/ca-fix

name: ca-fix
description: "Fix a confirmed bug: a failing regression test first, then a minimal fix, then the rest of the tdd gates."
argument-hint: "<what's happening vs. what should happen>"

$ca-fix — regression-first bug fix

The only permitted entry to bug-fix work. No fix code is written before a regression test reproduces the defect and goes red for the right reason. Give the observed behavior and the expected behavior, plus a stack trace or reproduction when you have one.

Work identity after confirmation

Use the installed `hooks/work.py` facade through [includes/helper-invocation.md](../../includes/helper-invocation.md) from the selected worktree. A diagnosis, unresolved cause, `no_action` result or design question creates no work item. Once the caller has authorized an actionable repair and the regression is red for the right reason, select the explicit `WORK-ID` if supplied. Otherwise create one `--type fix` item with the observed symptom and expected behavior as its intent, using an exact durable source key as `--origin` when available. Without an origin, pass a stable `--operation-id` and reuse it for an uncertain retry. Retain the returned work ID through repair, verification and delivery. A second bug with the same title is distinct unless its exact ID or origin proves otherwise.

On resume use `work.py context <WORK-ID>` and current evidence, not a new title match or transient debug attempt. Attach a real existing spec/plan only when the repair uses one. Keep root-cause citations and regression outcomes in their current owners. For native-owned work, refresh and report the local derived page with `work.py view <WORK-ID> --save`; it is a snapshot of canonical work. Legacy board work has no native derived view; use its selected board owner. `work.py complete` means local implementation progress only. Unknown checks, PR delivery and provider effects remain separately reported. In a native project with an explicit transition map, that one completion also saves its bounded tracker intent or waiting reason locally. Sending remains an explicit `work.py sync-mapped <WORK-ID>` step under the configured merge timing; a provider outage does not call for rerunning the regression or reviewers.

**Orientation:** if the code map is present (`.codearbiter/code-map.md`, or its HTML knowledge document), read it before diagnosing — a coarse concern→path→role map that helps locate the defect. Absent is fine; it is read-on-demand.

For a confirmed bug, the author reads the current scoped map, provenance, command declarations and collector observations, applicable constraints, and host-effective instructions. Resolve missing task-critical inputs and applicable conflicts before dependent work; provenance warnings are advisory. Direct implementation continues from these inputs.

When delegating, the coordinator calls `_contextselectlib.compose_fix_or_test_actor_input` with `route='fix'`, `caller='fix'`, the actual task paths, and the observed, expected, reproduction, cited evidence, and named regression test from the bug-origin handoff. Supply `required_refs` for task-critical inputs identified during orientation. Send its returned `input` to the actual author. A directly confirmed bug may supply the same evidence without re-entering `debug`. Keep command cwd and verification state; a historical pass does not prove a current run. The packet is orientation with `requires_actor_check`, never permission to change code. Resolve applicable critical context before material action. Call `_contextselectlib.prepare_actor_delivery` for that returned packet and the actual author/task/worktree/current epochs. Send its bounded `delivery_text` to the author on `deliver` and retain the attempt. On `advisory`, record the unknown delivery observation and continue authorized work without further delivery retries. Missing required refs and applicable constraint or instruction conflicts still stop dependent work; provenance warnings do not. Re-select after resume, compaction or scope change.

Flow

Routes to the `tdd` skill, bug variant — Phase 1 is framed around confirming the defect, not building new behavior:

1. **Establish the defect** from an observed reproduction or a supported source/contract causal trace, with its evidence and limits. A runtime replay is not mandatory when the causal trace proves the defect. 2. **Locate the root cause** — the exact code path producing the wrong behavior. 3. **Write or reuse the named regression test** from the confirmed bug handoff. It must fail in the current state for the precise reason the bug causes (not an unrelated error). 4. **Confirm it's red for the right reason** — the failure message matches the described defect.

**Remediation strategy (conditional).** Only after step 2 has confirmed the root cause, and only when materially distinct remediation strategies exist (for example, a local guard versus a contract change), run a SMARTS comparison per [includes/smarts/core.md](../../includes/smarts/core.md) inline before any fix code. A single obvious fix gets no SMARTS table. SMARTS never ranks hypotheses or confirms the cause; diagnosis stays evidence-led in `debug`.

Only then does `tdd` proceed: minimal fix to green, then the remaining `tdd` gates. When delegating, select `backend-author`, `frontend-author`, or `infra-author` by where the bug lives. If the defect cannot be pinned by a failing test, STOP and surface the question.

Debug handoff and direct-fix prerequisite

For an authorized direct fix that needs a small investigation to establish its cause, take one internal diagnostic prerequisite through the debug owner, then return to the same original fix caller and its existing scope and TDD gates. Keep the count at one for this fix attempt. No public command recursion or compulsory public route retyping is needed, and no feature artifact is fabricated. If diagnosis is unresolved, non-code, or exposes an authority blocker, report the resul