# Fix

> [Implementation] Use when a workflow step or the user asks for root-cause fixes with regression coverage. --target={ci|issue|logs|review|test|types|ui} scopes the issue.

- Skill: `duc01226/fix-3` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add duc01226/fix-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/fix-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: duc01226 (https://skillmd.com/u/duc01226)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/duc01226/fix-3

---


> Codex compatibility note:
> - Invoke `$skill-name`: load the registered `.agents/skills/<name>/SKILL.md` and execute it with Codex tools; no separate `Skill` tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author `.claude/**`; mirrors are generated.
> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
> - Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.
> - Preserve protocol order unless the user approves a deviation. Workflows use `$start-workflow`: gates stay fixed; other steps may flex with logged reasons and evidence.
<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, merge steps without explicit user approval. Inside a workflow run, `$start-workflow` → Workflow-step mode bounds this rule.
> **[BLOCKING]** Before each step or sub-skill call, update todo tracking: `in_progress` on start, `completed` on end.
> **[BLOCKING]** Every completed/skipped step MUST include evidence or explicit skip reason.
> **[BLOCKING]** If Task tools unavailable, maintain equivalent step-by-step plan tracker with same status transitions.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

> **Work tracking:** Keep the project's tracked work current in the same change, as its root instructions (`CLAUDE.md` or `AGENTS.md`) say. When the project uses the portable tracker (`taskTracking.mode` is `observe` or `linked`), read [the linked work integration guide](../task-track/references/integration-guide.md) at capture, start, saved-work, verification, handoff and close-out checkpoints. Use the actual linked producer and exact items; retain the primary outcome and record optional upkeep once through the common owner. Continue untracked when no link exists; acceptance remains explicit.

## Quick Summary

**Goal:** Eliminate each issue's root cause with end-to-start `file:line` evidence, fix the lowest invariant-owning layer (never the crash site), and add or update regression coverage that proves the fix converges.

**Summary:**

- **Purpose:** Diagnose end-to-start, fix the lowest invariant-owning layer, update regression coverage and spec/tests; NEVER patch symptoms.
- **No-flag spine:** Root-Cause Prerequisite Gate → researcher investigation → `investigate --mode=debug` trace (`file:line`, hypothesis matrix, forward proof) → Confidence & Evidence → impact plan → 🛑 Validate-Before-Fix → owning-layer implementation → standalone test update (`$integration-test`, or justified `$test` fallback) → conditional `$spec` check → `$changes-review --defer=whole-target` for production code → `$why-review` → verify once (`$integration-test --mode=verify` or `$test` with the mutation check; fix and re-run to green; re-review only if that edited anything, `SYNC:verify-last-order`); ALWAYS follow this order.
- **Routing:** `--target={ci|issue|logs|review|test|types|ui}` selects a self-contained branch with its own diagnosis; no flag runs the spine. Branches skip standalone §1/§2 duplication, but every direct call passes the Root-Cause Prerequisite Gate.
- **Modes/gates:** HARD is default; fast mode requires ALL 5 trivial-bug conditions. Root-cause proof, `Confidence: X%` (`<70%` STOP), and Validate-Before-Fix are hard gates; approval may skip only when `nested=true` (a `[Workflow]` row that merely exists in the current task list does not count), while standalone calls own test/spec/review phases; NEVER bypass a gate.
- **Workflow step (`nested=true`):** after the workflow's `$investigate --mode=debug` (and its `$plan`, when that step ran), consume that cited trace and plan instead of spawning `debugger`, `researcher` or `planner` sub-agents, and adjust the pre-written regression test when the fix changes its seams; tests run only in the workflow's later verify step. See [Fix the issue](#fix-the-issue).

**Workflow:**

1. **Investigation** — Use researcher subagents to explore the issue in parallel; use `$investigate` inline for tracing (an optional graph hint may help).
2. **Diagnose** — Trace root cause through code paths with evidence
3. **Plan** — Create fix plan with impact analysis
4. **Fix** — Implement the fix with its regression test; tests run once in the verify step, not here (`SYNC:verify-last-order`)
5. **Standalone test update** — After the fix, every standalone call invokes `$integration-test` to add or update regression coverage; use `$test` only for a justified unit-test seam. When `nested=true` (a workflow step with its own linked phase tasks), the parent sequence owns these test phases, except that this step adjusts a regression test the workflow wrote before the fix when the fix changes its seams (not run here).

**Key Rules:**

- **Root-Cause Prerequisite Gate (BLOCKING):** no code edit until `$investigate --mode=debug` traced THIS problem in THIS session — evidence, not recall
- Debug Mindset: every claim needs `file:line` evidence
- Use subagents for parallel investigation of multiple hypotheses
- Always create a plan before implementing complex fixes
- **Target flag** (see [Target Routing](#target-routing---target)): `--target={ci|issue|logs|review|test|types|ui}` selects a self-contained branch that scopes the fix to that domain. No flag = full diagnose→fix spine below.

## Contents

- [Quick Summary](#quick-summary)
- [First Principle — Easy to Change · Easy to Scale · Easy to Maintain](#first-principle--easy-to-change--easy-to-scale--easy-to-maintain)
- [Default Mode Policy](#default-mode-policy)
- [🛑 Root-Cause Prerequisite Gate (Direct `$fix` Invocation) — BLOCKING](#-root-cause-prerequisite-gate-direct-fix-invocation--blocking)
- [Standalone Mode Minimum Contract (Non-Workflow Only)](#standalone-mode-minimum-contract-non-workflow-only)
- [Debug Mindset (NON-NEGOTIABLE)](#debug-mindset-non-negotiable)
- [⚠️ MANDATORY: Confidence & Evidence Gate](#️-mandatory-confidence--evidence-gate)
- [Target Routing (`--target=`)](#target-routing---target)
- [Workflow:](#workflow)
- [Next Steps (Standalone: after the Minimum Contract completes. Skip only when `nested=true` — a `\[Workflow\]` row that merely exists in the current task list does not count.)](#next-steps-standalone-after-the-minimum-contract-completes-skip-only-when-nestedtrue--a-workflow-row-that-merely-exists-in-tasklist-does-not-count)
- [Closing Reminders](#closing-reminders)

## First Principle — Easy to Change · Easy to Scale · Easy to Maintain

> The full gate is `SYNC:core-engineering-principles` (protocol guide below; a hook delivers its text); its closing digest ends this file.

---

## Default Mode Policy

> **Default mode HARD.** Every section below applies: parallel researcher subagents, `file:line` root-cause tracing, Confidence & Evidence Gate, impact plan, and bug-preservation tests.
>
> **Fast mode ONLY when ALL 5 conditions hold** (genuinely trivial bug):
>
> - Root cause obvious from error and already located; no diagnosis needed
> - One file; ≤10 changed lines
> - No cross-service impact or contract change
> - Existing bug test, or non-functional typo/log-message fix
> - Fix confidence ≥95% without further investigation
>
> Any condition fails → full protocol; in doubt use HARD. Non-trivial fixes cannot skip diagnosis.
>
> **Fast mode skips only:** parallel subagent investigation (direct read/grep instead), separate plan (inline change), and regression-test authoring (only when coverage exists). It still runs Confidence & Evidence, Behavioral Delta Matrix, and the existing test suite.

## 🛑 Root-Cause Prerequisite Gate (Direct `$fix` Invocation) — BLOCKING

> **[BLOCKING]** Direct `$fix` MUST NOT edit code until `$investigate --mode=debug` produces THIS problem's root cause in THIS session. The gate runs before the Standalone Mode Minimum Contract, any `--target=` branch, and 🛑 Validate-Before-Fix. — why: an untraced first edit patches the symptom site and ships the disease.
>
> **1. Trigger — ALL direct invocations.** User-typed command or model-selected skill; every `--target={ci|issue|logs|review|test|types|ui}` branch and no-flag spine. Branches skip contract §1/§2 duplication but pass this gate. — why: a branch `debugger`/`tester` step is not an end-to-start trace.
>
> **2. Check — evidence, never memory.** Before the first code edit, accept only same-session, same-problem `$investigate --mode=debug` evidence:
>
> - a the current task list row for `investigate --mode=debug` (or its phase tasks) covering this symptom, **or**
> - a written investigation report naming this symptom (e.g. `tmp/analysis/{issue-name}.analysis.md`, `tmp/reports/debug-investigate-*.md`) containing the end-to-start trace.
>
> No evidence → NOT run. Recalling that the cause "is known" is not proof. — why: context compaction preserves belief, not findings.
>
> **3. Act.** Not run → run `$investigate --mode=debug` FIRST, then resume `$fix` at planning with its report. This subsumes the spine's step-1 `debugger`. — why: repeating an existing diagnosis double-runs the spine.
>
> **4. Same-problem test.** A prior `$investigate --mode=debug` for a different symptom does NOT satisfy this gate. If `<issues>` is not covered, the gate fires. — why: one investigation per session would license unlimited untraced fixes.
>
> **5. Skip conditions — explicit, narrow, and recorded.** Record which one applies with its proof; never skip silently:
>
> | Condition                                                                                                                  | Skip? |
> | -------------------------------------------------------------------------------------------------------------------------- | ----- |
> | Same-problem evidence per §2 exists → cite the `file:line` / task-row proof and proceed                                     | YES   |
> | Fast-mode-trivial bug (**ALL 5** `Default Mode Policy` opt-out conditions hold) → MAY inline the end-to-start trace instead of spawning the skill; the trace itself is still REQUIRED | PARTIAL |
> | Active parent workflow row whose sequence **already executed** `investigate --mode=debug` for this problem → cite the completed step | YES   |
> | `--target=review` over VALIDATED review findings, each carrying `file:line` evidence and a named owning layer (validated by `$why-review --validate-findings` or by its reviewer's own validation step) → cite the report | YES   |
> | Active parent workflow row **alone**, with no completed `investigate --mode=debug` step for this problem                            | **NO** |
>
> **The last row is the hole this gate closes.** A parent workflow row may exist while its `investigate --mode=debug` step never ran, covered another symptom, or was skipped. This gate adds completed same-problem proof; it never relaxes the contract. — why: a container task is not evidence that its work happened.
>
> **BLOCKED until:** the §2 check is stated with its evidence (or its explicit skip row + proof) AND a root-cause trace for this problem exists. **NEVER** proceed to plan or edit on "the cause is obvious" alone.

## Standalone Mode Minimum Contract (Non-Workflow Only)

> **Workflow context:** `$fix` normally runs inside `workflow-bugfix`, whose sequence (`investigate --mode=debug → spec [mode=amend] → plan → … → fix → … → spec [mode=sync] → workflow-review-changes`) supplies diagnosis, spec sync, and review. Standalone `$fix` diagnoses and patches but does not guarantee root-cause ownership, alignment with the business spec root (default `docs/specs/`; `specRoots.business.path` in `docs/project-config.json` overrides), or review; without this contract it risks symptom-patching + spec drift.
>
> **Scope:** applies with no parent workflow. No-flag runs the full diagnose→fix path; `--target={ci|issue|logs|review|test|types|ui}` branches remain self-contained for diagnosis, skip §1/§2 duplication, and inherit mandatory §3 test-update, §4 spec-correctness, the production-code `$changes-review` gate, and §5 `$why-review` gates. A branch's own `tester` / `code-reviewer` sub-agent step does not replace `$changes-review`.
>
> **Detect mode:** call the current task list first (per Nested Task Expansion). A run that is a step of a `[Workflow]` row (THIS run's own phase tasks are linked to that parent row, `nested=true` — a `[Workflow]` row that merely exists in the current task list, such as an abandoned one, does not count) — or a `--target=review` call from a reviewer's fix phase (the `$changes-review --fix-loop` fix step, `changes-review/references/fix-loop.md` step 3) — skips this section because the caller owns these steps, but the Root-Cause Prerequisite Gate still requires a completed, same-problem `investigate --mode=debug` (or, for `--target=review`, its validated-review-finding skip row); presence alone is insufficient. Not nested (no linked parent row, or only a stale/unrelated `[Workflow]` row) → standalone: before the first code edit, MUST ATTENTION create this ordered minimum spine as todo tracking todos:
>
> 1. **`$investigate --mode=debug`** — root cause FIRST; §2 evidence decides whether it already ran. Trace symptom end-to-start to the invariant-owning layer with `file:line`, hypothesis matrix, and forward proof. This is standalone diagnosis and subsumes the spine's step-1 `debugger`; resume at planning with its report. Fast-mode-trivial bugs may inline the trace, but the trace remains required.
> 2. **Fix spine** — this skill's `plan → 🛑 approve → implement` body below; Validate-Before-Fix remains unchanged.
> 3. **`$integration-test` test-update gate** — **MUST ATTENTION — MANDATORY after the fix for every standalone call.** Invoke it first to inspect changed behavior and add/update regression coverage. Use integration coverage across a real process/service boundary or for externally observable behavior; use `$test` only for a justified unit seam and record why. An existing suite run does not replace a regression update. Read `integration-test-reference.md` from the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) first.
> 4. **`$spec` spec-correctness check** — *CONDITIONAL, ensures spec docs aren't left stale.* From the proven root cause, decide which case holds:
>    - **Spec WRONG / stale** — behavior was never true or intended behavior changed without a spec update → run `$spec [mode=amend]` for §1-§7, then `$spec [mode=sync]` for §8 `TC-{FEATURE}-{NNN}` ↔ integration tests.
>    - **Spec CORRECT, code failed it** — no §1-§7 amendment. If the bug case is absent from §8, run `$spec [mode=tests]` to add it, then `$spec [mode=sync]`; if an existing TC covers it, record `Spec verified correct, bug case already in §8 — no spec change (code-only defect)` with `file:line`. Never leave the bug case absent from §8.
>    - **No governing spec** — record `No governing spec — nothing to amend` with `file:line`; if warranted, run `$spec [mode=init]`, then `[mode=tests]` to seed the bug-case regression TC. Decide explicitly; skip only amendment, never the decision.
> 5. **`$why-review`** — the last REVIEW todo after fix, test-update, spec decision, and `$changes-review`; sign off root-cause ownership, lowest-layer fix, no symptom patch, regression coverage, and justified §4 decision. Trivial non-functional fixes may satisfy it inline/briefly.
> 6. **Verify once** (`SYNC:verify-last-order`) — the final todo, after every review: `$integration-test --mode=verify` (or a justified `$test`) runs the regression tests once, then the mutation check (revert the fix → the regression test must fail = the RED proof); fix and re-run to green; re-run the reviews only if that edited anything. Reporting "done" is blocked until 5 passes and 6 is green on the final tree.
>
> **Production-code fixes:** add `$changes-review --defer=whole-target` before §5 (§5's `$why-review` owns the rationale review); the shared Standalone Review Gate owns placement and inside-workflow skip. **Final standalone order:** `investigate --mode=debug → [fix spine] → $integration-test` (or justified `$test`) → spec-check → changes-review (production code) → `$why-review` → verify once (`$integration-test --mode=verify` or `$test` + mutation check = the RED proof).

## Debug Mindset (NON-NEGOTIABLE)

**Skeptical + sequential. Every claim needs traced proof; confidence >80% to act.**

- Verify every hypothesis against an actual code trace; do NOT trust the first guess — why: nearest attention often finds the symptom, not the cause.
- Root-cause claims require `file:line` evidence; without a trace, state "hypothesis, not confirmed".
- Question cause and completeness: trace execution, related paths, and contributing factors.
- No "should fix it" without proof that the fix addresses the traced root cause.

## ⚠️ MANDATORY: Confidence & Evidence Gate

**MANDATORY IMPORTANT MUST ATTENTION** declare `Confidence: X%` with evidence list + `file:line` proof for EVERY claim.
**95%+** recommend freely | **80-94%** with caveats | **70-79%** list unknowns | **<70% STOP — gather more evidence.**

**Ultrathink** plan and start fixing these issues; follow Orchestration Protocol, Core Responsibilities, Subagents Team, Development Rules:
<issues>$ARGUMENTS</issues>

## Target Routing (`--target=`)

`$fix` is an intelligent router. With no flag it runs the full diagnose→fix spine below. Pass `--target=` to scope the run to a self-contained branch:

| `--target` | Behavior                                                                  |
| ---------- | ------------------------------------------------------------------------- |
| `types`    | **Branch in `references/target-types.md`** — TypeScript / type-error resolution.           |
| `ci`       | **Branch in `references/target-ci.md`** — CI / pipeline failure triage.                 |
| `issue`    | **Inline branch (below)** — tracked issue / ticket resolution.            |
| `logs`     | **Branch in `references/target-logs.md`** — log / stack-trace-driven debugging.           |
| `test`     | **Branch in `references/target-test.md`** — failing-test repair.                          |
| `ui`       | **Branch in `references/target-ui.md`** — UI / visual-defect fixes.                     |
| `review`   | **Inline branch (below)** — fix VALIDATED review findings from review report(s). |

No `--target` (or an unrecognized value) → run the full Workflow spine below; infer the right specialization from `<issues>`. When that inference selects a branch (`types|ci|logs|test|ui`), read its `references/target-<name>.md` in full FIRST (BLOCKING), exactly as an explicit `--target` does.

> **Target routing:** `--target=ci|issue|logs|review|test|ui` are `$fix` branches; invoke them through `$fix --target=...`, not separate skill names. `issue` and `review` are below in this file; `types`, `ci`, `logs`, `test` and `ui` live in `references/target-<name>.md`, read in full FIRST (BLOCKING) when that target runs — an invocation of another target never reads them.

### `--target=types` — TypeScript / type-error branch

Read `references/target-types.md` in full FIRST (BLOCKING) — it holds this branch's goal, rules and workflow. The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to it unchanged.

### `--target=ci` — CI / pipeline-failure branch

Read `references/target-ci.md` in full FIRST (BLOCKING) — it holds this branch's goal, rules and workflow. The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to it unchanged.

### `--target=issue` — tracked-issue / ticket branch

**Goal:** Investigate and fix bugs reported as tracked issues (e.g. GitHub issues) with full traceability.

**Active-goal read (BEFORE root-cause work):** resolve the active Goal Contract per `SYNC:goal-contract-satisfaction-loop` (active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md`, plans root default `plans/` with `docsRoots.plans.path` in `docs/project-config.json` overriding → create from the issue). Map the ticket's acceptance criteria to the saved success criteria; after the fix, append proof evidence and remaining gaps to the Iteration Log. Closure is blocked while any required criterion remains FAIL.

**Key Rules:**

- Link the fix back to the issue for traceability.
- Verify the fix addresses the specific reproduction steps from the issue.

**Workflow:**

1. Activate `investigate --mode=debug` and follow its workflow; this satisfies the Root-Cause Prerequisite Gate—record its report path as §2 evidence.
   > **AI Debugging Protocol:** frame the observed symptom, trace reader → storage/projection → writer → consumer/job → producer/origin, enumerate feeder paths, record hypotheses, and prove convergence forward.
   > **MUST ATTENTION READ** `.claude/docs/AI-DEBUGGING-PROTOCOL.md` for full search, risk, and confirmation rules.
2. Use external memory at `tmp/analysis/issue-[number].analysis.md` for structured analysis. **Re-read the ENTIRE analysis file before proposing any fix.**
3. **🛑 Present root cause + proposed fix → `ask user question tool` → wait for approval before implementing.**
4. Implement the approved fix.

> **Standalone Review Gate (non-workflow only):** any standalone production-code fix — the no-flag spine (Standalone Mode Minimum Contract above) **or** any `--target={ci|issue|logs|review|test|types|ui}` branch — adds a `$changes-review --defer=whole-target` todo tracking todo as the **final changes-review gate**, placed immediately before the contract's §5 `$why-review` terminal sign-off (test-update → spec-check → changes-review → why-review → verify once). A fix touching no production code (test-only, docs-only) skips it with that reason recorded. Inside a workflow, skip — the sequence handles `$changes-review`.

> **Review-loop severity floor (when `$fix` is the fix half of a review loop):** use the canonical `.claude/scripts/lib/review-policy.cjs` predicate and fix only validated findings that block the current round. Classify by consequence: **CRITICAL** = immediate material security/safety/authority/data-loss risk or a failed binary gate; **HIGH** = material supported-path correctness, contract, privacy, authority, compatibility, or likely-harm risk; **MEDIUM** = bounded but consequential edge/resilience/observability/testability/maintainability risk; **LOW** = evidenced non-blocking polish with no credible present correctness, security, privacy, authority, availability, or data-integrity impact. Round 1 is strict (CRITICAL/HIGH/MEDIUM/LOW); from round 2 onward only CRITICAL/HIGH/MEDIUM reopen a fix or re-review round, while LOW-only findings are recorded as deferred and do **not** reopen the loop. `NOT VERIFIABLE` is unresolved evidence, not LOW, and failed binary gates always block. Never re-tier a finding to reach a pass. This bounds loop work only; a standalone user request to fix a LOW-severity issue remains valid and is not refused.

The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to this branch unchanged.

### `--target=review` — validated review-findings branch

**Goal:** Close the validated blocking findings of one or more review reports (e.g. `$changes-review`, the specialist reviewers run with `--report-only`, `$why-review`) directly — the review report IS the diagnosis, so no plan ceremony is needed for local fixes.

**Input:** the report path(s) in `$ARGUMENTS` (or the consolidated review report of the active workflow). Only findings marked validated are in scope; an unvalidated finding goes back to `$why-review --validate-findings` first.

**Workflow:**

1. **Load and track** — re-read every input report; create one task per validated blocking finding (current round bar per the review-loop severity floor above). Record `FIXING` in the report next to each.
2. **Re-confirm before editing** — the cited `file:line` evidence still holds on the current tree; a finding that is a *bug with an unknown cause* (the report names a symptom, not the owning cause) goes to `$investigate --mode=debug` first — the Root-Cause Prerequisite Gate still binds that case.
3. **Fix at the owning layer** — one authoritative correction per violated invariant; group findings that share an owner. For a large or cross-module fix set, `$plan` is RECOMMENDED; it must capture the decisions, owners, risks and final gates without adding an automatic review step.
4. **Tests** — a behavior-changing fix gets a regression/preservation test for the intended behavior, written with the fix. NOT run here when the caller has a later verify step or passes `--tests=defer` — that single verify runs it, and its mutation check is the fix's RED proof (`SYNC:verify-last-order`). With NO later verify step (a standalone `$workflow-review-changes` in its default `--tests=prove` mode), re-run the affected tests and record exact results. A `$fix` that is itself the verify-step repair of a red test re-runs the failing set after each fix and follows the project's test-failure adjudication before any source or test edit.
5. **Write back** — append to the SAME report a `## Fix Log` row per finding: `FIXED` (files changed, test evidence) · `REJECTED` (new evidence that the finding is wrong — never final on the fixer's word: the caller re-validates it via `$why-review --validate-findings` or asks the user) · `DEFERRED` (round-2+ LOW only). The report stays the single living record the re-review reads.
6. **Hand back** — when a reviewer's fix phase or a workflow fix step called this branch (the `$changes-review --fix-loop` fix step, or `$workflow-review-changes`'s `fix --target=review` step), the caller owns re-review, spec and docs: the Standalone Mode Minimum Contract does not apply, skip the approval prompt, and never re-invoke `$changes-review`. Only a user-typed `$fix --target=review` is standalone: it presents the fix set once and ends with `$changes-review` over the fixed diff.

When `nested=true` (a `[Workflow]` row that merely exists in the current task list does not count) or in a reviewer's fix phase, skip approval prompts; user-typed standalone, present the fix set once via `ask user question tool` before editing. The Debug Mindset, Confidence & Evidence Gate, the review-loop severity floor above, and all SYNC gates apply to this branch unchanged.

### `--target=logs` — log / stack-trace branch

Read `references/target-logs.md` in full FIRST (BLOCKING) — it holds this branch's goal, rules and workflow. The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to it unchanged.

### `--target=test` — failing-test branch

Read `references/target-test.md` in full FIRST (BLOCKING) — it holds this branch's goal, rules and workflow. The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to it unchanged.

### `--target=ui` — UI / visual-defect branch

Read `references/target-ui.md` in full FIRST (BLOCKING) — it holds this branch's goal, rules and workflow. The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to it unchanged.

## Workflow:

If screenshots or videos are provided, use `visual analysis tooling` to describe the issue so developers can predict root causes.

### Fulfill the request

**Question Everything:** Use `ask user question tool` for probing questions about the request, constraints, and true objective. Do not assume; clarify until 100% certain.

- Use `ask user question tool` to clarify any open questions.
- Ask 1 question at a time; wait for answer before next question.
- No questions → start next step.

> **⚠️ Validate Before Fix (NON-NEGOTIABLE):** After root cause + plan, present findings + plan via `ask user question tool` and get approval BEFORE code changes; no silent fixes.
> **End-to-Start Trace Gate:** For non-trivial bugs, failed verification, stale/incorrect outputs, or behavior-changing fixes, the root-cause plan MUST ATTENTION include `Debugger Trace: End -> Start`, feeder paths, hypothesis matrix, owning layer, and forward convergence proof. If missing, STOP and run `$investigate --mode=debug` or `$investigate` before planning; the Root-Cause Prerequisite Gate re-checks trace content.

### Fix the issue

**Active-goal read (BEFORE root-cause work):** resolve the active Goal Contract per `SYNC:goal-contract-satisfaction-loop` — active `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md`, plans root default `plans/` with `docsRoots.plans.path` in `docs/project-config.json` overriding → create from the issue via `.claude/templates/goal-contract-template.md`. Saved success criteria define "fixed"; a local proof missing any required criterion is NOT complete. After proof, append root cause, evidence, and remaining gaps to the Iteration Log. Tiny fixes may skip deeper gates ONLY with a user-accepted reason in the goal file.

**AI surface?** Only if the defect sits in, or the fix creates or changes, a model call, prompt, agent, tool/MCP, retrieval or eval (see `node .claude/scripts/ai-signal-scan.cjs`): read `.claude/skills/shared/protocols/ai-engineering-gate.md` and apply it; otherwise skip this line.

Use `investigate --mode=debug` for complex problems, and the skills catalog to activate other needed skills.

> **Workflow step after `$investigate --mode=debug` (`nested=true`).** When this run is a step of a `[Workflow]` row (its own phase tasks are linked to that parent row; a row that merely exists in the current task list does not count) whose sequence already executed `$investigate --mode=debug` for this problem, consume that step's cited root-cause report and, when the workflow's `$plan` step ran, its plan. The report satisfies the Root-Cause Prerequisite Gate (its completed-parent-step skip row) and is the diagnosis: skip spine steps 1–3, spawning no `debugger`, `researcher` or `planner` sub-agent. Implement the cited plan through step 5, or plan inline from the report when no `$plan` ran. Re-confirm the cited `file:line` evidence on the current tree before editing; a symptom the report does not cover goes back to `$investigate --mode=debug`. Approval follows the `nested=true` rule in the Quick Summary, and the step ends with its report, without step 6's commit question.
>
> **Regression test in the workflow.** The workflow writes the bug's regression test before this step and does not run it. When the fix changes the seams that test drives (names, signatures, setup or fixtures), adjust the test in this step so it still reproduces the bug through the changed seams, never weakening its assertion. Tests run only in the workflow's later verify step (`SYNC:verify-last-order`): RED by reverting the fix through a hand-edit, then GREEN with it.

1. Use `debugger` subagent to find the root cause and report to the main agent. **Skip when the Root-Cause Prerequisite Gate already ran `$investigate --mode=debug` for this problem**; that report subsumes this step, so resume at planning. — why: repeating diagnosis double-runs the spine.
   1.5. Write results to `tmp/analysis/{issue-name}.analysis.md`; re-read the ENTIRE file before planning.
   1.6. Confirm it contains final symptom → reader → storage/projection → writer → consumer/job → producer/origin, all feeders, hypothesis matrix, owning layer, and forward proof.
2. Use `researcher` subagent to research root causes on the internet if needed; report back.
3. Use `planner` subagent to create the implementation plan from reports; report back.
4. **🛑 Present root cause + fix plan → `ask user question tool` → wait for user approval.**
5. Use `$plan --mode=execute` SlashCommand to implement plan step by step.
6. Final Report:

- Report changes, brief explanation, getting-started guidance, and next steps.
- Ask whether to commit and push; if yes, use `git-manager` subagent.

* **IMPORTANT:** Sacrifice grammar for concise reports; list unresolved questions at the end, if any.

**REMEMBER:**

- Generate visual assets with `visual analysis tooling`; read/analyze them against requirements. Use media processing for image edits (background removal, adjustment, cropping).

> **Spec-Loop completion gate (canonical: `SYNC:spec-loop-discipline`).** The fix is NOT done until the touched invariants close the loop: (1) every §4 [HARD] rule / §5 invariant the bug violated has a **universally-quantified property TC** ("for ALL inputs in {domain}, {invariant} holds") + boundary counter-case — not just the single reproduction example (this is the property bar the §3 regression-TC must meet, not merely an example case); (2) the fixed core-logic line is **mutation-killed** — if a mutant survives on the changed line the killing test is missing, so the bug can silently return (MUTATION-SCORE bar, not line-coverage %); (3) the finding fed BOTH the spec and the tests per the §3 spec-correctness decision AND a guarding test (Dual-Feedback) — a code-only patch with neither leaves the disease undocumented. Re-verify spec + tests + code together before declaring the fix complete.

---

## Next Steps (Standalone: after the Minimum Contract completes. Skip only when `nested=true` — a `[Workflow]` row that merely exists in the current task list does not count.)

> **The Root-Cause Prerequisite Gate and the Standalone Mode Minimum Contract above are NOT optional and NOT a question** — standalone `$fix` has already auto-run `investigate --mode=debug` (gate-enforced) → fix spine → mandatory `$integration-test` test update (or justified `$test` unit-test fallback) → conditional `$spec` check → (`$changes-review --defer=whole-target` for production code) → `$why-review` as the terminal sign-off. Do not re-ask the user whether to do those; they are the guaranteed floor.
>
> **AFTER that floor is met,** MUST ATTENTION use `ask user question tool` to offer what lies BEYOND the minimum (user decides):

- **"Proceed with full workflow (Recommended)"** — Hand off to the best-fit workflow (e.g. `workflow-bugfix`) from here to add the remaining gates the minimum spine omits — `plan --mode=validate`, `integration-test --mode=review`, `integration-test --mode=verify`, `production-readiness-review`, `security-audit`, `docs-manager --mode=update`.
- **"$test"** — Run the full test suite to verify the fix in context.
- **"Commit & push"** — Hand the proven, reviewed change to the `git-manager` subagent.
- **"Stop here"** — Minimum contract satisfied; user takes it from here.

> If THIS run is a step of a `[Workflow]` row (`nested=true`: its own phase tasks are linked to that parent row; a `[Workflow]` row that merely exists in the current task list, such as an abandoned one, does not count), skip both the contract and this menu — the workflow sequence handles diagnosis, spec sync, review, and next steps.

> **[IMPORTANT]** Use todo tracking to break ALL work into small tasks BEFORE starting. Prevents context loss from long files. Keep task depth proportional to the work.

- `domain-entities-reference.md` under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

<!-- PROTOCOL-GUIDES:START -->

> **Protocol guides** — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

- `core-engineering-principles` — Core quality gate: easy to change, easy to scale, easy to maintain, judged by future change cost; planning, implementing or reviewing any change → .claude/skills/shared/protocols/core-engineering-principles.md
- `design-distinctiveness-gate` — Design identity gate DD-1 to DD-8: subject, design plan, generic test, restraint; designing, implementing or reviewing a visual surface → .claude/skills/shared/protocols/design-distinctiveness-gate.md
- `design-review-checklist` — Executable front-end design review protocol CL-1 to CL-6; reviewing, planning or building front-end work → .claude/skills/shared/protocols/design-review-checklist.md
- `domain-entity-change-gate` — DDD entity, value object and aggregate change gate; planning, implementing or reviewing a domain model change → .claude/skills/shared/protocols/domain-entity-change-gate.md
- `end-to-start-debugger-trace` — Walk backward from the observed end state through every feeder path before fixing; investigating non-trivial bugs or failed verification, changing code behavior, or tracing unclear code flow → .claude/skills/shared/protocols/end-to-start-debugger-trace.md
- `environment-fault-hypothesis` — Weigh the environment as a competing cause, with a named discriminator; judging a bug report, failing test, error or unexpected output → .claude/skills/shared/protocols/environment-fault-hypothesis.md
- `evidence-based-reasoning` — Ground every material claim in file:line, config or source evidence, with stated confidence; making any claim, finding or recommendation → .claude/skills/shared/protocols/evidence-based-reasoning.md
- `fix-layer-accountability` — Fix at the component that owns the violated contract, not at the crash site; choosing where to apply a fix → .claude/skills/shared/protocols/fix-layer-accountability.md
- `measured-capacity-engineering` — Model demand, reduce measured work safely and prove capacity before scaling; planning, building, testing or reviewing hot paths, caches or capacity → .claude/skills/shared/protocols/measured-capacity-engineering.md
- `prototype-design-system` — Prototype design-system page PD-1 to PD-6: tokens and a live catalog of reusable controls beside every mock-up, each control built once and planned before the pages; generating a mock-up or prototype, or planning or building one → .claude/skills/shared/protocols/prototype-design-system.md
- `root-cause-debugging` — Systematic root-cause debugging, never guess-and-check; debugging a failure → .claude/skills/shared/protocols/root-cause-debugging.md
- `severity-rubric` — One consequence-based Critical, High, Medium, Low scale for every finding and gate; classifying a finding or deciding whether a review round passes → .claude/skills/shared/protocols/severity-rubric.md
- `source-test-drift-check` — When source behavior changes, reconcile the affected tests from evidence; code, fix, test or review work changes behavior → .claude/skills/shared/protocols/source-test-drift-check.md
- `task-tracking-external-report` — Task breakdown before the work and report files written incrementally; starting any multi-step skill, plan or review → .claude/skills/shared/protocols/task-tracking-external-report.md
- `test-failure-fault-adjudication` — Decide whether the source or the test is at fault before editing either; a test fails → .claude/skills/shared/protocols/test-failure-fault-adjudication.md
- `ui-action-density-gate` — Action and attention gate AD-1 to AD-6: one primary text button, lighter forms for other actions, uniform groups, named icons, a copy budget, regular aligned grids; designing, mocking up, building or reviewing a user-facing surface with actions or text → .claude/skills/shared/protocols/ui-action-density-gate.md
- `understand-code-first` — Read and trace the target and existing patterns before changing code; planning or editing code → .claude/skills/shared/protocols/understand-code-first.md
- `verify-last-order` — Build all phases and write tests, review statically, then verify on

…(truncated)
