bug-fix

Files (2)

• SKILL.md
• bug.py

SKILL.md (first lines)

> **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 gap (it behaves correctly,
only looks off) defaults to the **spine**, not `bug-fix`; reserve `bug-fix` for
a confirmed behavioral malfunction.

**Fidelity vs. refinement — does the visual target change?** If the mockup is
still the agreed target and the build simply hasn't reached it yet, that is
**fidelity**: carry the *existing* mockup forward as the AC, don't re-decide the
target. If we now want a *different* look than the mockup, that is a genuine
**refinement** (a new target), authored as such — not smuggled in as mere
unfinished work.

## Lifecycle

```
REPORTED → DIAGNOSING → ROOT_CAUSED → FIXING → REVIEWED → (VERIFIED) → DONE
                  │              └─ main already clean → RESOLVED_ON_MAIN
                  └──────────────── escalate → ESCALATED (→ spec NNN)
```

`(VERIFIED)` is gnarly/security-tier only — trivial/standard collapse
`REVIEWED → DONE`. Back-edges relax status and are ungated: `REVIEWED →
FIXING` (review needs changes — skips the `→ FIXING` entry gates, which
belong to the forward `ROOT_CAUSED → FIXING` edge), and a failed green-check or a
"symptom-not-cause" verdict routes back to `DIAGNOSING`, carrying the failed
attempt forward as new evidence (append it to `## Already tried` — it flows
into `learnings.md` at close). Every review back-edge stamps
`review_reopened_at`; re-entering `REVIEWED`/`DONE` then needs verdicts
recorded *after* that stamp, so re-run and re-record the passes.

`RESOLVED_ON_MAIN` is terminal: after the root cause is understood, the
session checks fresh `origin/main` before starting the fix. If the original
reported repro no longer fails there, another session already solved it; the
bug record is closed as resolved on main instead of generating a duplicate
patch.

From ramboz/jig, MIT.

More from ramboz/jig