# Bug Diagnosis

> Structured bug diagnosis producing a written diagnosis document before any fix is attempted. Use when the user reports a bug, asks to investigate why something fails, says diagnose this bug, find the root cause, figure out why X broke, or when a bug is non-obvious, intermittent, or survived previous fix attempts. Pairs with systematic-debugging (the discipline) and backprop (recurrence prevention).

- Skill: `hongyime/bug-diagnosis` (Agent Skill)
- Install (CLI): `npx get-skill add hongyime/bug-diagnosis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hongyime/bug-diagnosis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: hongyime (https://skillmd.com/u/hongyime)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/hongyime/bug-diagnosis

---


# 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

1. No fix code until the diagnosis document exists and states a root cause with
   evidence.
2. Every claim in the diagnosis cites observed evidence (log line, command
   output, repro step), not inference alone.
3. If evidence contradicts the hypothesis, update the hypothesis, not the
   evidence.
4. 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:

1. Read the full error message, stack trace, log context. Never skim.
2. Check recent diffs: `git log --oneline -15`, `git diff HEAD~3` for suspects.
3. For multi-layer systems (client -> API -> service -> DB), instrument each
   boundary once: what enters, what exits. Run once, read where truth diverges.
4. Note environment deltas: versions, env vars, config, OS, paths.

On Windows/PowerShell, capture evidence as text so it can be quoted in the
diagnosis:

```powershell
command 2>&1 | Out-String | Set-Content "$env:TEMP\evidence-01.txt"
```

On Debian/Linux (bash):

```bash
command > /tmp/evidence-01.txt 2>&1
```

### 3. Form And Test Hypotheses

One hypothesis at a time. State it as:

> Hypothesis H1: <cause> because <evidence>. Prediction: if true, <cheap test>
> will show <result>.

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):

```markdown
# 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

