Debug

Overview

This skill applies a systematic debugging methodology inspired by medical differential diagnosis. It provides a rigorous 7-step process for investigating and resolving bugs through observation, classification, hypothesis testing, and verification. This approach prioritizes evidence-based reasoning over assumptions, ensuring root causes are identified rather than symptoms treated.

When to Use This Skill

Activate this skill in two primary scenarios:

Scenario A: Post-Modification Anomalies When modifying a previously tested and working version, and any unexpected behavior emerges after the changes.

Scenario B: User-Reported Issues When users report that test results don't meet expectations or the system fails to execute as intended.

Debugging Workflow

Follow this 7-step systematic approach to diagnose and resolve issues.

For a detailed checklist of each step, refer to {baseDir}/references/debugging_checklist.md. For common bug patterns and their signatures, see {baseDir}/references/common_patterns.md.

Step 1: Observe Without Preconception (Observe)

Objective: Collect all available evidence without jumping to conclusions.

Process:

• Gather all accessible clues: user reports, system logs, dashboards, error stack traces, version changes (git diff), configuration parameters (configs/args/env)
• Focus exclusively on facts and observable phenomena
• Avoid premature hypotheses or assumptions about causes
• Document all observations systematically

Key Principle: Observe, don't just see. At this stage, the goal is comprehensive data collection, not interpretation.

Step 2: Classify and Isolate Facts (Classify & Isolate Facts)

Objective: Distinguish symptoms from root causes and narrow the problem scope.

Process:

For Incremental Development (Scenario A - Post-Modification Anomalies):

• Confirm the previous step still works (ensure issue is from new changes)
• List ALL changes since last working state (git diff, code modifications, config changes)
• Identify implicit assumptions in these changes, such as:
  • API calling conventions ("I assume this API works this way")
  • Parameter types/order ("I assume this parameter accepts X")
  • Configuration values ("I assume this env var is set")
  • Data formats ("I assume the response is JSON")
  • [And other fundamental assumptions embedded in the changes]
• Apply Occam's Razor: The simplest explanation is usually correct—prioritize basic assumption errors (typos, wrong parameters, incorrect API usage) over complex failure modes
• Verify fundamental assumptions with this priority:
  1. Check how it was implemented in the last working version (proven to work)
  2. Consult official documentation for correct usage (may be outdated)
  3. Only then consider external issues (community-reported bugs, known issues)

General Isolation:

• Separate "what is broken" (symptoms) from "why it's broken" (causes)
• Systematically narrow down the problem domain by testing:
  • Does it occur only in specific browsers?
  • Does it happen on specific operating systems?
  • Is it time-dependent?
  • Is it triggered by specific parameter values or input data?
• Eliminate all modules/components that function correctly
• Isolate the suspicious area

Key Principle: Reduce the search space by eliminating what works correctly.

Step 3: Build Differential Diagnosis List (Differential Diagnosis List)

Objective: Enumerate all possible technical failure points.

Process:

• Create a comprehensive list of potential failure modes:
  • Cache errors
  • Database connection failures
  • Third-party API outages
  • Memory leaks
  • Configuration anomalies
  • Version compatibility issues
  • Race conditions
  • Resource exhaustion
• Include even rare or unlikely scenarios
• Draw on knowledge base and past experiences
• Consider both common and edge cases
• Consult {baseDir}/references/common_patterns.md for known bug patterns

Key Principle: Cast a wide net initially—don't prematurely exclude possibilities.

Step 4: Apply Elimination and Deductive Reasoning (Deduce & Exclude)

Objective: Systematically eliminate impossible factors to find the truth.

Process:

• Follow Sherlock Holmes' principle: "When you eliminate the impossible, whatever remains, however improbable, must be the truth"
• Design precise tests to validate or invalidate each hypothesis
• Use Chain-of-Thought reasoning to document the deductive process
• Make reasoning transparent and verifiable
• Progressively eliminate factors until a single root cause remains

Key Principle: Evidence-based elimination leads to certainty.

Step 5: Experimental Verification and Investigation (Experimental Verification)

Objective: Validate hypotheses through controlled experiments.

Process:

• Create restorable checkpoints before making changes
• Design and execute targeted experiments to test remaining hypotheses
• Research latest versions, known issues, and community discussions (GitHub issues, Stack Overflow)
• Conduct focused verification tests
• Use experimental evidence to prove each logical step
• Iterate until the exact cause is confirmed

Key Principle: Prove hypotheses with experiments, not assumptions.

Step 6: Locate and Implement Fix (Locate & Implement Fix)

Objective: Apply the most elegant and least invasive solution.

Process:

• Pinpoint the exact code location or configuration causing the issue
• Design the fix with minimal side effects
• Prioritize elegant solutions over quick patches
• Consider long-term maintainability
• Implement the fix with precision

Key Principle: Seek elegant solutions, not temporary workarounds.

Step 7: Prevention Mechanism (Prevent)

Objective: Ensure the same error doesn't recur and verify stability.

Process:

• Verify all related modules remain stable after the fix
• Run comprehensive regression tests
• Review the entire debugging process
• Generalize lessons learned
• Document findings in CLAUDE.md or project documentation
• Implement safeguards to prevent similar issues

Key Principle: Fix once, prevent forever.

Best Practices

Maintain Scientific Rigor:

• Bold hypotheses, careful verification
• Evidence before assertions
• Transparency in reasoning

Documentation:

• Track all observations, hypotheses, and test results
• Make the investigation reproducible
• Document not just the fix, but the reasoning process
• Use {baseDir}/references/investigation_template.md to structure investigation logs
• Use {baseDir}/assets/debug_report_template.md for creating post-mortem reports

Communication:

• Explain findings clearly to users
• Provide context for why the issue occurred
• Describe preventive measures implemented

Resources

This skill includes bundled resources to support the debugging workflow:

references/

Load these into context as needed during investigation:

• {baseDir}/references/debugging_checklist.md - Comprehensive checklist for each debugging step
• {baseDir}/references/common_patterns.md - Common bug patterns and their signatures
• {baseDir}/references/investigation_template.md - Template for documenting investigations

assets/

Use these templates for documentation and reporting:

• {baseDir}/assets/debug_report_template.md - Template for summarizing debugging sessions and creating post-mortem reports