/bug-fix

name: bug-fix
description: >
  Drive the teeth-gated lifecycle for reported defects: diagnose root cause,
  prove it, and prevent regression through REPORTED → DIAGNOSING → ROOT_CAUSED
  → FIXING → REVIEWED → DONE, with VERIFIED, ESCALATED, and RESOLVED_ON_MAIN
  paths where needed. Auto-fires on fix this bug, debug this, root-cause this,
  this regressed, this broke again, why is this failing, diagnose before
  fixing, or investigate this failure. Two modes: `diagnose` stops at
  ROOT_CAUSED; `diagnose_and_fix` runs through DONE. Uses a durable bug record,
  multiple hypotheses, a fresh-main recheck, and a witnessed red→green test.
  Do not use for spec-shaped work (use `spec-workflow`) — including a pure
  visual design-fidelity gap against an agreed mockup, which is spec-shaped, not
  a bug (see "Design-fidelity triage" below) — or trivial one-liners (use
  `tdd-loop`).
user-invocable: true

> **Working posture ([ADR-0056](../../docs/decisions/adr-0056-adversarial-register-quarantine.md)).** > Adversarial review is a *named, bounded operation.* This workflow invokes > review passes (bug-review / craft), whose skeptical register belongs *inside* > those isolated reviewer subagents. Outside a review, default to collaborative > and solution-forward; don't carry the adversarial stance into ordinary > conversation.

> Spec 058 / [ADR-0016](../../docs/decisions/adr-0016-bug-fix-lifecycle.md) > built this workflow. The deterministic state mutations and teeth gates live > in `bug.py`; this SKILL.md drives the judgment layer. It is a **peer of > `spec-workflow`** — a first-class jig workflow that owns its orchestration, > not a deferring baseline.

What this skill does

• Routes a reported bug to the **proportional** path: `triage` bows out of

trivial work, reserving the record + gates for standard/gnarly tiers.

• Drives the bug lifecycle state transitions via `bug.py transition`, which

enforces the teeth gates (diagnose-before-fix; red→green).

• Coordinates reviewer-subagent passes (bug-review, craft, conditional

security) at `→ REVIEWED`, validated by the ADR-0014 evidence gate.

• Rechecks fresh main after `ROOT_CAUSED` and before `FIXING` so a stale

parallel session does not re-fix a bug already solved on trunk.

• Provides the first-class escalation seam (`bug.py escalate`) for when a bug

turns out to be a missing or under-specified behaviour.

• Imports the diagnose-first discipline (the diagnostic question,

anti-anchoring, evidence-accruing re-entry) borrowed from diagnose-first debugging — see [ADR-0016 §9](../../docs/decisions/adr-0016-bug-fix-lifecycle.md).

The diagnostic question (read first, every time)

> **Is this a problem with the output, or the process that created the > output? Fixing the output is a treadmill.**

This is the heart of DIAGNOSING. A fix that patches the symptom — the bad value, the wrong pixel, the failing assertion — without finding the process that produced it does not close the bug; it relocates it. The bug-review pass exists to catch exactly this (`fix_class: workaround` honestly labelled is fine; a workaround disguised as a `structural_fix` is a blocker).

Modes

• **`diagnose`** — stop at `ROOT_CAUSED`. Use when you (or the user) want the

root cause established and reviewed before committing to a fix, or when the fix belongs to someone else. This is the default for "diagnose before fixing" / "root-cause this".

• **`diagnose_and_fix`** — run through `FIXING → REVIEWED → … → DONE`. Use

when the fix is yours to land now.

The mode is a posture, not a flag — both run the same `bug.py transition` gates; `diagnose` simply stops the forward walk at `ROOT_CAUSED`.

Tiers — proportionality enforced *downward*

`bug.py triage` is the de-escalation gate. The antidote to ceremony is a workflow that **refuses** to build ceremony for a one-liner.

| Tier | Behaviour | |---|---| | **trivial** (typo, one-liner, mechanical) | `triage --tier trivial` **deletes the record** and tells you to write the failing test with `tdd-loop`, fix, and commit. The workflow bows out. | | **standard** | Single-file record + diagnose gate + red→green teeth + bug-review + craft. ≥2 hypotheses advisory. | | **gnarly** (cross-layer, security, regression that didn't stick, design **malfunction** — *not* a pure visual fidelity gap, which is spec-shaped; see "Design-fidelity triage") | Full rigor: ≥2 hypotheses **mandatory**, keeps the `VERIFIED` step, conditional security pass, `new --push` reserves the number on `origin/main`. May escalate to a spec. |

When in doubt about whether a bug is trivial, ask: would a regression test for it be worth keeping? If yes, it is at least standard.

Design-fidelity triage — malfunction vs. fidelity gap ([ADR-0049](../../docs/decisions/adr-0049-design-fidelity-routing-to-originating-spec.md))

A design complaint is `bug-fix` **only when the UI malfunctions**: a control that looks active but isn't, or a layout that overlaps so content is unreadable. A pure visual gap against an agreed mockup — the screen works, it just hasn't reached the agreed look — is **fidelity work on the spec spine**, not `bug-fix`. Route it:

• **An originating spec exists** (the gap surfaced under a spec whose slice

built the screen) → continue that slice if still open, or open a follow-up slice **under the same spec**, carrying the mockup forward as design-value ACs.

• **No originating spec exists** (a mockup-first / cross-platform rebuild that

never entered spec-workflow) → open a **new spec** via `spec-workflow`'s greenfield path, with the mockup as design-value ACs. A mockup-first rebuild is never dead-ended into `bug-fix` for lack of an owning spec.

**Ambiguous-case tie-breaker:** an issue that "looks broken, but maybe just mis-styled" (a control that mis-signals its state, or overlap that only *might* block interaction) is decided by a quick behavioral check — does it actually *do* the wrong thing? An ambiguous-but-functional