# Trace Bug

> Diagnose and fix a reproducible defect by starting from the end-user failure, tracing evidence across boundaries, testing competing hypotheses, and adding a regression test. Use for bugs, flaky behavior, and unexplained test failures. Do not use for feature design.

- Skill: `leihuang23/trace-bug-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add leihuang23/trace-bug-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leihuang23/trace-bug-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: leihuang23 (https://skillmd.com/u/leihuang23)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leihuang23/trace-bug-2

---


# Trace Bug

The first task is to reproduce what the user experiences, not to patch the first suspicious line.

## Workflow

1. Capture the report, environment, expected behavior, observed behavior, frequency, and impact.
2. Reproduce the defect end to end as closely as possible to the user path. Preserve the command, inputs, logs, screenshot, or trace.
3. If it does not reproduce, vary one dimension at a time: data, timing, permissions, platform, locale, network, cache, concurrency, or version.
4. Build a hypothesis ledger before editing.
5. Instrument or inspect the boundary that most efficiently separates competing hypotheses.
6. Identify the first point where actual state diverges from expected state.
7. Add a regression test that fails for the root cause, not just the visible symptom.
8. Apply the smallest root-cause fix. Avoid unrelated refactors until green.
9. Re-run the end-user reproduction, regression, relevant suites, and adjacent failure modes.
10. Remove diagnostic code and review the final diff.

## Hypothesis ledger

```markdown
| Hypothesis | Prediction | Discriminating check | Result | Status |
| --- | --- | --- | --- | --- |
```

Statuses: `untested`, `supported`, `rejected`, `root-cause`, `contributing`.

## Flake discipline

- Preserve seed, order, timing, machine, retries, and pass/fail history.
- A retry is diagnostic evidence, not a fix.
- Do not add sleeps when an observable condition can be awaited.
- Distinguish product nondeterminism, test pollution, environmental variance, and insufficient assertions.

## Stop rules

- Do not change production code before a credible reproduction or a clearly documented substitute exists.
- Do not broaden the fix beyond the causal chain without new evidence.
- If evidence contradicts the original report, report the contradiction instead of forcing a diagnosis.

## Evidence packet

Return reproduction, root cause, rejected hypotheses, regression test, fix, verification commands and outcomes, adjacent risks, and any environment where the defect remains untested.