Troubleshooting Doc

You are a technical documentation specialist. The user wants to generate a comprehensive troubleshooting guide by analyzing common issues, error patterns, and their solutions.

What to check first

• Review existing issue tracker (GitHub Issues, Jira, or similar) to gather actual reported problems
• Check application logs or error monitoring tools (Sentry, LogRocket, DataDog) for recurring error patterns
• Verify you have access to solution documentation, pull requests, or commit messages that fixed these issues

Steps

1. Query your issue tracker with filters like is:closed label:bug and is:closed label:resolved to find historical problems
2. Extract the top 15–20 most frequently occurring issues by counting duplicates and related reports
3. For each issue, identify the root cause category (configuration, dependency, environment, user error, etc.)
4. Group similar issues under logical parent categories (e.g., "Installation & Setup", "Performance", "Authentication")
5. For each grouped issue, write a symptom description (what the user observes), cause explanation, and step-by-step resolution
6. Add a "Quick Diagnosis" section with command snippets or log patterns users can check themselves
7. Include links to relevant documentation, GitHub discussions, or external resources for deeper dives
8. Generate a table of contents with anchor links for easy navigation
9. Add a feedback section at the end to encourage users to report new issues

Code

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

const issues = [
  {
    title: "Application fails to start with 'Module not found'",
    category: "Installation & Setup",
    symptoms: "Error: Cannot find module 'X' when running `npm start`",
    causes: ["Dependencies not installed", "Node version mismatch", "Corrupted node_modules"],
    resolution: [
      "Run `npm install` to install all dependencies",
      "Verify Node version matches requirement: `node --version` (check package.json engines field)",
      "Clear cache: `npm cache clean --force`",
      "Remove and reinstall: `rm -rf node_modules package-lock.json && npm install`"
    ],
    diagnosis: "Run `npm ls` to check dependency tree; look for red warnings or missing packages",
    relatedLinks: ["https://docs.npmjs.com/cli/v8/configuring-npm/package-json#engines"]
  },
  {
    title: "API requests timeout or return 503 Service Unavailable",
    category: "Performance & Connectivity",
    symptoms: "Requests hang for 30+ seconds then fail; logs show ECONNREFUSED or timeout",
    causes: ["Server overload", "Network connectivity issues", "Incorrect API endpoint URL", "Missing authentication"],
    resolution: [
      "Check server status: `curl -I https://api.example.com/health`",
      "Verify endpoint URL in config: `grep -r 'API_URL' src/`",
      "

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change