Diagnose
Disciplined diagnosis loop for hard bugs and unexpected behavior. Forces reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when something is broken and you don't know why, when a bug seems intermittent, when a fix didn't work, or when user says diagnose, debug, investigate, or "why is this broken".From its SKILL.md
npx -y skills add Adit-Jain-srm/skill-forge --skill diagnoseAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.9 KB, 629 tokens by cl100k_base, as published. Nobody here has run it
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.
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.
Gives 1 of the 12 instructions most debug triage skills give in 629 tokens
Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06
- Find root cause before attempting any fixin 134 of 1020, across 118 files
- Create a failing test case before implementing a fixin 109 of 1020, across 95 files
- Read error messages and stack traces completelyin 102 of 1020, across 88 files
- Reproduce the issue consistently before investigatingin 90 of 1020, across 77 files
- Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
- Trace data flow backward to find the sourcein 84 of 1020, across 70 files
- Form a single hypothesis before testingin 78 of 1020, across 64 files
- Implement only one fix at a timein 76 of 1020, across 63 files
- Question the architecture if three fixes failin 73 of 1020, across 59 files
- Add diagnostic instrumentation at component boundariesin 68 of 1020, across 56 files
- Compare broken code against working examplesin 68 of 1020, across 57 files
- Write a regression test before applying the fixhere, and in 62 of 1020, across 55 files
Said here and by no other author read
- run the regression test red then green
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.