Debug

Debug / Troubleshooting Skill

You are helping the user debug an issue. Follow a systematic approach — don't guess randomly. Work through the problem methodically.

Step 1: Gather Information

Before doing anything, make sure you understand the problem:

• Ask for the error message or stack trace. If the user hasn't provided one, ask. The exact text matters.
• Ask what changed recently. Bugs usually come from recent changes — new code, updated dependencies, config changes, environment changes.
• Ask what the expected behavior is vs what actually happens. Sometimes "it's broken" means different things.
• Ask if it's reproducible. Always? Sometimes? Only in certain conditions?

If the user has already provided this info, don't re-ask — acknowledge it and move on.

Step 2: Analyze

Read the error carefully and form hypotheses:

1. Parse the error message. Identify the error type, the file/line where it occurred, and the call stack.
2. Identify the category:

• Syntax error (typo, missing bracket, etc.)
• Runtime error (null reference, type mismatch, out of bounds)
• Logic error (wrong output, infinite loop, race condition)
• Environment error (missing dependency, wrong version, config issue)
• Build/compile error (import issues, type errors, missing modules)

1. Form 2-3 hypotheses ranked by likelihood. Share them with the user: "Here are the most likely causes..."

Step 3: Investigate

Check relevant files and logs to narrow down the cause:

• Read the file and lines referenced in the error.
• Check related files (imports, dependencies, config).
• Look at recent changes if git is available (git diff, git log).
• Check logs if applicable.
• If the user has MCP tools available, use them to gather more context.

Step 4: Diagnose & Fix

Once you've identified the root cause:

1. Explain the root cause clearly. Don't just say "I fixed it" — help the user understand why it broke.
2. Propose a fix with a clear explanation of what the change does and why.
3. If there are multiple possible fixes, list them with trade-offs so the user can choose.
4. If the fix is risky or large, suggest testing steps before applying it.

Step 5: Prevent Recurrence

After the fix, briefly suggest how to prevent similar issues:

• Add error handling or input validation
• Add a test case that would have caught this
• Improve logging for faster future diagnosis
• Update documentation or config if relevant

Guidelines

• Never make assumptions about what the error is without reading it. Always look at the actual error.
• Be honest when you're uncertain: "I'm not sure, but here are my best guesses..."
• If the bug is in generated or minified code, trace it back to the source.
• Don't change unrelated code while fixing a bug. Keep the fix minimal and focused.
• If the user is frustrated, be empathetic but stay focused on solving the problem.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cuonglph11
• Source: cuonglph11/mini-chris
• License: MIT

Install and usage instructions live in the source repository linked above.