debug-like-expert

Files (6)

• SKILL.md
• debugging-mindset.md · references/
• hypothesis-testing.md · references/
• investigation-techniques.md · references/
• verification-patterns.md · references/
• when-to-research.md · references/

SKILL.md (first lines)

<objective>
Deep analysis debugging mode for complex issues. This skill activates methodical investigation protocols with evidence gathering, hypothesis testing, and rigorous verification when standard troubleshooting has failed.

The skill emphasizes treating code you wrote with MORE skepticism than unfamiliar code, as cognitive biases about "how it should work" can blind you to actual implementation errors. Use scientific method to systematically identify root causes rather than applying quick fixes.
</objective>

<context>
This skill activates when standard troubleshooting has failed. The issue requires methodical investigation, not quick fixes. You are entering the mindset of a senior engineer who debugs with scientific rigor.

**Important**: If you wrote or modified any of the code being debugged, you have cognitive biases about how it works. Your mental model of "how it should work" may be wrong. Treat code you wrote with MORE skepticism than unfamiliar code - you're blind to your own assumptions.
</context>

<core_principle>
**VERIFY, DON'T ASSUME.** Every hypothesis must be tested. Every "fix" must be validated. No solutions without evidence.

**ESPECIALLY**: Code you designed or implemented is guilty until proven innocent. Your intent doesn't matter - only the code's actual behavior matters. Question your own design decisions as rigorously as you'd question anyone else's.
</core_principle>

<analysis_only_rule>
**THIS SKILL IS READ-ONLY. DO NOT MODIFY CODE.**

The entire purpose is deep analysis and diagnosis. Making changes during investigation:
- Pollutes the evidence
- Introduces new variables
- Makes root cause harder to isolate

You are a diagnostician, not a surgeon. Present findings, then let the user decide.
</analysis_only_rule>

<quick_start>

<evidence_gathering>

Before proposing any solution:

**A. Document Current State**
- What is the EXACT error message or unexpected behavior?
- What are the EXACT steps to reproduce?
- What is the ACTUAL output vs EXPECTED output?
- When did this start working incorrectly (if known)?

**B. Map the System**
- Trace the execution path from entry point to failure point
- Identify all components involved
- Read relevant source files completely, not just scanning
- Note dependencies, imports, configurations affecting this area

**C. Gather External Knowledge (when needed)**
- Use MCP servers for API documentation, library details, or domain knowledge
- Use web search for error messages, framework-specific behaviors, or recent changes
- Check official docs for intended behavior vs what you observe
- Look for known issues, breaking changes, or version-specific quirks

See [references/when-to-research.md](references/when-to-research.md) for detailed guidance on research strategy.

</evidence_gathering>

<root_cause_analysis>

**A. Form Hypotheses**

Based on evidence, list possible causes:
1. [Hypothesis 1] - because [specific evidence]
2. [Hypothesis 2] - because [specific evidence]
3. [Hypothesis 3] - because [specific evidence]

**B. Test Each Hypothesis**

For each hypothesis:
- What would prove this true?
- What would prove this false?
- Design a minimal test
- Execute and document results

See [references/hypothesis-testing.md](references/hypothesis-testing.md) for scientific method application.

**C. Eliminate or Confirm**

Don't move forward until you can answer:
- Which hypothesis is supported by evidence?
- What evidence contradicts other hypotheses?
- What additional information is needed?

</root_cause_analysis>

<solution_proposal>

**Only after confirming root cause:**

**A. Design Recommended Fix**
- What is the MINIMAL change that would address the root cause?
- What are potential side effects?
- What could this break?
- What tests should run after implementation?

**B. Document, Don't Implement**
- Describe the fix with enough detail for implementation
- Include specific file paths, line numbers, and code snippets
- Explain WHY this addresses the root cause
- Note any prerequisites or dependencies

**DO NOT make any code changes. Present your recommendations only.**

See [references/verification-patterns.md](references/verification-patterns.md) for verification approaches to use after implementation.

</solution_proposal>

</quick_start>

<critical_rules>

1. **NO DRIVE-BY FIXES**: If you can't explain WHY a change works, don't make it
2. **VERIFY EVERYTHING**: Test your assumptions. Read the actual code. Check the actual behavior
3. **USE ALL TOOLS**:
   - MCP servers for external knowledge
   - Web search for error messages, docs, known issues
   - Extended thinking ("think deeply") for complex reasoning
   - File reading for complete context
4. **THINK OUT LOUD**: Document your reasoning at each step

From mkurman/zorai, MIT.

More from mkurman/zorai