ramboz Working posture (ADR-0056). 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 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 ofspec-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:
triagebows 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_CAUSEDand beforeFIXINGso 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.
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 atROOT_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 throughFIXING → 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)
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 intobug-fixfor 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), 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).
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.
The teeth gates
bug.py transition enforces presence/shape, never quality (quality is the
reviewer's job). Each gate is bypassable as a deliberate act
(ADR-0011 lineage) — separate env vars so one gate can be relaxed without
silently relaxing the others.
| Transition | Gate | Bypass |
|---|---|---|
→ ROOT_CAUSED |
≥2 candidate hypotheses + a leading one + an evidence pointer | JIG_BUG_DIAGNOSE_GATE=0 |
ROOT_CAUSED → FIXING |
fresh-main recheck recorded as main_repro_result: reproduces; fix_class declared; regression_test runs red (shells to tdd.py, expects exit 1; stamps red_confirmed_at); repository-closure inventory present for new standard/gnarly records |
JIG_BUG_MAIN_CHECK_GATE=0 (main recheck), JIG_BUG_TEST_GATE=0 (test), JIG_BUG_CLOSURE_GATE=0 (closure) |
→ REVIEWED |
the same regression_test now runs green (shells to tdd.py, expects exit 0; stamps green_confirmed_at); call-site closure recorded for new records; and the required review verdicts pass |
JIG_BUG_TEST_GATE=0 (test), JIG_BUG_CLOSURE_GATE=0 (closure), JIG_REVIEW_EVIDENCE_GATE=0 (verdicts) |
→ VERIFIED |
original reported repro re-run clean (gnarly/security only), attested in the record | — |
→ DONE |
required review verdicts pass + a learning recorded in docs/memory/learnings.md |
JIG_REVIEW_EVIDENCE_GATE=0 |
The distinctive gates are the diagnose gate (the ≥2-hypotheses
anti-anchoring rule), the fresh-main recheck after root cause, the
red→green teeth, and the repository-closure gates (ADR-0037). The
red→green teeth: the helper itself witnesses the test fail before the fix and
pass after, so "there is a regression test" is machine-attested, not claimed. A
bug already clean on fresh main becomes RESOLVED_ON_MAIN; a test already green
without the fix does not capture the bug — the → FIXING gate refuses it. A
tdd.py env error (exit 2) fails closed (gate not satisfied), distinct from
red. The repository-closure gates make reuse/history discovery and call-site
closure durable evidence (see the Repository-closure inventory subsection
under step 2 below).
fix_class (declared at → FIXING) is one of workaround / local_patch /
structural_fix / guardrail / observability.
How to use
0. Confirm the project is scaffolded
Like spec-workflow, the bug record lives under docs/bugs/. If the project
is greenfield, route to /jig:scaffold-init first; if it has a spec layout
but no scaffold.json, route to /jig:migrate. Don't hand-roll docs/bugs/.
1. Create and triage the record
Before creating a new bug from a feedback/triage batch, scan
docs/specs/README.md for an overlapping active slice. If the work is already
owned by a spec, link that slice from the bug record or escalate/route instead
of creating a second owner.
# Reserve the number. Local by default; --push reserves on origin/main
# (gnarly tier), --pr via PR. Works from any branch/worktree (ADR-0015).
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" new <slug> [--push|--pr]
# Classify. trivial → record deleted, bows out to tdd-loop + commit.
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" triage <id> \
--tier trivial|standard|gnarly [--severity <level>]
If triage bows out, stop here — write the failing test with
/jig:tdd-loop, fix, commit. Do not re-create the record.
Claim/release reuses the spec 049 machinery: bug.py pickup <id> claims;
bug.py pickup <id> --release --reason "<why>" force-releases a stale claim
(logged to the record's ## Release log). pickup also stamps the working-tree
.jig/spec-ref marker naming this bug (slice 098-04) — the signal that tells
jig's lifecycle entry gate a bug fix is in flight, so ad-hoc-edit nudges stay
silent while you work. Release and terminal transitions clear it.
2. Diagnose (→ DIAGNOSING → ROOT_CAUSED)
Fill the record body — ## Symptom, ## Repro, ## Evidence,
## Hypotheses, ## Root cause. Anti-anchoring: write ≥2 candidate
hypotheses with confirm/falsify framing and mark the leading one (mandatory
for gnarly, advisory for standard, but always good practice — the first
explanation is rarely the right one). Write the hypotheses as a Markdown list
under ## Hypotheses — any marker works (-, *, +, or 1.) and the gate
counts top-level items only, so indented - Confirm: / - Falsify:
sub-bullets read as notes, not as extra hypotheses. Mark the leading one with
[x], an inline (leading) tag, or a Leading: line.
Ground a ## Root cause claim; enumerate a universal one
(ADR-0052).
A root-cause claim of universal or negative shape — "nothing else calls
this", "only this path writes the column", "this is the one place the
value is set" — is established by an enumeration (a search you can show
returns the complete set: grep every caller / writer / call-site), not
by a single citation of one example. One true example says nothing about the
rest of the set, and a false "only/nothing" here sends the fix to the wrong
place. To claim it, state why the search is exhaustive — what closes the set
so nothing escapes. Many sets only look grep-bounded: a column written
through an ORM, a string-built query, reflection, config-wiring, codegen, or an
external consumer is invisible to grep (illustrative, not a checklist), so an
empty result is absence of evidence, not proof nothing writes it. When you
cannot show the search closes the set, weaken the claim or record it under
## Already tried / the record's assumptions rather than asserting it as the
root cause — the bug-review pass treats an empty search as ungrounded until you
have shown what closes the set. Then:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" transition <id> DIAGNOSING
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" transition <id> ROOT_CAUSED
In diagnose mode, stop here and present the root cause.
Repository-closure inventory (before → FIXING) — ADR-0037
Before you write the fix, fill the ## Repository closure inventory section
(new standard/gnarly records gate ROOT_CAUSED → FIXING on it — a fresh
bug.py new record carries the section and the closure_schema: marker; a
legacy pre-091 record has neither and is exempt). This exists because a narrow
patch that duplicates an existing helper passes TDD while leaving a
convergent path unfixed — the closure question has to be asked before the
code shapes the change, not at review.
- Equivalent / convergent logic searched — look for an existing
implementation of the same contract, possibly under a different name.
Tool-neutral: prefer a configured semantic index when one is available;
the portable floor every project has is targeted text search plus
git log -S/git grep. Record the terms you tried, not just a verdict. - Relevant history inspected —
git log/git blameon the touched surface: when and why did this logic arrive, and did the same change land elsewhere? - Affected call sites — enumerate the sites that share this contract.
- Reuse decision — reuse the existing implementation, or duplicate with an explicit reason.
This is an effort-and-protocol standard, not a completeness standard. You
cannot prove a differently-named helper does not exist, and the gate does not
ask you to. What it refuses is a bare verdict — "none found" with no
recorded search behind it. When the set genuinely cannot be closed by a name
search, apply the same enumeration standard as the ## Root cause grounding
above (ADR-0052):
state what you searched and why it does not close the set, and record the
residual as an assumption with that protocol. Do not restate the enumeration
rule here — it has one home, in the diagnose grounding block above. bug-review
judges whether the search was real; the transition gate only checks the
prompts are answered and not vacuous.
3. Fix (→ FIXING → REVIEWED), diagnose_and_fix mode
Declare
fix_class:and name theregression_test:in the record. Before→ REVIEWED, fill## Call-site closure: account for every site the inventory named as changed, tested, or intentionally left alone (with a reason). This is accounting, not a mandate to widen the fix — a site can be correctly left untouched. New records gate→ REVIEWEDon it; legacy records are exempt.Recheck fresh main before writing the fix. Fetch/inspect
origin/main(usually from a detached worktree) and re-run the original reported repro. Then record the outcome:python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" main-check <id> \ --result reproduces \ --ref origin/main@<sha> \ --evidence "<original repro command + observed failure>"If the bug no longer reproduces on fresh main, record the terminal off-ramp and stop:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" main-check <id> \ --result resolved-on-main \ --ref origin/main@<sha> \ --evidence "<original repro command + observed clean result>"Write the regression test FIRST (it must fail without the fix — that is what the
→ FIXINGgate witnesses). Use/jig:tdd-loopfor the red→green loop.transition <id> FIXING— the gate requires the fresh-main recheck above, then shells totdd.pyand expects the test red; it stampsred_confirmed_at.Implement the smallest change the diagnosis supports. Make the test green.
Run the review passes (below), record their verdicts, then
transition <id> REVIEWED— the gate shells totdd.pyand expects the test green (stampsgreen_confirmed_at), then validates the verdicts.
4. Review passes (at → REVIEWED)
Two required + one conditional, run as reviewer-subagent passes by the
host/orchestrator and validated by the ADR-0014 evidence gate. The reviewer
is read-only — bug.py validates the durable verdict artifacts they produce
(docs/bugs/reviews/bug-NNN-<pass>.md).
bug-review (always) — the compliance analogue, jig's own. Build the prompt with
review.py bug-review:PROMPT=$(python3 "${CLAUDE_PLUGIN_ROOT}/skills/independent-review/review.py" \ bug-review "docs/bugs/NNN-<slug>.md" "<deliverable-path>" ...)It asks: does the fix address root cause or paper over the symptom? is there a regression test that fails without the fix? blast radius? scope creep? If
fix_class: workaround, is it honestly labelled and justified?craft (
pr-review, always) — defers to a richer installedpr-reviewskill on disk; falls back to jig's baselinepr-reviewskill. Run that skill's methodology against the bug's deliverables — it is diff-shaped, not spec-shaped, so there is noreview.py pr-reviewcall for a bug (that builder requires a spec + slice). Record the verdict withprompt_source: pr-review skill craft pass(as bugs 001–003 did). A configuredreview.pr_review_skill(scaffold.json) is NOT read here. Spec 096-01 / ADR-0040 D1 wired config honoring intoreview.py's craft-pass builder, but this pass makes no such call, so the config key does not reach it — deferral here stays disk/router-based. Making bug-fix's craft (and security) passes config-honoring is a tracked follow-up (ADR-0040 OQ1).security (
security-review, conditional onsecurity_surface: truein the record — mirrors howarch_review: truegates the arch pass) — defers to a richer installedsecurity-reviewskill (Adobe'sadobe-security-*, the user's own, or jig's baseline).
There is no arch pass — bugs carry no design.
Record each verdict with review.py record-review --bug NNN --pass <name> --verdict pass --reviewer <src> --summary-file <path> (or --summary-file -
to pipe the body in — the body is required, and stdin is never read
implicitly, bug 017). The REVIEWED gate requires bug-review +
craft (+ security when security_surface: true), each verdict: pass.
5. Verify (gnarly/security only) and close
# Gnarly/security: re-run the ORIGINAL reported repro (not just the proxy
# test), attest it in the record, then:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" transition <id> VERIFIED
# Record the learning in docs/memory/learnings.md (the → DONE gate checks it),
# commit the work, then:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" transition <id> DONE
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" status-board
Run /jig:memory-sync to consolidate any new learnings. Land the change with
/jig:slice-land if a formal landing checklist helps.
Before landing, audit the board. docs/bugs/README.md is derived — every
column is computed from the records — so it is regenerated, never hand-edited,
and a merge conflict on it is resolved by re-running status-board rather than
by picking a side:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" check-board
Read-only; exits non-zero on either problem it can find. Stale board — the
records changed and status-board wasn't re-run. Duplicate id — two records
claim one number, which is what parallel branches produce when the number was
never reserved on the trunk. The renderer emits both rows without complaint and
a staleness check can't see it (both rows are faithfully derived), so this is
the only thing that catches it. Wire it into CI if the project lands work from
more than one branch at a time.
Escalation (→ ESCALATED)
When diagnosis reveals the "bug" is a missing or under-specified behaviour — not a defect in existing behaviour — escalate instead of fixing:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bug-fix/bug.py" escalate <id> [--slug <spec-slug>]
This calls workflow.py new, stamps escalated_to: NNN on the bug and
"originated from bug NNN" on the new spec, and parks the bug in terminal
ESCALATED (not DONE — it was not fixed as a bug). Continue in
spec-workflow.
De-escalation guidance
The single most important judgment in this workflow is down-shifting:
- A typo, a copy-paste error, a one-line off-by-one, a mechanical rename — let
triage --tier trivialdelete the record. Write the test, fix, commit. Creating a numbered record for a one-liner is the ceremony this workflow exists to refuse. - A standard bug does not need the
VERIFIEDstep or a security pass —REVIEWED → DONEis the path. - Reach for gnarly only for genuinely cross-layer, security-surfaced, regression-that-didn't-stick, or design-malfunction bugs (a control that looks active but isn't; overlap that makes content unreadable — not a pure visual fidelity gap, which is spec-shaped; see "Design-fidelity triage"). If a "gnarly" bug is really a missing behaviour, escalate — don't grind it through the bug gates.
Routing — bug-shaped vs spec-shaped
This is the bookend to spec-workflow's "do not use for bug-shaped work"
clause. See docs/workflow.md for the canonical
routing rule. In short: a reported defect → jig:bug-fix (proportional to
tier); a hard-to-reverse decision, cross-layer change, or ambiguous-scope new
behaviour → spec-workflow; a trivial one-liner → straight to tdd-loop +
commit.
Gotchas
- The
→ FIXINGgate refuses an already-green test. A regression test that passes without the fix does not capture the bug. Write the test to fail first. - The
→ FIXINGgate also refuses a stale trunk check. AfterROOT_CAUSED, recordbug.py main-check … --result reproducesagainst freshorigin/main; if the repro is clean there, markRESOLVED_ON_MAINand stop. tdd.pyenv error fails the gate closed (exit 2 ≠ red). Fix the environment; don't bypass blindly.- Bypass env vars are deliberateness escapes, not the default.
JIG_BUG_DIAGNOSE_GATE=0/JIG_BUG_MAIN_CHECK_GATE=0/JIG_BUG_TEST_GATE=0/JIG_REVIEW_EVIDENCE_GATE=0are for out-of-band flows — using them silently defeats the teeth. - Escalate, don't grind. A bug whose fix introduces new routing/landing semantics or a missing behaviour is a spec — use the escalation seam.
ESCALATEDandRESOLVED_ON_MAINare terminal — closed, not unfinished. A bug in a terminal non-DONEstate was reclassified to a spec (ESCALATED) or already fixed on trunk (RESOLVED_ON_MAIN); it was never fixed as a bug, so its blank fix/test columns are expected. Don't flag it as stale or try to advance it toDONE. The status board segregates these rows under a## Terminalsection (parity with the spec board's## Deferred slices/## Abandoned slices) so closure is legible.bug.pynever spawns subagents. The host/orchestrator runs the reviewer passes;bug.pyonly validates the recorded verdict artifacts (ADR-0016 Scope).