docs: add lightweight /bugfix workflow (#4204)

[iancooper]

Summary

Fleshes out the /bugfix proposal in #4204 as a working command suite, mirroring how /spec:* is built (a set of subcommands under .claude/commands/). It is a lightweight, diagnosis-first bug workflow:

/bugfix:triage -> /bugfix:confirm (✋ gate) -> /bugfix:test (✋ gate) -> /bugfix:fix -> /bugfix:verify

It is essentially /test-first wrapped with an explicit Confirm gate up front, because a bug's root cause is a hypothesis until proven. It deliberately omits the ADR/requirements/adversarial-review rounds that /spec mandates.

Why

Bugs differ from features in one key way: the root cause is a hypothesis until proven. Issues often arrive with a suggested fix (sometimes agent-authored) that can be wrong, incomplete, or address a symptom. /test-first jumps straight to a test for an assumed cause — it has no gate for confirming the diagnosis first.

Worked example — #4054 (ASB SessionId case-sensitivity): Confirm proved the cause (JsonSerialisationOptions.PropertyNamingPolicy = CamelCase camelCases header keys on round-trip) and surfaced a second defect the suggested fix only partially addressed (reserved-header stripping is also case-sensitive). Confirming the theory changed the scope of the fix — which is exactly what the Confirm gate exists to catch.

Commands (.claude/commands/bugfix/)

Command	Role	Sub-agent / model
/bugfix:triage [issue|desc]	Restate symptom, locate code, form hypothesis (suggested fix marked UNVERIFIED)	Plan, opus, read-only
/bugfix:confirm	✋ Confirm gate — prove/refute cause, surface scope changes; writes .confirm-approved	Plan, opus, read-only
/bugfix:test	Failing regression test (delegates to /test-first)	inline, sonnet
/bugfix:fix	Minimal change to green, scoped to confirmed cause; defers to /tidy-first if cleanup needed	inline, sonnet
/bugfix:verify	Run suite; capture root cause + Fixes #N	inline
/bugfix:status, /bugfix:switch	Bookkeeping over bugfixes/	—

Open questions from #4204 — resolved

• State model: a bugfixes/NNNN-slug/ dir with one bugfix.md record + the single .confirm-approved marker (lighter than /spec's three markers).
• Confirm evidence: red repro preferred, documented code-trace allowed when a repro needs live infra (the [Bug] Do Case insensitive check for ASB sessionID #4054 case); the durable executable test is written later at the test step.
• Issue linking: capture the confirmed root cause and link with Fixes #N so merge closes the issue — never auto-close from the command.
• Relationship to /tidy-first: /bugfix:fix defers to it when a fix needs structural cleanup first (separate refactor: then fix: commits).

Docs

Adds /bugfix to .claude/commands/bugfix/README.md (workflow diagram, gate rationale, sub-agent/model-policy table), the top-level commands README, .agent_instructions/skills_overview.md, and CLAUDE.md.

Closes #4204

🤖 Generated with Claude Code

[claude]

Review: /bugfix workflow command suite

Thanks for fleshing this out — it's a clean, well-reasoned addition. This is a documentation-only PR (11 markdown files, no source/build changes), so there are no runtime bug/perf/security surfaces; the review is about correctness as instructions to the agent and consistency with the existing /spec suite. I checked the new commands against .claude/commands/spec/* and they mirror the established conventions faithfully:

• ✅ Plan (read-only) sub-agent + model: "opus" for the reasoning-heavy steps (triage/confirm), main agent owns all bookkeeping and the AskUserQuestion gate — exactly the pattern spec:design uses.
• ✅ Bash(cat:*)-style allowlists, !-prefixed context blocks, and the tracked bugfixes/.current-bug marker mirror specs/.current-spec (which is committed, so committing bug records is a consistent choice).
• ✅ The Confirm gate is genuinely the value-add over /test-first, and the [Bug] Do Case insensitive check for ASB sessionID #4054 worked example (camelCase round-trip + the second case-sensitivity defect) makes the "diagnosis is a hypothesis until proven" rationale concrete.

Minor suggestions (none blocking)

1. Hardcoded model attribution will date — verify.md Step 4 bakes Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> into the suggested commit template. A literal model name in a commit template goes stale the moment the session model changes. Consider a placeholder (Co-Authored-By: Claude <noreply@anthropic.com> or {model}) so the suggestion can't misattribute.

2. switch UX diverges from spec:switch — /bugfix:switch <bug-slug> resolves bugfixes/$ARGUMENTS/, i.e. the user must type the full NNNN-slug (e.g. 0001-asb-sessionid-case), whereas spec:switch takes the bare slug and prepends the ID ([ID]-$ARGUMENTS). Both work, but the <bug-slug> hint reads as "just the slug." Either match spec:switch's prepend behavior or clarify the hint to <NNNN-slug> to avoid a "directory not found" stumble.

3. status.md phase derivation vs. template placeholders — "Tested = Regression Test section names a test" / "Fixed = Fix section names changed files." The triage template seeds those sections with _(left blank — filled by …)_, so the agent must distinguish a real entry from the placeholder. Fine for a reasoning agent, but a one-line note ("ignore the _(left blank…)_ placeholder") would make it unambiguous.

4. Decision-tree ASCII alignment in skills_overview.md — the new branch is a bit tangled where the "Adding behavior? → YES" arm threads down to "Code needs cleanup?". Readable, but a second pass on the connectors would help.

5. Model-switch is advisory only — test.md/fix.md recommend setting the session to sonnet but nothing enforces it (expected for a doc-driven command; consistent with how /spec handles it).

Test coverage

N/A — no code paths added. The commands are exercised only by invocation, matching how the rest of .claude/commands/ is maintained.

Overall: consistent with repo conventions, the Confirm gate is a sound addition, and the docs are thorough. The notes above are polish, not blockers.

🤖 Generated with Claude Code

[codescene-delta-analysis]

No application code in the PR — skipped Code Health checks.

See analysis details in CodeScene

Quality Gate Profile: Clean Code Collective
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[claude]

Review: /bugfix workflow command suite

Reviewed the full diff (11 files, docs/command-definitions only — no production C# touched). I cross-checked against the existing /spec:* convention this is modelled on. Overall this is a well-executed, internally-consistent addition — the diagnosis-first framing is sound, the Confirm gate fills a real gap in /test-first, and the worked example (#4054) makes the value concrete. A few points below, mostly minor.

What's good

• Faithful mirror of /spec conventions. Frontmatter (allowed-tools, description, argument-hint), the Plan sub-agent + opus for read-only reasoning, sonnet for implementation, "main agent owns user interaction & bookkeeping" — all consistent with .claude/commands/spec/README.md.
• allowed-tools are scoped correctly per command. Agent appears only in triage/confirm (which launch sub-agents) and is absent from test/fix/verify (which run inline). touch is granted where the .confirm-approved marker is written; gh/git/mkdir only where needed.
• State model is genuinely lighter than /spec (one .confirm-approved marker vs three), and the phase-derivation rules in status.md are explicit, including the nice detail that a section still holding its _(left blank — …)_ placeholder counts as empty.
• All cross-references resolve (tdd/test-first.md, refactor/tidy-first.md, spec/README.md all exist).
• Faithful-reporting discipline is baked in — verify.md and fix.md both say to report failing results honestly and not declare success on red, and the issue is linked with Fixes #N rather than auto-closed.

Points worth addressing

1. The "Plan has no AskUserQuestion, so it structurally cannot prompt the user" claim is likely inaccurate. Both triage.md and confirm.md lean on this as a structural guarantee. In the current agent registry, Plan is granted all tools except Agent, Artifact, ExitPlanMode, Edit, Write, NotebookEdit — i.e. AskUserQuestion is available to it. The design is still safe because the sub-agent prompt explicitly forbids asking questions, but the wording overstates a structural lock that may not hold. Note this is inherited from the existing /spec README, which makes the same claim, so it's pre-existing rather than introduced here — but since this PR repeats it verbatim, worth softening to "the prompt instructs it not to ask" (and ideally fixing the /spec README too).

2. bugfixes/ state (including .confirm-approved markers) will be committed to git, since there's no .gitignore entry and specs/ markers like .design-approved are already tracked. Consistent with the /spec precedent, so probably intentional — but worth a conscious confirmation that you want bug working-state and gate markers in repo history rather than ignored.

3. Co-Authored-By: Claude <noreply@anthropic.com> in verify.md differs from the more specific trailer this repo's own tooling uses. The PR already adds a note that it's a deliberate stable placeholder to avoid misattribution as models change — reasonable, just flagging the intentional divergence.

4. "Delegates to /test-first" / "defers to /tidy-first" is prompt-level guidance, not a hard handoff. The model has to load and follow the referenced command — there's no enforced gate boundary between them. This matches how /spec:implement references /test-first, so it's consistent, but "delegates" slightly oversells the mechanism: the /test-first approval gate only applies if the model actually re-enters that skill.

5. Minor allowed-tools inconsistency: confirm.md grants both Bash(grep:*) and the Grep tool, while triage.md grants only Grep. Harmless, but worth normalizing.

Test coverage

N/A — documentation/command-definition content. There's no automated way to test slash-command markdown in this repo, consistent with how the existing /spec and /tdd commands ship. The bugfix.md template and phase-derivation rules read consistently across triage/confirm/test/fix/verify/status.

Verdict

No blocking issues. Point 1 (the overstated AskUserQuestion structural claim) is the only thing I'd nudge before merge, and it's low-severity since the behavioural safeguard (the prompt instruction) is in place regardless. Nice, careful work that clearly studied the /spec precedent.

🤖 Generated with Claude Code