Diagnose

Overview

Systematic debugging that produces evidence at every step — not guesswork, not shotgun fixes.

Process

Do NOT guess. Follow the loop. Every step produces evidence.

The Loop

1. REPRODUCE — make it fail on demand. If you can't reproduce, you can't fix.
2. MINIMISE — strip everything until only the bug remains. Smallest failing case.
3. HYPOTHESISE — ONE theory. Not three. One. State it clearly.
4. INSTRUMENT — add the ONE measurement that proves/disproves your hypothesis.
5. EVALUATE — run it. Was hypothesis correct?
   YES → go to step 6
   NO  → back to step 3 with new information
6. FIX — minimal change that addresses root cause (not symptoms)
7. REGRESSION TEST — write a test that would have caught this. Run it red then green.

Rules

• Never skip REPRODUCE. "I think it fails when..." is not reproducing.
• Never fix without a hypothesis. Shotgun debugging = wasted time.
• One hypothesis at a time. Changing two things = you learn nothing.
• The fix must address ROOT CAUSE. If you're fixing symptoms, you're not done.
• The regression test must FAIL without the fix applied.

Anti-Patterns (stop yourself)

• "Let me try adding a null check here" → NO. Where's your hypothesis? What evidence?
• "It's probably a timing issue" → Probably? REPRODUCE it. PROVE it's timing.
• "I'll add some console.logs" → WHICH log proves WHICH hypothesis? Be specific.
• "Fixed! (without running the test)" → NO. Prove it. Run it. Evidence.

Common Mistakes

• Changing two things at once — you learn nothing about which fixed it
• "Probably" without evidence — reproduce it or it's speculation
• Fixing symptoms (adding null checks) instead of root causes (why was it null?)
• Declaring "fixed" without a regression test proving it

Example

Bug: "Login button sometimes doesn't respond"

1. REPRODUCE: Click login 20 times → fails on attempts 7, 14, 19 (pattern?)
2. MINIMISE: Remove all other UI. Just the button + handler. Still fails.
3. HYPOTHESISE: "Event listener is being attached multiple times on re-render"
4. INSTRUMENT: Add counter in useEffect → logs show 3 listeners after 3 renders
5. EVALUATE: Hypothesis confirmed. Missing cleanup in useEffect.
6. FIX: Add return () => btn.removeEventListener(...) in useEffect
7. REGRESSION TEST: test('login handler attaches exactly once after re-renders')

Persistence

ACTIVE whenever debugging. Stay in the loop until the regression test is green. Don't exit early. Don't declare "fixed" without step 7.

Source & license

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

• Author: Adit-Jain-srm
• Source: Adit-Jain-srm/skill-forge
• License: MIT
• Homepage: https://github.com/Adit-Jain-srm/skill-forge#quick-start

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