arthai-marketplace

/fix

Formal bug fix pipeline — root cause analysis, scope lock, behavior contract, differential testing, regression proof.

Synopsis

/fix <description|#issue> [--severity critical|high|medium|low] [--hotfix|--lite|--lite-strict|--verified|--full|--swarm]

When to use it

Note: /fix can also be auto-triggered by a Monitor webhook when production error events cross a threshold — see Monitor Integration in the skill for the .claude/monitors/ config that wires an error tracker (Sentry, Datadog, Rollbar) to the pipeline.

Quickstart

/fix POST /auth/refresh returns 500

What you’ll see: an investigation that converges on a root cause (with file:line evidence), a scope-locked fix with a regression test proven to catch the bug, a differential test showing nothing else changed (any unrelated test regression blocks the PR), and a PR with the full evidence trail.

Examples

/fix #123                                      # load the bug from a GitHub issue
/fix #123 --severity critical                  # explicit severity (otherwise auto-assessed)
/fix #123 --hotfix                             # production fire — expedited single-trace path
/fix --severity high token refresh fails silently

Arguments & flags

Flag Values Default What it does
--severity critical | high | medium | low auto-assessed Drives QA depth and merge urgency
--hotfix — off Expedited path for production fires: single backward trace, compressed checks, deferred deep investigation post-merge
--lite / --verified / --full (alias --swarm) / --lite-strict — auto-detected Advanced: force the investigation depth (lite → verified → full ladder) instead of letting the pipeline pick it from the bug’s signals; --verified (analyst + challenger) is what auto-detection picks when no signal fires

All six investigation-depth flags (--hotfix, --lite, --lite-strict, --verified, --full/--swarm) are mutually exclusive — pass at most one. Leave them all off to let auto-detection pick a depth from the bug’s signals.

What it does

User-confirmation checkpoints (marked below) are interactive prompts where /fix pauses and asks you to decide something — which hypothesis to pursue, whether to accept a symptom-side fix, what QA level to run. In CI, autopilot, or Monitor-triggered runs, each checkpoint uses a safe default instead of blocking.

  1. Loads bug context — from the issue or description, syncs with the default branch (refuses to run with uncommitted changes), runs an advisory revert-check so a buffered revert can’t masquerade as the bug, and checks the knowledge base for similar past incidents. If invoked with no description, it asks for one first (user-confirmation checkpoint).
  2. Root cause investigation — competing investigator agents trace the bug independently, then cross-challenge each other until they converge on a causation chain (symptom → root) with cited evidence. Depth is auto-selected: lite for smoking-gun tracebacks, full swarm for auth/payments/migrations/security, verified (analyst + challenger) as the default when neither signal fires. If the swarm can’t converge, you choose which hypothesis to pursue (user-confirmation checkpoint). If a lite investigation finishes with low confidence, disagreeing agents, or both agents stopping at the symptom with no root-cause walk-back, it auto-escalates to a full investigation — pass --lite-strict to disable this and accept the lite verdict as-is.
  3. Scope lock — builds the dependency graph from the root cause and writes a Fix Zone (may modify), Watch Zone (caution), and Frozen Zone (blocked). The fix cannot touch files outside the zone.
  4. Behavior contract — tables what MUST change and what MUST NOT change, with a baseline test-suite snapshot.
  5. Implements the fix — a scoped agent fixes at the root cause (not the symptom) and writes a regression test, which is mutation-checked: it must FAIL with the fix reverted and PASS with it applied.
  6. Review swarm — a fix-reviewer (7-point correctness checklist plus a root-cause pre-gate) and a qa-attacker (3-5 attack scenarios) review in parallel and cross-examine. The pre-gate verifies the diff actually lands at or upstream of the root cause, not just at the symptom, and returns PASS / FAIL / SYMPTOM-ONLY-JUSTIFIED. A symptom-only fix (FAIL) is BLOCKED and sent back to implementation; a justified symptom-side fix (SYMPTOM-ONLY-JUSTIFIED) is surfaced to you for confirmation (user-confirmation checkpoint) in interactive mode, or logged as a warning-only in CI/autopilot.
  7. Differential testing — re-runs the full suite and diffs against the baseline. Any unrelated PASS→FAIL blocks the PR.
  8. Post-fix handoff — asks what QA level to run before PR: commit / full / skip, with full recommended for critical/high severity (user-confirmation checkpoint), runs /qa, restarts local servers, and asks you to test the fix manually before proceeding (user-confirmation checkpoint). Then creates the PR via /pr with the bug-fix evidence template, updates the knowledge base, runs a final completion verification, and prints a post-fix checklist (incident record, bug-pattern, knowledge-graph write, verifier) before announcing the PR URL. In unattended runs (CI, autopilot, Monitor-triggered) it never prompts: the QA level is derived from severity and manual testing is deferred with a logged notice.

Agents spawned

Agent Model tier Role
backward-tracer / forward-tracer sonnet Independent root-cause investigation strategies
pattern-matcher haiku Searches the knowledge base for matching past incidents
implementation agent (backend / frontend) sonnet Applies the fix inside the Fix Zone
fix-reviewer sonnet Correctness checklist + root-cause pre-gate
qa-attacker sonnet Adversarial attack scenarios against the fix
completion-verifier sonnet Final completeness cross-check

Note: in calibrated projects, these agent assignments and model tiers can be overridden — check .claude/registry.json for active agent substitutions and model-policy.yml (or .claude/model-policy.yml) for model-tier overrides.

Output & artifacts

Troubleshooting

Problem Fix
Uncommitted changes present — commit, stash, or discard before /fix The pipeline refuses to start on a dirty tree — clean it up first
Rebase conflicts against origin/main The base shifted under you — run git rebase --abort and sync manually before re-running
Investigation swarm could not converge You’ll be shown all competing hypotheses with evidence — pick one or ask it to investigate all
Review verdict: BLOCK (“fix patches symptom only”) The diff doesn’t address the root cause — the pipeline returns to implementation rather than shipping a band-aid
Regression test passes both with and without the fix The test is rejected as useless and rewritten — this is by design