Bug Diagnosis
Diagnose bugs by producing an evidence-based diagnosis document BEFORE proposing
or writing any fix. The deliverable of this skill is the diagnosis; fixing is a
separate decision.
When To Use
- User reports a bug and wants to understand it first
- A bug survived one or more failed fix attempts
- The failure is intermittent, environmental, or multi-layer
- The user explicitly asks for root cause, diagnosis, or investigation
For simple obvious breaks, systematic-debugging discipline alone is enough.
Use this skill when the diagnosis itself needs structure and persistence.
Iron Rules
- No fix code until the diagnosis document exists and states a root cause with
evidence.
- Every claim in the diagnosis cites observed evidence (log line, command
output, repro step), not inference alone.
- If evidence contradicts the hypothesis, update the hypothesis, not the
evidence.
- Fix the fault, not the place where it surfaced. The symptom is where a
wrong state became visible; the root cause is the first place the system
did something it should not do, or failed to handle a state it should
handle. A guard is a fix only when the state it handles is legitimate;
if the state should never exist, the check hides the bug. Check for the
pattern, not just the instance.
Workflow
1. Capture The Symptom Contract
Write down, before investigating:
| Field |
Question |
| Expected |
What should happen |
| Observed |
What actually happens |
| Scope |
Always? Sometimes? One machine? One user? |
| Onset |
When did it start; what changed around then |
| Repro |
Exact steps or inputs that trigger it |
If you cannot reproduce it, say so and gather data instead of guessing.
2. Collect Evidence
Work outward from the error site:
- Read the full error message, stack trace, log context. Never skim.
- Check recent diffs:
git log --oneline -15, git diff HEAD~3 for suspects.
- For multi-layer systems (client -> API -> service -> DB), instrument each
boundary once: what enters, what exits. Run once, read where truth diverges.
- Note environment deltas: versions, env vars, config, OS, paths.
On Windows/PowerShell, capture evidence as text so it can be quoted in the
diagnosis:
command 2>&1 | Out-String | Set-Content "$env:TEMP\evidence-01.txt"
On Debian/Linux (bash):
command > /tmp/evidence-01.txt 2>&1
3. Form And Test Hypotheses
One hypothesis at a time. State it as:
Hypothesis H1: because . Prediction: if true,
will show .
Run the cheapest discriminating test. Record result. Move to next hypothesis or
confirm. After 2+ failed fix attempts on the same symptom, stop and re-diagnose;
three failures usually means wrong layer or wrong architecture assumption.
4. Write The Diagnosis Document
Save as .agents/diagnosis/YYYY-MM-DD-<slug>.md (create folder if needed):
# Diagnosis: <short title>
Date: YYYY-MM-DD | Repo: <path> | Status: CONFIRMED | SUSPECTED | BLOCKED
## Symptom Contract
(expected / observed / scope / onset / repro)
## Evidence
1. <fact> — source: <log/command/file + line>
2. ...
## Root Cause
<Plain statement of cause.>
## Why It Was Not Obvious
<What misled earlier attempts, if any.>
## Fix Options
| Option | Changes | Risk | Recommendation |
## Verification Plan
How we will prove the fix works and did not break neighbors.
## Recurrence Guard
Should this become an invariant/test? If yes -> hand to `backprop` / spec §V.
5. Hand Off
| Situation |
Next |
| Fix agreed |
implement per Verification Plan (build skill if SPEC-driven) |
| Recurring class of bug |
backprop to add a §V invariant |
| Ambiguity about intended behavior |
ask user before coding |
| Fix is large/multi-part |
to-spec or to-tickets |
Guardrails
- Do not write fix code while diagnosing. Diagnostic instrumentation only.
- Do not delete or "clean up" anything mid-diagnosis; preserve the crime scene.
- Do not present an unconfirmed hypothesis as fact; mark status honestly.
- Time-box rabbit holes: after ~30 minutes without new evidence, report findings
and blockers to the user.
Related Skills
systematic-debugging - the four-phase discipline this skill documents output for
backprop - turn confirmed root causes into recurrence-preventing invariants
to-spec, to-tickets - hand off large fixes
1---2name: bug-diagnosis3description: >-4 Structured bug diagnosis producing a written diagnosis document before any5 fix is attempted. Use when the user reports a bug, asks to investigate why6 something fails, says diagnose this bug, find the root cause, figure out why7 X broke, or when a bug is non-obvious, intermittent, or survived previous fix8 attempts. Pairs with systematic-debugging (the discipline) and backprop9 (recurrence prevention).10license: MIT11metadata:12 source: https://skillmd.com/skills/hongyime/bug-diagnosis13 author: Local setup14 version: "1.0.0"15 platform: "Codex, Antigravity (agy), OpenCode, Muse on Windows, macOS, Linux (Debian)"16---1718# Bug Diagnosis1920Diagnose bugs by producing an evidence-based diagnosis document BEFORE proposing21or writing any fix. The deliverable of this skill is the diagnosis; fixing is a22separate decision.2324## When To Use2526- User reports a bug and wants to understand it first27- A bug survived one or more failed fix attempts28- The failure is intermittent, environmental, or multi-layer29- The user explicitly asks for root cause, diagnosis, or investigation3031For simple obvious breaks, `systematic-debugging` discipline alone is enough.32Use this skill when the diagnosis itself needs structure and persistence.3334## Iron Rules35361. No fix code until the diagnosis document exists and states a root cause with37 evidence.382. Every claim in the diagnosis cites observed evidence (log line, command39 output, repro step), not inference alone.403. If evidence contradicts the hypothesis, update the hypothesis, not the41 evidence.424. Fix the fault, not the place where it surfaced. The symptom is where a43 wrong state became visible; the root cause is the first place the system44 did something it should not do, or failed to handle a state it should45 handle. A guard is a fix only when the state it handles is legitimate;46 if the state should never exist, the check hides the bug. Check for the47 pattern, not just the instance.4849## Workflow5051### 1. Capture The Symptom Contract5253Write down, before investigating:5455| Field | Question |56|---|---|57| Expected | What should happen |58| Observed | What actually happens |59| Scope | Always? Sometimes? One machine? One user? |60| Onset | When did it start; what changed around then |61| Repro | Exact steps or inputs that trigger it |6263If you cannot reproduce it, say so and gather data instead of guessing.6465### 2. Collect Evidence6667Work outward from the error site:68691. Read the full error message, stack trace, log context. Never skim.702. Check recent diffs: `git log --oneline -15`, `git diff HEAD~3` for suspects.713. For multi-layer systems (client -> API -> service -> DB), instrument each72 boundary once: what enters, what exits. Run once, read where truth diverges.734. Note environment deltas: versions, env vars, config, OS, paths.7475On Windows/PowerShell, capture evidence as text so it can be quoted in the76diagnosis:7778```powershell79command 2>&1 | Out-String | Set-Content "$env:TEMP\evidence-01.txt"80```8182On Debian/Linux (bash):8384```bash85command > /tmp/evidence-01.txt 2>&186```8788### 3. Form And Test Hypotheses8990One hypothesis at a time. State it as:9192> Hypothesis H1: <cause> because <evidence>. Prediction: if true, <cheap test>93> will show <result>.9495Run the cheapest discriminating test. Record result. Move to next hypothesis or96confirm. After 2+ failed fix attempts on the same symptom, stop and re-diagnose;97three failures usually means wrong layer or wrong architecture assumption.9899### 4. Write The Diagnosis Document100101Save as `.agents/diagnosis/YYYY-MM-DD-<slug>.md` (create folder if needed):102103```markdown104# Diagnosis: <short title>105106Date: YYYY-MM-DD | Repo: <path> | Status: CONFIRMED | SUSPECTED | BLOCKED107108## Symptom Contract109(expected / observed / scope / onset / repro)110111## Evidence1121. <fact> — source: <log/command/file + line>1132. ...114115## Root Cause116<Plain statement of cause.>117118## Why It Was Not Obvious119<What misled earlier attempts, if any.>120121## Fix Options122| Option | Changes | Risk | Recommendation |123124## Verification Plan125How we will prove the fix works and did not break neighbors.126127## Recurrence Guard128Should this become an invariant/test? If yes -> hand to `backprop` / spec §V.129```130131### 5. Hand Off132133| Situation | Next |134|---|---|135| Fix agreed | implement per Verification Plan (`build` skill if SPEC-driven) |136| Recurring class of bug | `backprop` to add a §V invariant |137| Ambiguity about intended behavior | ask user before coding |138| Fix is large/multi-part | `to-spec` or `to-tickets` |139140## Guardrails141142- Do not write fix code while diagnosing. Diagnostic instrumentation only.143- Do not delete or "clean up" anything mid-diagnosis; preserve the crime scene.144- Do not present an unconfirmed hypothesis as fact; mark status honestly.145- Time-box rabbit holes: after ~30 minutes without new evidence, report findings146 and blockers to the user.147148## Related Skills149150- `systematic-debugging` - the four-phase discipline this skill documents output for151- `backprop` - turn confirmed root causes into recurrence-preventing invariants152- `to-spec`, `to-tickets` - hand off large fixes