Bugfix spec
Not every fix deserves a full feature spec — but every fix deserves an investigation with a paper trail. This template turns "fix the bug" into reproduction, hypothesis, strategy, and regression proof.
Production incidents, regressions, and any bug where the cause isn't obvious from the report. Skip it only for typos and one-line fixes whose cause is self-evident. If the same bug has been "fixed" twice before, you needed this template the first time.
Section-by-section, annotated
§1 Bug report summary
The report distilled: what happens, what should happen, environment, frequency. Severity and priority are separate fields — severity is technical, priority is business. Good looks like: anyone can reproduce the wrong behavior from this section alone.
§2 Reproduction steps
Exact, numbered steps that trigger the bug reliably, with expected vs. actual at each step. If you can't reproduce it, you can't verify the fix. Good looks like: a script or test that fails right now.
§3 Impact assessment
Who is affected, how many, how badly, and for how long. This section sets the urgency and justifies the fix's scope — a sev-1 gets a different strategy than a cosmetic glitch. Good looks like: numbers, not adjectives.
§4 Root-cause hypothesis
The leading theory of why this happens, plus how you'll confirm or rule it out. Writing the hypothesis down is what separates debugging from guessing. Good looks like: a falsifiable statement and a planned experiment.
§5 Fix strategy
What will change, what will pointedly not change, and why this addresses the cause rather than the symptom. Includes alternatives considered and rejected. Good looks like: the smallest change that fixes the cause, with the blast radius stated.
§6 Regression tests
Tests that fail on the current code and pass after the fix — the lock that keeps the bug from returning. Also: adjacent areas that need re-verification. Good looks like: at least one automated test per root cause.
§7 Rollout & verification
How the fix ships, what to monitor, and the criteria for declaring the bug dead. For data-corrupting bugs: whether affected data needs repair. Good looks like: a monitoring query you can run the morning after deploy.
Copy it, investigate, fix
# Bugfix Spec: [Short bug title] | Field | Value | |----------|--------------------| | Owner | [Name] | | Status | Triaged / Investigating / Fixing / Verifying / Done | | Severity | [S1 critical – S4 cosmetic] | | Priority | [P1 – P4] | | Reported | [YYYY-MM-DD] | ## Revision block | Rev | Date | Author | Description | |-----|------------|--------|------------------------| | 0.1 | [YYYY-MM-DD] | [Name] | Triage and reproduction | ## 1. Summary - **Observed:** [What happens, concretely] - **Expected:** [What should happen] - **Environment:** [Version, platform, config where seen] ## 2. Reproduction steps 1. [Exact step] 2. [Exact step] 3. **Observe:** [The wrong behavior] - **Reproducibility:** [Always / intermittent — X% of attempts] - **Repro script/test:** [Link or snippet that fails right now] ## 3. Impact assessment - **Who is affected:** [User segment, internal team, ...] - **Scale:** [Rough numbers: requests/day, users, revenue at risk] - **Duration:** [When it started; still ongoing?] - **Workarounds:** [Any; and their cost] ## 4. Root-cause hypothesis **Leading theory:** [Why this happens, in one or two sentences.] **Evidence so far:** - [Log line, stack trace excerpt, or observation] **How to confirm or rule out:** - [ ] [Experiment / query / bisect step] **Alternative theories (ruled out):** - [Theory] — ruled out because [reason] ## 5. Fix strategy **Change:** [What will change, file/component level.] **Will not change:** [Adjacent code deliberately left alone, and why.] **Why this fixes the cause, not the symptom:** [One paragraph.] **Alternatives considered:** - [Alternative] — rejected because [reason] **Blast radius:** [What else could this change affect?] ## 6. Regression tests - [ ] [Test 1: fails now, passes after fix] - [ ] [Test 2: covers the adjacent edge case] **Areas to re-verify:** [Features touching the changed code.] ## 7. Rollout and verification - **Ship plan:** [Normal deploy / hotfix / flagged rollout] - **Monitoring:** [Query or dashboard to watch post-deploy] - **Done when:** [The criterion that declares this bug dead] - **Data repair needed?** [Yes — plan / No]
| Rev | Date | Description |
|---|---|---|
| 1.0 | 2026-09-20 | Initial publication. |