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