workflow-bugfix

name	workflow-bugfix
description	Fix a bug on an existing harness project via structured debugging — build a reliable pass/fail signal first, then hypothesize, confirm, and fix minimally. Use when: a reported bug, a hard-to-reproduce failure, a regression, a mysterious/intermittent error, agent-assisted root-cause analysis.

Bug report: $ARGUMENTS

One-Liner

Build a fast, deterministic, agent-runnable pass/fail signal first — the bug is 90% fixed once you have it. Never theorize before you can reproduce.

Core Philosophy

Most debugging fails because the engineer jumps to hypotheses without a reproducible signal, then "fixes" symptoms. Build the loop, let the loop drive everything, and only change code once a single hypothesis is confirmed. Smaller footprint than workflow-feature, same review/test/verify gates.

The six phases (each ends in a Gate)

Phase 1 — Build a feedback loop

Create the fastest reproducible signal: unit test > integration test > CLI script > REPL > fuzz. Must be agent-runnable, deterministic, and emit pass/fail (not "looks wrong"). Gate: a script/test reproducibly demonstrates the failure.

Phase 2 — Reproduce exactly

Confirm the loop shows the reported failure, not a nearby one. A different failure = a second bug (note it, don't chase it). Gate: loop output matches the report word-for-word.

Phase 3 — Hypothesize (before touching code)

Generate 3–5 ranked, falsifiable, independent hypotheses.

H1 (most likely): <cause> → predicts <observable> → test by <action>
H2: …

Gate: each hypothesis has a concrete, testable prediction.

Phase 4 — Confirm one

Bisect / instrument / add logging to confirm or kill hypotheses cheaply (use core-explore to locate). Do not fix yet. Gate: exactly one hypothesis is confirmed by evidence from the loop.

Phase 5 — Minimal fix

Smallest change that turns the loop green. Resist scope creep; a larger design problem becomes a separate feature (WIP=1). Gate: the Phase-1 loop is now green.

Phase 6 — Regression + verify

test-regression is mandatory (a bug edits existing behavior) plus the loop's reproduction test; run check-review-loop — an independent role-based reviewer (scripts/role-resolver.sh --phase review) with harness review open/record provenance — then ./harness verify <id>. Gate: reproduction test + regression green, review findings resolved, review provenance CURRENT, evidence recorded.

Rules

• Failing test before fix — a fix without a reproducing test is not accepted.
• Regression required — check-test-strategy always includes regression here.
• Task-state — tick the reproduce→fix→regression→verify boxes in .harness/tasks/<id>.md (../../resources/task-state.md).
• Step-gate + token-budget as in workflow-feature, including caveman on by default — apply opt-caveman to inter-agent prompts and subagent results. Persona controls reporting depth (../../resources/persona-mode.md).

Delegate craft depth to the experts. For stack-trace/log analysis and hypothesis-driven isolation, load the vendored debugging-wizard and the six-phase debug-diagnose (see ../../resources/expert-skills-map.md). This workflow keeps the feedback-loop-first discipline, the gates, and the regression+verify close-out.