gh-towry-dots-conf-claude-local-marketplace/skills/debugger/SKILL.md

name, description

name	description
debugger	Systematically trace bugs backward through call stack to find the original trigger. Use this skill when user wants to debug complex issues or has a bug that is hard to spot; user says "not working" and you are debugging an issue.

When to use

• User is frustrated about your attempts
• Bugs are vague and not easy to spot
• User says debug this or debug it something like that

Tools, subagents, skills that might be helpful

• Critical: fast-repo-context claude skill for fast codebase search and analysis, this is highly recommended to use, load it with Skill tool; Can use it to search on current project or other projects.
• kg knowledge graph search
• load git-jj claude skill for vcs operations (logs, blame, diff etc), use bash ~/.claude/skills/git-jj/scripts/repo_check.sh to check repo is jj or git managed.
  • Debugging-specific commands:
    • git blame <file> / jj file annotate <file> - find who changed a line and when
    • git log -p <file> / jj log -p <file> - see all changes to a specific file
    • git bisect - binary search for the commit that introduced a bug
    • git diff <a>..<b> / jj diff -r <a>..<b> - compare specific revisions
    • jj log -r "file('path')" - find commits that touched a file
• outbox subagent for high level debugging ideas and strategies; Invoke the Task tool with outbox.
• oracle subagent for advanced reasoning about complex issues, decision making; Invoke the Task tool with oracle.
• brightdata mcp tool: use it to search on the web for similar issues, error messages, stack traces.
• github mcp tool: use it to search library related issues in github issues.
• Other command tools that you already know
• As a last resort, run claude --model openrouter/anthropic/claude-opus-4.5 -p "<detailed prompt about the issue>" --tools "Read,Grep,Glob" for help from the most advanced SWE LLM. This is expensive, so use it wisely and compose the prompt carefully.

When to use git history for debugging

Use git history when:

• Regression bugs: User says "it worked before" or "it broke after update"
• Unknown code changes: You find suspicious code but don't understand why it was written that way
• Recent breakage: Bug appeared recently and might correlate with recent commits
• Blame investigation: Need to find the original author/context of problematic code

Skip git history when:

• Bug is clearly a logic error in current code
• Issue is configuration or environment related
• User confirms this is new code, not a regression

Debugging process

1. Understand the issue/bug
2. Fetch context with fast-repo-context skill of the codebases. Use kg to search the knowledge graph in case we solved this before. Use fast-repo-context skill(recommended) or rg bash tool to search the codebases with possible keywords, and read comments or documents.
3. Review available tools and subagents (fd, rg, kg, git, etc.)
4. Start debugging iterations - Each iteration MUST be explicitly labeled (e.g., "Iteration 1", "Iteration 2")
   • 4.1 Get debugging ideas from outbox subagent with context from steps 2 and 3. Include the tools and subagents you have and what they do, so outbox can give advice based on your available tools.
   • 4.2 Check git history (if applicable): Use git-jj skill to investigate version history when the bug might be a regression. Run blame on suspicious lines, check recent file changes, or use bisect to find the breaking commit. See "When to use git history" section above.
   • 4.3 Follow instructions from outbox, trace back to the root cause of the bug/issue
   • 4.4 Propose a fix or the root of cause to user, let user review it.
   • 4.5 Apply the fix if user agrees.
   • 4.5 Ask user to confirm the fix
5. Iterate Step 4 until user has confirmed the bug/issue is resolved. Keep key findings from each iteration and feed all findings and attempted methods to outbox for the next iteration.

Iteration tracking

• Always announce iteration number at the start: "Iteration N: Trying X approach..."
• Keep a mental log of what was tried in each iteration
• When consulting outbox after iteration 1, always include findings from ALL previous iterations

Outbox prompt template

Note: outbox is a readonly/thinking agent. It cannot use tools (no Read, Write, Execute). It can only reason and advise. You must provide all relevant context in the prompt.

First iteration:

**Bug**: <one-line description>
**Symptoms**: <what user observed, error messages>
**Relevant files**: <file paths found in step 2>
**Code context**: <brief snippet or description of suspicious area>

**Available tools** (I can execute these):
- rg, fd (search)
- kg (knowledge graph - check past solutions)
- git-jj (blame, file history, bisect, diff)
- Read, Grep, Glob (file inspection)
- Execute (run commands, add logs)

**Ask**: Given this bug and these tools, what debugging strategy should I follow? Provide specific actionable steps. At the end of your advice, include a "feedback request" like: "If this doesn't work, tell me [specific info] for next iteration."

Subsequent iterations:

**Iteration**: N (where N > 1)

**Bug**: <one-line description>
**Symptoms**: <what user observed, error messages>
**Relevant files**: <file paths>
**Code context**: <brief snippet or description of suspicious area>

**Available tools** (I can execute these):
- rg, fd (search)
- kg (knowledge graph - check past solutions)
- git-jj (blame, file history, bisect, diff)
- Read, Grep, Glob (file inspection)
- Execute (run commands, add logs)

**What I tried**: <methods attempted in previous iterations>
**Findings**: <key observations, what was ruled out>
**Current hypothesis**: <if any>

**Ask**: Based on findings, what should I try next? At the end of your advice, include a "feedback request" like: "If this doesn't work, tell me [specific info] for next iteration."

Notes

• kg should be used for finding key information related to the issues. Do not use it to save unverified debugging assumptions. After user confirms the fix, you can ask whether to save the fix to the knowledge graph.
• You have advanced tools, subagents and skills to debug complex issues. Do not hesitate to use them.

Real world example

The tree city picker does nothing when I click the input I will gather the code modules related to this issue...

next phase

Ok, I have located the files. Now let me check what tools and subagents might help me debug this issue, and ask outbox subagent for ideas.

next phase

Iteration 1: Following outbox advice, I'll check the click handler binding...

tried approach, didn't work

Iteration 2: The click handler exists but event propagation might be blocked. Let me trace the event flow...

found something suspicious

Iteration 3: Found it! The parent container has pointer-events: none. Here is the fix...

Hi, here is the root cause of this issue/bug:

-- omit for demo

Please confirm it.

great work!