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.
[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.
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 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.
Workflow:
- Investigation — Use researcher subagents to explore the issue in parallel; use
$investigate inline for tracing (an optional graph hint may help).
- Diagnose — Trace root cause through code paths with evidence
- Plan — Create fix plan with impact analysis
- Fix — Implement the fix with its regression test; tests run once in the verify step, not here (
SYNC:verify-last-order)
- 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={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
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:
$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.
- Fix spine — this skill's
plan → 🛑 approve → implement body below; Validate-Before-Fix remains unchanged.
$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.
$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.
$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.
- 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:
$ARGUMENTS
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:
- 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.
- Use external memory at
tmp/analysis/issue-[number].analysis.md for structured analysis. Re-read the ENTIRE analysis file before proposing any fix.
- 🛑 Present root cause + proposed fix →
ask user question tool → wait for approval before implementing.
- 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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Use
researcher subagent to research root causes on the internet if needed; report back.
- Use
planner subagent to create the implementation plan from reports; report back.
- 🛑 Present root cause + fix plan →
ask user question tool → wait for user approval.
- Use
$plan --mode=execute SlashCommand to implement plan step by step.
- 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 — 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)
1---2name: fix-33description: '[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.'4disable-model-invocation: false5metadata:6 source: https://skillmd.com/skills/duc01226/fix-37---89> Codex compatibility note:10> - 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.11> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.12> - 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.13> - 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.14> - 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.15<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->1617> **[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.18> **[BLOCKING]** Before each step or sub-skill call, update todo tracking: `in_progress` on start, `completed` on end.19> **[BLOCKING]** Every completed/skipped step MUST include evidence or explicit skip reason.20> **[BLOCKING]** If Task tools unavailable, maintain equivalent step-by-step plan tracker with same status transitions.2122<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->2324> **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.2526## Quick Summary2728**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.2930**Summary:**3132- **Purpose:** Diagnose end-to-start, fix the lowest invariant-owning layer, update regression coverage and spec/tests; NEVER patch symptoms.33- **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.34- **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.35- **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.36- **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).3738**Workflow:**39401. **Investigation** — Use researcher subagents to explore the issue in parallel; use `$investigate` inline for tracing (an optional graph hint may help).412. **Diagnose** — Trace root cause through code paths with evidence423. **Plan** — Create fix plan with impact analysis434. **Fix** — Implement the fix with its regression test; tests run once in the verify step, not here (`SYNC:verify-last-order`)445. **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).4546**Key Rules:**4748- **Root-Cause Prerequisite Gate (BLOCKING):** no code edit until `$investigate --mode=debug` traced THIS problem in THIS session — evidence, not recall49- Debug Mindset: every claim needs `file:line` evidence50- Use subagents for parallel investigation of multiple hypotheses51- Always create a plan before implementing complex fixes52- **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.5354## Contents5556- [Quick Summary](#quick-summary)57- [First Principle — Easy to Change · Easy to Scale · Easy to Maintain](#first-principle--easy-to-change--easy-to-scale--easy-to-maintain)58- [Default Mode Policy](#default-mode-policy)59- [🛑 Root-Cause Prerequisite Gate (Direct `$fix` Invocation) — BLOCKING](#-root-cause-prerequisite-gate-direct-fix-invocation--blocking)60- [Standalone Mode Minimum Contract (Non-Workflow Only)](#standalone-mode-minimum-contract-non-workflow-only)61- [Debug Mindset (NON-NEGOTIABLE)](#debug-mindset-non-negotiable)62- [⚠️ MANDATORY: Confidence & Evidence Gate](#️-mandatory-confidence--evidence-gate)63- [Target Routing (`--target=`)](#target-routing---target)64- [Workflow:](#workflow)65- [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)66- [Closing Reminders](#closing-reminders)6768## First Principle — Easy to Change · Easy to Scale · Easy to Maintain6970> The full gate is `SYNC:core-engineering-principles` (protocol guide below; a hook delivers its text); its closing digest ends this file.7172---7374## Default Mode Policy7576> **Default mode HARD.** Every section below applies: parallel researcher subagents, `file:line` root-cause tracing, Confidence & Evidence Gate, impact plan, and bug-preservation tests.77>78> **Fast mode ONLY when ALL 5 conditions hold** (genuinely trivial bug):79>80> - Root cause obvious from error and already located; no diagnosis needed81> - One file; ≤10 changed lines82> - No cross-service impact or contract change83> - Existing bug test, or non-functional typo/log-message fix84> - Fix confidence ≥95% without further investigation85>86> Any condition fails → full protocol; in doubt use HARD. Non-trivial fixes cannot skip diagnosis.87>88> **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.8990## 🛑 Root-Cause Prerequisite Gate (Direct `$fix` Invocation) — BLOCKING9192> **[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.93>94> **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.95>96> **2. Check — evidence, never memory.** Before the first code edit, accept only same-session, same-problem `$investigate --mode=debug` evidence:97>98> - a the current task list row for `investigate --mode=debug` (or its phase tasks) covering this symptom, **or**99> - 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.100>101> No evidence → NOT run. Recalling that the cause "is known" is not proof. — why: context compaction preserves belief, not findings.102>103> **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.104>105> **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.106>107> **5. Skip conditions — explicit, narrow, and recorded.** Record which one applies with its proof; never skip silently:108>109> | Condition | Skip? |110> | -------------------------------------------------------------------------------------------------------------------------- | ----- |111> | Same-problem evidence per §2 exists → cite the `file:line` / task-row proof and proceed | YES |112> | 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 |113> | Active parent workflow row whose sequence **already executed** `investigate --mode=debug` for this problem → cite the completed step | YES |114> | `--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 |115> | Active parent workflow row **alone**, with no completed `investigate --mode=debug` step for this problem | **NO** |116>117> **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.118>119> **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.120121## Standalone Mode Minimum Contract (Non-Workflow Only)122123> **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.124>125> **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`.126>127> **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:128>129> 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.130> 2. **Fix spine** — this skill's `plan → 🛑 approve → implement` body below; Validate-Before-Fix remains unchanged.131> 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.132> 4. **`$spec` spec-correctness check** — *CONDITIONAL, ensures spec docs aren't left stale.* From the proven root cause, decide which case holds:133> - **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.134> - **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.135> - **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.136> 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.137> 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.138>139> **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).140141## Debug Mindset (NON-NEGOTIABLE)142143**Skeptical + sequential. Every claim needs traced proof; confidence >80% to act.**144145- Verify every hypothesis against an actual code trace; do NOT trust the first guess — why: nearest attention often finds the symptom, not the cause.146- Root-cause claims require `file:line` evidence; without a trace, state "hypothesis, not confirmed".147- Question cause and completeness: trace execution, related paths, and contributing factors.148- No "should fix it" without proof that the fix addresses the traced root cause.149150## ⚠️ MANDATORY: Confidence & Evidence Gate151152**MANDATORY IMPORTANT MUST ATTENTION** declare `Confidence: X%` with evidence list + `file:line` proof for EVERY claim.153**95%+** recommend freely | **80-94%** with caveats | **70-79%** list unknowns | **<70% STOP — gather more evidence.**154155**Ultrathink** plan and start fixing these issues; follow Orchestration Protocol, Core Responsibilities, Subagents Team, Development Rules:156<issues>$ARGUMENTS</issues>157158## Target Routing (`--target=`)159160`$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:161162| `--target` | Behavior |163| ---------- | ------------------------------------------------------------------------- |164| `types` | **Branch in `references/target-types.md`** — TypeScript / type-error resolution. |165| `ci` | **Branch in `references/target-ci.md`** — CI / pipeline failure triage. |166| `issue` | **Inline branch (below)** — tracked issue / ticket resolution. |167| `logs` | **Branch in `references/target-logs.md`** — log / stack-trace-driven debugging. |168| `test` | **Branch in `references/target-test.md`** — failing-test repair. |169| `ui` | **Branch in `references/target-ui.md`** — UI / visual-defect fixes. |170| `review` | **Inline branch (below)** — fix VALIDATED review findings from review report(s). |171172No `--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.173174> **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.175176### `--target=types` — TypeScript / type-error branch177178Read `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.179180### `--target=ci` — CI / pipeline-failure branch181182Read `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.183184### `--target=issue` — tracked-issue / ticket branch185186**Goal:** Investigate and fix bugs reported as tracked issues (e.g. GitHub issues) with full traceability.187188**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.189190**Key Rules:**191192- Link the fix back to the issue for traceability.193- Verify the fix addresses the specific reproduction steps from the issue.194195**Workflow:**1961971. Activate `investigate --mode=debug` and follow its workflow; this satisfies the Root-Cause Prerequisite Gate—record its report path as §2 evidence.198 > **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.199 > **MUST ATTENTION READ** `.claude/docs/AI-DEBUGGING-PROTOCOL.md` for full search, risk, and confirmation rules.2002. Use external memory at `tmp/analysis/issue-[number].analysis.md` for structured analysis. **Re-read the ENTIRE analysis file before proposing any fix.**2013. **🛑 Present root cause + proposed fix → `ask user question tool` → wait for approval before implementing.**2024. Implement the approved fix.203204> **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`.205206> **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.207208The Debug Mindset, Confidence & Evidence Gate, and all SYNC gates below apply to this branch unchanged.209210### `--target=review` — validated review-findings branch211212**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.213214**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.215216**Workflow:**2172181. **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.2192. **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.2203. **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.2214. **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.2225. **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.2236. **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.224225When `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.226227### `--target=logs` — log / stack-trace branch228229Read `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.230231### `--target=test` — failing-test branch232233Read `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.234235### `--target=ui` — UI / visual-defect branch236237Read `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.238239## Workflow:240241If screenshots or videos are provided, use `visual analysis tooling` to describe the issue so developers can predict root causes.242243### Fulfill the request244245**Question Everything:** Use `ask user question tool` for probing questions about the request, constraints, and true objective. Do not assume; clarify until 100% certain.246247- Use `ask user question tool` to clarify any open questions.248- Ask 1 question at a time; wait for answer before next question.249- No questions → start next step.250251> **⚠️ 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.252> **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.253254### Fix the issue255256**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.257258**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.259260Use `investigate --mode=debug` for complex problems, and the skills catalog to activate other needed skills.261262> **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.263>264> **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.2652661. 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.267 1.5. Write results to `tmp/analysis/{issue-name}.analysis.md`; re-read the ENTIRE file before planning.268 1.6. Confirm it contains final symptom → reader → storage/projection → writer → consumer/job → producer/origin, all feeders, hypothesis matrix, owning layer, and forward proof.2692. Use `researcher` subagent to research root causes on the internet if needed; report back.2703. Use `planner` subagent to create the implementation plan from reports; report back.2714. **🛑 Present root cause + fix plan → `ask user question tool` → wait for user approval.**2725. Use `$plan --mode=execute` SlashCommand to implement plan step by step.2736. Final Report:274275- Report changes, brief explanation, getting-started guidance, and next steps.276- Ask whether to commit and push; if yes, use `git-manager` subagent.277278* **IMPORTANT:** Sacrifice grammar for concise reports; list unresolved questions at the end, if any.279280**REMEMBER:**281282- Generate visual assets with `visual analysis tooling`; read/analyze them against requirements. Use media processing for image edits (background removal, adjustment, cropping).283284> **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.285286---287288## 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.)289290> **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.291>292> **AFTER that floor is met,** MUST ATTENTION use `ask user question tool` to offer what lies BEYOND the minimum (user decides):293294- **"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`.295- **"$test"** — Run the full test suite to verify the fix in context.296- **"Commit & push"** — Hand the proven, reviewed change to the `git-manager` subagent.297- **"Stop here"** — Minimum contract satisfied; user takes it from here.298299> 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.300301> **[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.302303- `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)304305<!-- PROTOCOL-GUIDES:START -->306307> **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.308309- `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.md310- `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.md311- `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.md312- `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.md313- `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.md314- `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.md315- `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.md316- `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.md317- `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.md318- `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.md319- `root-cause-debugging` — Systematic root-cause debugging, never guess-and-check; debugging a failure → .claude/skills/shared/protocols/root-cause-debugging.md320- `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.md321- `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.md322- `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.md323- `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.md324- `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.md325- `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.md326- `verify-last-order` — Build all phases and write tests, review statically, then verify on327328…(truncated)