Fix

fix

The defect unit-of-work — parallel to "feature" in the DAE pipeline. Tracks a bug from first report through a regression spec, code fix, hardening, and a structured retrospective that feeds back into the methodology.

Unlike ad-hoc fixes, the fix workflow enforces a regression spec that must be RED on current code before any change, and closes the loop with a "why didn't we catch it?" gap analysis tied to a closed category vocabulary. That loop is the methodology contribution: bugs become methodology feedback, not just patches.

When to use

• A bug report arrives (user report, Sentry alert, stack trace, regression in CI).
• A defect needs a repeatable reproduction path and a tracked fix.
• A regression must be proven to stay fixed (the bug-line gate: the regression test must fail on the original bug).

Not for: building a new capability (/engineer.discuss or /engineer.feature-init); adjusting an in-flight feature's scope (/engineer.feature-edit); reviewing recent changes without a defect (/engineer.arch-check or /crap-analyzer).

Maintenance auto-invocation. fix is the landing point of the SDLC's maintenance loop (${CLAUDE_PLUGIN_ROOT}/references/intent.md): a trigger — a Sentry/CI alert, a Slack message, or a schedule — can invoke it with no human at the start. Wire the trigger via the schedule skill (cron routines) or an external alert calling claude -p "/engineer.fix <signal>"; Step 1 synthesizes the bug intent from the signal/logs and the pipeline runs, surfacing to a human only at the review gates its severity + effective autonomy demand (a critical or user-blocking defect always confirms; low-severity internal ones can run further unattended). The external-write gate (${CLAUDE_PLUGIN_ROOT}/references/handoff-dispatch.md) still applies — a maintenance run never merges/deploys on its own unless verify: auto + dae_mergeready clear it.

Workflow

Infra contract. Any step that runs tests, mutations, or the regression spec MUST first ensure required infra is up via ${CLAUDE_PLUGIN_ROOT}/scripts/dae_infra.py ensure <names> (reading the manifest's infra: section). On a start-failed failure → stop and surface the structured diagnosis. On undeclared required infra → stop with "declare in manifest" message. This applies to Steps 3, 4, 7.

Quirks contract. Before booting infra or running test commands, consult manifest.infra_quirks: apply runtime_pins (e.g. ensure JAVA_HOME matches runtime_pins.java), read port_map_file if set, surface framework_constraints to the agent if relevant ("note: Flutter web has no hot-reload — full rebuild required"), use recovery_commands keyed by failure signature when probing reports a known stuck state, and — when reproducing against a worktree whose app is mount-served — follow worktree_preview instead of rediscovering the mount switch. Quirks exist so the agent doesn't rediscover what's already documented (nexthq Java/Flutter, mmc Apache opcache).

Fixture-parity contract. Steps 3, 4, and 7 run the regression spec / acceptance / mutation against a seeded DB. If manifest.acceptance.fixture_parity.check is set, run that command FIRST as a hard gate — non-zero means the seed fixture has drifted from the schema/migrations: stop, report the drift, do not run the tests, and do not attribute the resulting RED to code. Even with no check configured, never diagnose a RED as fixture drift without proving it (diff the fixture against the schema) — a phantom-column fixture masks real defects. See ${CLAUDE_PLUGIN_ROOT}/references/fixture-parity.md.

Step 0 — Re-entry routing

Before Step 1, probe for in-flight fixes via ${CLAUDE_PLUGIN_ROOT}/scripts/dae_fix.py list_open_fixes (any status != closed). Three cases:

mmc ran 5 sequential fixes from one /engineer.fix invocation because the skill assumed one-shot. Re-entry routing makes "many fixes in a row" cheap: no re-anchor, no template re-read, just pick up where the last close left off. A fresh defect from re-entry still flows through Steps 1–9 — it just doesn't lose the agent's context to a cold start.

Step 1 — Capture

Accept free-form input; no feature slug required. Collect: title, severity (low | medium | high | critical), source (kind: sentry|github|slack|user|internal, ref: <url-or-id>), whether it blocks users (blocks_user), workaround ("none" if none), and a concise repro/expected/actual. This capture is the bug intent (${CLAUDE_PLUGIN_ROOT}/references/intent.md) — synthesized from whatever signal arrived (a Sentry alert, stack trace, Slack message, or raw log), exactly as discuss synthesizes a feature intent.

Write .engineer/fixes/<YYYY-MM-DD-slug>.md via the schema in references/artifact-template.md. Set status: investigating.

CLI shortcut: /engineer.fix "title" --source <url> pre-fills title and source; skip the prompt for those fields.

From a tracker capture: if this fix is being promoted from an untriaged tracker row (a bug a human added directly — no Slug; see Tracker-as-intake in engineer/references/tracker.md), pre-fill title / severity / source from the row, set the fix's tracker_ref to that row, and write the fix slug back to it — don't leave the row orphaned or create a duplicate.

Validate the new artifact: ${CLAUDE_PLUGIN_ROOT}/scripts/dae_fix.py --validate <fix-file>. Surface any errors before proceeding.

Step 2 — Investigate

Goal: identify which feature(s) own the broken code.

Heuristics — run cheapest first to bound token cost:

1. Stack trace files → cross-reference feature.files in known features.
2. Error text grep across .engineer/features/*/feature.md.
3. Recent commits on the affected path (git log --oneline -- <file>).
4. User-provided hints.
5. From the failing symbol, trace root cause and blast radius via LSP — findReferences + call-hierarchy (incomingCalls) to see who reaches the broken code — when an LSP MCP capability is available; fall back to grep otherwise. See ${CLAUDE_PLUGIN_ROOT}/references/code-lookup.md.

Match resolution:

• Single clean candidate and prime-context confirms strong relevance → AUTO-POPULATE feature_refs; record match_mode: auto.
• Multiple candidates or ambiguous → rank top 3, invoke prime-context per candidate, present ranked list, ask user to confirm. Record match_mode: manual.
• No match → record match_mode: none; proceed as a loose fix (no feature_refs).

Record investigation.candidates_considered. Set status: pinned-pending.