1---
2name: debug-investigate
3description: "[Fix & Debug] Use when investigating a bug's root cause — reproduce the symptom, trace it end-to-start through the code, form and test hypotheses, and pinpoint the defect before any fix."
4metadata:
5 source: https://skillmd.com/skills/duc01226/debug-investigate
6---
7
8> Codex compatibility note:
9>
10> - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references.
11> - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
12> - User-question prompts mean to ask the user directly in Codex.
13> - Ignore Claude-specific mode-switch instructions when they appear.
14> - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
15> - 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.
16> - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
17> - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
18> - If a required step/tool cannot run in this environment, stop and ask the user before adapting.
19
20<!-- CODEX:PROJECT-REFERENCE-LOADING:START -->
21
22## Codex Project-Reference Loading (No Hooks)
23
24Codex uses static project-reference loading instead of runtime-injected project docs.
25When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.
26
27**Always read:**
28
29- `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings)
30- `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog)
31- `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns)
32
33**Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=<key>`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it.
34
35**Situation-based docs:**
36
37- Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md`
38- Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md`
39- Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md`
40- Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`
41- Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above
42- Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/`
43- Integration test implementation/review: `integration-test-reference.md`
44- E2E test implementation/review: `e2e-test-reference.md`
45- Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files
46
47Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task.
48
49<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->
50
51<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->
52
53> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.
54> **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends.
55> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.
56> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
57
58<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->
59
60## Quick Summary
61
62**Goal:** Deliver a `$why-review`-validated root cause pinned to `file:line` at the invariant-owning layer — investigation-only, so `$fix` corrects the cause, not the symptom — or an honest "hypothesis, not confirmed" naming the evidence gaps.
63
64**Summary:**
65
66- **Purpose — investigation-ONLY:** pin the root cause, NEVER patch here; the deliverable is a `$why-review`-validated cause handed to `$fix`, or an honest "hypothesis, not confirmed."
67- **Main steps in order (the digest):** (0) **Classify** bug type — Phase 0, BLOCKING — routes to `debugger` / `performance-optimizer` / `security-auditor` and decides which evidence matters; (0.5) **Adjudicate fault** — failing/flaky integration test ONLY: READ the `$integration-test-review` gate protocol (never invoke it) and emit one verdict — TEST-WRONG · TEST-NOT-OPTIMAL · SOURCE-WRONG · ENVIRONMENT · AMBIGUOUS — BEFORE any trace, because tracing the source first silently assumes the test is right; (1) **Reproduce** with evidence (error/stack/screenshot); (2) **Hypothesize** 2-3 ranked theories + the evidence that confirms/contradicts each; (3) **Trace END-to-START** — name Frame 0 (observed final state), walk reader → storage/projection → writer → consumer/job → producer, enumerate ALL feeder paths; (4) **Confirm** one cause explains ALL symptoms via the hypothesis matrix, no bypass paths; (5) **Validate** through the `$why-review` gate; (6) **Report** the confidence-tagged finding + hand off to `$fix` → `$prove-fix` runs after the fix.
68- **Core discipline:** the bug enters where bad state is WRITTEN, not where it crashes — fix at the LOWEST invariant-owning layer, NEVER the crash site.
69- **Evidence law:** every root-cause claim carries `Confidence: X%` + `file:line` proof; below 60% report "hypothesis, not confirmed" with named gaps, NEVER a guess. Run a graph trace when `graph.db` exists — it surfaces bus/event consumers grep cannot see.
70- **`$why-review` gate is non-negotiable:** run it in the SAME session/main agent before declaring confirmed; 2 rounds without passing → STOP and escalate by asking the user directly.
71
72**Workflow:**
73
741. **Classify** — Detect bug scenario type (Phase 0) → route to specialized agent
75 1.5. **Adjudicate** — Failing integration test? Read `$integration-test-review` gates (Phase 0.5) → emit fault verdict before tracing
762. **Reproduce** — Confirm expected vs actual with evidence
773. **Hypothesize** — Form 2-3 ranked theories
784. **Trace** — Follow code paths; collect `file:line` proof per hypothesis
795. **Confirm** — Single root cause explains ALL symptoms
806. **Validate** — Trigger `$why-review` on findings/root cause before declaring confirmed
817. **Report** — Confidence-tagged finding + hand off to `$fix`
82
83**Key Rules:**
84
85- NEVER patch symptoms — trace full call chain, fix at owning layer
86- NEVER report root cause without `file:line` evidence
87- NEVER declare confirmed root cause without passing the `$why-review` validation gate
88- Output: confirmed root cause OR "hypothesis, not confirmed" + evidence gaps
89
90## Phase 0: Classify Bug Scenario (BLOCKING — Do Before ANY Investigation)
91
92**Think:** What type of failure is this? Classification routes to the right agent and determines which evidence matters most.
93
94| Bug Type | Signals | Specialized Agent |
95| ------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
96| Frontend UI / rendering | Console errors, visual regression, component state | `debugger` |
97| Backend logic / data | Wrong API response, data corruption, validation failure | `debugger` |
98| Cross-service / message bus | Events not propagating, consumer failures, sync lag | `debugger` + graph trace MANDATORY |
99| Performance / memory | Slow queries, OOM, N+1, unbounded result sets | `performance-optimizer` |
100| Security / auth | Access denied, token issues, permission bypass | `security-auditor` |
101| **Failing / flaky integration test** | A test that was green now fails, fails intermittently, or fails only in a full-suite run | `debugger` + **READ the `$integration-test-review` protocol FIRST** (see Fault Adjudication below) |
102
103**Cross-service bugs:** Run graph trace FIRST — grep alone misses implicit bus connections.
104**OOM / memory exhaustion:** Check row COUNT before row SIZE. Unbounded query loading thousands of records is more common cause. Triage: (1) missing DB-level filter? (2) excessive row size?
105
106### Phase 0.5: Fault Adjudication — failing integration tests (BLOCKING for that bug type)
107
108> **Think:** a failing test has TWO candidate defendants — source and test. Tracing source first ASSUMES the test is right; that assumption produces the "fix" rationalizing a broken invariant into green. Decide _whose fault_ before deciding _where to trace_.
109
110**Step 1 — READ the protocol; NEVER invoke the skill.** Read `.claude/skills/integration-test-review/SKILL.md` §"The 8 Quality Gates" into context. Gates 1 (assertion value), 3 (repeatability), 4 (domain logic), 8 (scenario fidelity) reveal whether the TEST is the faulty party — dead/always-true assertion, non-unique ID, assertion on fields the handler never writes, unreachable setup.
111
112> **MUST NOT invoke `$integration-test-review` from here — READ its protocol instead.** Inside `integration-test-verify-loop`, this skill already runs in the SAME round as an explicit `$integration-test-review` call (`integration-test-verify-loop/SKILL.md:110`, `:495`); invoking it again runs a 9-phase audit twice per round — the duplicate-ownership defect that loop removes (`:31`). The loop OWNS the invocation. — why: standalone, reading also suffices — investigation is this skill's only deliverable.
113
114**Step 2 — emit ONE fault verdict before any trace.**
115
116| Verdict | Meaning | Where to trace next |
117| -------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
118| **TEST-WRONG** | Stale assertion, wrong setup, non-unique data, unreachable scenario | The test's own root cause — fix the assertion/setup at its root, NEVER weaken it |
119| **TEST-NOT-OPTIMAL** | Test is right but fragile — timing, shared state, ordering dependence | The fragility's source (missing ARRANGE barrier, shared infra assertion) |
120| **SOURCE-WRONG** | Production code violates the spec or a clear invariant | Normal end-to-start trace to the invariant-owning layer; KEEP or strengthen the test |
121| **ENVIRONMENT** | Config, DB, credentials, ports, versions | Mark BLOCKED — do not trace application code |
122| **AMBIGUOUS** | Spec silent or contradictory about which side is correct | **STOP and ask the user** by asking the user directly — never self-resolve |
123
124**Step 3 — governing law (`CLAUDE.md:160`, mirrored `AGENTS.md:446`):** _"A green-again suite is not the goal; the correct verdict on what was actually wrong is."_ NEVER weaken an assertion, add a skip, or relax a timeout to force green; NEVER change source to satisfy a broken test — instead fix the faulty party the verdict named, at its owning layer. Spec silent or ambiguous → STOP and ask.
125
126## Debug Mindset (NON-NEGOTIABLE)
127
128**Skeptical. Sequential. Every claim needs traced proof, confidence >80%.**
129
130- NEVER assume first hypothesis correct — verify with actual code traces
131- Every root cause claim MUST include `file:line` evidence
132- Cannot prove root cause → state "hypothesis, not confirmed"
133- Challenge assumptions: "Is this really the cause?" → trace actual execution path
134- Challenge completeness: "Other contributing factors?" → check related code paths
135
136## Confidence & Evidence Gate
137
138**MUST ATTENTION** declare `Confidence: X%` + evidence list + `file:line` proof for EVERY claim.
139
140| Confidence | Meaning | Action |
141| ---------- | ---------------------------------------- | ------------------------------------ |
142| 95-100% | Full trace verified | Report as confirmed root cause |
143| 80-94% | Main path verified, edge cases uncertain | Report with caveats |
144| 60-79% | Partial trace | Report as hypothesis |
145| <60% | Insufficient evidence | DO NOT report — gather more evidence |
146
147## Investigation Dimensions
148
149Reason through each dimension — state what fails if weak, then apply with evidence.
150
151### Dim 1: Reproduce
152
153**Think:** What exact conditions trigger this? Data state? User action? Timing? Environment delta?
154
155- Confirm issue exists with evidence (error message, stack trace, screenshot)
156- Identify trigger: user action, data state, timing, env difference
157
158### Dim 2: Hypothesize
159
160**Think:** Given symptoms, what are the most plausible failure modes? What would confirm vs contradict each?
161
162- Form 2-3 theories ranked by likelihood
163- Note evidence needed to confirm/contradict each theory before investigating
164
165### Dim 3: End-to-Start Trace
166
167**Think:** What exact final output proves the bug? Which reader produced it? Which storage/projection/write path fed that reader? Where does bad state ENTER the system — not where it CRASHES? Which layer owns this invariant?
168
169- Name Frame 0: observed final state (UI, API response, log, persisted value, assertion, aggregate)
170- Identify the final reader/query/renderer/assertion and the state it consumes
171- Walk backward: reader -> storage/projection/cache -> writer -> consumer/handler/job -> producer/origin
172- Enumerate every feeder path that can write the same final state
173- Check error handling paths
174- Collect `file:line` evidence per hypothesis
175- Use graph trace for implicit connections (event handlers, bus consumers)
176
177### Dim 4: Confirm
178
179**Think:** Does this root cause explain ALL symptoms? Are there bypass paths that skip the fix point?
180
181- Match evidence to single root cause
182- Verify root cause explains ALL observed symptoms
183- Check secondary contributing factors
184- Build hypothesis matrix: primary, contributing, ruled out, latent, unknown
185- Resolve or disclose competing causes before proposing a fix
186- Verify no bypass paths (direct construction, clone/spread without re-validation, mutations outside model layer)
187
188### Dim 5: Report
189
190- Output: confirmed root cause + evidence chain
191- Include: affected files, Debugger Trace: End -> Start, feeder paths, hypothesis matrix, data flow summary, owning fix layer, fix recommendation, forward convergence proof
192- Hand off to `$fix` for implementation
193
194## Dependency Tracing (MANDATORY when graph.db exists)
195
196**MUST ATTENTION** use structural queries — graph reveals ALL callers/consumers grep misses.
197
198```bash
199# Who calls the buggy function
200python .claude/scripts/code_graph query callers_of <function> --json
201
202# Who imports the buggy module
203python .claude/scripts/code_graph query importers_of <file> --json
204
205# What tests exist
206python .claude/scripts/code_graph query tests_for <function> --json
207
208# Full upstream + downstream context
209python .claude/scripts/code_graph trace <suspect-file> --direction both --json
210
211# Callers only (find all trigger points)
212python .claude/scripts/code_graph trace <suspect-file> --direction upstream --json
213```
214
215Graph reveals implicit connections (MESSAGE_BUS, event handlers) that propagate issues across services — invisible to grep.
216
217## Root Cause Validation (`$why-review` Gate)
218
219NEVER declare a confirmed root cause straight from investigation. Run `$why-review` as a quality validation gate on the findings and root cause — in the SAME session, SAME main agent (do NOT spawn a sub-agent) — before handing off to `$fix`.
220
221**Step 1 — Investigate (main agent):** Identify root cause + full evidence chain. Write findings to report file.
222
223**Step 2 — Validate (`$why-review`, same main agent):** Trigger `$why-review` on the findings/root cause. The gate must confirm:
224
225- Root cause is correct and reasonable, with `file:line` evidence that conclusively supports it
226- Evidence has no gaps and explains ALL symptoms
227- The proposed fix direction would NOT introduce other bugs or regressions (check downstream consumers, bypass paths, owning layer)
228
229**Decision:**
230
231- `$why-review` PASSES → declare confirmed, proceed to `$fix`
232- `$why-review` finds GAPS/risks → collect additional evidence, repeat
233- 2 validation rounds without passing → STOP, escalate to user by asking the user directly
234
235## ⚠️ MANDATORY: Post-Fix Verification
236
237After `$fix` applies changes, `$prove-fix` MUST be run — builds code proof traces per change with confidence scores. Non-negotiable in all fix workflows.
238
239## Anti-Rationalization (Red Flags)
240
241| Evasion | Rebuttal |
242| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
243| "I see the problem, let me fix it" | Symptoms ≠ root cause. Investigate first. |
244| "Quick fix for now, investigate later" | Quick fixes mask bugs. Find root cause. |
245| "Just try changing X and see" | One hypothesis at a time. Scientific method, not trial and error. |
246| "Already tried 2+ fixes, one more" | 3+ failed fixes = STOP. Question the architecture, not the fix. |
247| "The error message is misleading" | Read it again carefully. Error messages are usually right. |
248| "It works on my machine" | Reproduce in the failing environment. Your environment hides bugs. |
249| "This can't be the cause" | Verify with evidence, not intuition. Unlikely causes are still causes. |
250| "It's OOM, must be a large object" | Check row COUNT before row SIZE. Unbounded query > large single row. |
251| "Skip `$why-review`, findings look solid" | Self-confirmed findings rationalize their own gaps. The `$why-review` gate is non-negotiable. |
252| "Graph.db not needed for this bug" | Cross-service bugs are invisible to grep. Run trace first. |
253
254---
255
256## Workflow Recommendation
257
258**MUST ATTENTION — NO EXCEPTIONS:** Not in workflow? Use ask the user directly:
259
2601. **Activate `workflow-bugfix` workflow** (Recommended) — scout → investigate → debug → plan → fix → prove-fix → review → test
2612. **Execute `$debug-investigate` directly** — standalone
262
263---
264
265## Next Steps (Standalone only — skip if inside workflow)
266
267**MUST ATTENTION** use ask the user directly after completing. NEVER auto-decide next step:
268
269- **"Proceed with full workflow (Recommended)"** — detect best workflow to continue from here
270- **"$fix"** — apply fix based on debug findings
271- **"$plan"** — if fix requires planning first
272- **"Skip, continue manually"** — user decides
273
274**Standalone Review Gate:** Outside workflow? MUST create `$changes-review` task as LAST task.
275
276---
277
278> **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files.
279
280- `docs/project-reference/domain-entities-reference.md` — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)
281
282<!-- SYNC:end-to-start-debugger-trace -->
283
284> **End-to-Start Debugger Trace** — For non-trivial bugs, failed verification, regression fixes, behavior-changing code, or unclear code flow, start from the observed final state and walk backward before proposing a fix.
285>
286> 1. **Frame 0: observed end state** — Name the exact user-visible output, failing assertion, log line, persisted value, API response, rendered UI, or aggregate bucket. Record the reader/query/renderer that produced it with `file:line` evidence.
287> 2. **Walk backward one hop at a time** — Trace final reader -> projection/cache/storage -> writer -> consumer/handler/job -> producer/caller -> original trigger. At every hop record: input, transformation, output, owner, and evidence.
288> 3. **Enumerate all feeder paths** — Find every upstream producer/caller/event/job that can write into the final path, including retry, async, cache, background, and alternate UI/API paths. Mark each path verified, ruled out, or still unknown.
289> 4. **Build the hypothesis matrix** — For each plausible cause, list evidence for, evidence against, how to reproduce/verify, blast radius, and status (`primary`, `contributing`, `ruled out`, `latent`). Do not fix until competing causes are explicitly resolved or bounded.
290> 5. **Choose the owning fix layer** — Identify the invariant owner and the lowest shared point that protects all downstream consumers. A fix at the symptom site is rejected unless the symptom site owns the invariant.
291> 6. **Prove convergence forward** — After choosing the fix, walk start -> end again and show how the corrected state reaches the observed final output. Map each root cause to a fix part and each fix part to a test/proof.
292>
293> **BLOCKED until:** final state named · backward trace written · all feeder paths enumerated · hypothesis matrix completed · owning fix layer justified · forward convergence proof mapped to tests.
294>
295> **NEVER:** Start at the first suspicious code path. Collapse multiple producers into one "flow". Treat duplicate symptoms as duplicate records without proving the read model. Skip ruled-out hypotheses.
296
297<!-- /SYNC:end-to-start-debugger-trace -->
298
299<!-- SYNC:root-cause-debugging -->
300
301> **Root Cause Debugging** — Systematic approach, never guess-and-check.
302>
303> 1. **Reproduce** — Confirm the issue exists with evidence (error message, stack trace, screenshot)
304> 2. **Isolate** — Narrow to specific file/function/line using binary search + graph trace
305> 3. **Trace** — Follow data flow from input to failure point. Read actual code, don't infer.
306> 4. **Hypothesize** — Form theory with confidence %. State what evidence supports/contradicts it
307> 5. **Verify** — Test hypothesis with targeted grep/read. One variable at a time.
308> 6. **Fix** — Address root cause, not symptoms. Verify fix doesn't break callers via graph `connections`
309>
310> **NEVER:** Guess without evidence. Fix symptoms instead of cause. Skip reproduction step.
311
312<!-- /SYNC:root-cause-debugging -->
313
314<!-- SYNC:incremental-persistence -->
315
316> **Incremental Result Persistence** — MANDATORY for all sub-agents or heavy inline steps processing >3 files.
317>
318> 1. **Before starting:** Create report file `plans/reports/{skill}-{date}-{slug}.md`
319> 2. **After each file/section reviewed:** Append findings to report immediately — never hold in memory
320> 3. **Return to main agent:** Summary only (per SYNC:subagent-return-contract) with `Full report:` path
321> 4. **Main agent:** Reads report file only when resolving specific blockers
322>
323> **Why:** Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results.
324>
325> **Report naming:** `plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md`
326
327<!-- /SYNC:incremental-persistence -->
328
329<!-- SYNC:subagent-return-contract -->
330
331> **Sub-Agent Return Contract** — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline.
332>
333> ```markdown
334> ## Sub-Agent Result: [skill-name]
335>
336> Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
337> Confidence: [0-100]%
338>
339> ### Findings (Critical/High only — max 10 bullets)
340>
341> - [severity] [file:line] [finding]
342>
343> ### Actions Taken
344>
345> - [file changed] [what changed]
346>
347> ### Blockers (if any)
348>
349> - [blocker description]
350>
351> Full report: plans/reports/[skill-name]-[date]-[slug].md
352> ```
353>
354> Main agent reads `Full report` file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan.
355> Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.
356>
357> **Context budget** — the return payload is a SUMMARY, not a transcript: ≤10 finding bullets, no raw file contents / full diffs / verbatim logs inline, no re-pasted source. Everything beyond the summary lives in the `Full report` on disk. A sub-agent that would exceed the summary shape MUST write the detail to its report and return only the pointer — the orchestrator's context is the scarce resource the whole map-reduce protects.
358
359<!-- /SYNC:subagent-return-contract -->
360
361<!-- SYNC:source-test-drift-check -->
362
363> **Source/test drift check.** For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/integration/E2E tests and decide from evidence whether tests should change to match intended behavior or the source change is an unintended bug to fix. Do not write tests for migration code; schema/data migrations are one-time execution paths, not core application logic.
364
365<!-- /SYNC:source-test-drift-check -->
366
367<!-- SYNC:test-failure-fault-adjudication -->
368
369> **Test-Failure Fault Adjudication** — When a test fails (or you are debugging or fixing a failure), the job is to determine _who is at fault — the source code or the test code_. Getting that verdict right matters more than turning the suite green. Binds every debug / fix / test skill identically.
370>
371> 1. **Provisional verdict before touching either side.** Classify the observed evidence as SOURCE-WRONG, TEST-WRONG, TEST-NOT-OPTIMAL, ENVIRONMENT-BLOCKED, or AMBIGUOUS; then `$debug-investigate` and trace end-to-start before editing. A green-again suite is NOT the goal.
372> 2. **Triangulate against the spec AND the source.** If a governing Feature Spec covers the behavior (e.g. `docs/specs/**` — §3 ACs / §4 BRs / §5 invariants / §8 TCs), it is the tiebreaker for _intended_ behavior — compare BOTH the production source and the failing test against it. With no spec, the documented intent / acceptance criteria / caller contract is the reference. Decide from this evidence whether the SOURCE is wrong or the TEST is wrong.
373> 3. **Classify who is at fault, then fix the wrong side at its root:**
374> - **SOURCE-WRONG** — production code violates the spec's intended behavior or a clear invariant → fix the source at the owning layer; keep or strengthen the test that caught it.
375> - **TEST-WRONG** — the test encodes a stale or incorrect assertion, setup, or expectation that contradicts intended behavior → fix the test at its root. NEVER weaken an assertion, add a skip, or relax a timeout to force green.
376> - **TEST-NOT-OPTIMAL** — intended behavior is valid but the test seam, timing, or assertion signal is fragile → improve the test without weakening the invariant.
377> - **ENVIRONMENT-BLOCKED** — infrastructure or external state prevents a source/test verdict → preserve diagnostics and stop mutation until the environment is healthy.
378> - **AMBIGUOUS** — evidence or intended behavior does not safely select an owner → ask the user or canonical owner before editing.
379> - NEVER change a test to match broken source, and NEVER change source to satisfy a broken test. (Migration code excluded — schema/data migrations are one-time execution paths, not core application logic.)
380> 4. **Ask the user when intended behavior is unclear.** If no spec covers the behavior, the spec is silent, or the spec is ambiguous about which side is correct, STOP and ask the user directly (or consult the canonical spec owner) before editing either side — never silently pick source or test just to make the suite pass.
381>
382> Reconcile to intended behavior, never to whichever side currently passes — green can encode the very bug.
383
384<!-- /SYNC:test-failure-fault-adjudication -->
385
386<!-- SYNC:ai-mistake-prevention -->
387
388> **AI Mistake Prevention** — Failure modes to avoid on every task:
389>
390> **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
391> **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
392> **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
393> **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
394> **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect.
395> **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
396> **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk.
397> **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
398> **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
399
400<!-- /SYNC:ai-mistake-prevention -->
401
402<!-- SYNC:nested-task-creation -->
403
404> **Nested Task Expansion Contract** — For workflow-step invocation, the `[Workflow] ...` row is only a parent container; the child skill still creates visible phase tasks.
405>
406> 1. Call the current task list first. If a matching active parent workflow row exists, set `nested=true` and record `parentTaskId`; otherwise run standalone.
407> 2. Create one task per declared phase before phase work. When nested, prefix subjects `[N.M] $skill-name — phase`.
408> 3. When nested, link the parent with `TaskUpdate(parentTaskId, addBlockedBy: [childIds])`.
409> 4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
410> 5. Mark exactly one child `in_progress` before work and `completed` immediately after evidence is written.
411> 6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.
412>
413> **Blocked until:** the current task list done, child phases created, parent linked when nested, first child marked `in_progress`.
414
415<!-- /SYNC:nested-task-creation -->
416
417<!-- SYNC:project-reference-docs-guide -->
418
419> **Project Reference Docs Gate** — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.
420>
421> 1. Identify scope: file types, domain area, and operation.
422> 2. **Read `docs/project-config.json` first — the project's machine-readable map.** It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it **before investigating, planning, or coding** — never assume framework defaults (`CLAUDE.md` + reference docs are derived from it). If it — or the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any required reference doc — is missing or stale, auto-run `$project-init` or the narrow route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=<key>`, `$claude-md-init`) first; if Codex mirrors or `AGENTS.md` are stale, ask the user to run `$sync-codex` (never auto-run it).
423> 3. Required docs by trigger: always `docs/project-reference/lessons.md`; doc lookup `docs-index-reference.md`; review `code-review-rules.md`; backend/CQRS/API `backend-patterns-reference.md`; domain/entity `domain-entities-reference.md`; frontend/UI `frontend-patterns-reference.md`; styles/design `scss-styling-guide.md` + `design-system/design-system-canonical.md`; integration tests `integration-test-reference.md`; E2E `e2e-test-reference.md`; feature docs/specs `feature-spec-reference.md` + `spec-system-reference.md` + `spec-principles.md`; behavior/public-contract/spec-test-code sync `workflow-spec-test-code-cycle-reference.md`; derived spec index/ERD/reimplementation guides `spec-system-reference.md` + source Feature Specs under `docs/specs/`; architecture/new area `project-structure-reference.md`.
424> 4. Read every required doc, then before target work state: `Reference docs read: ... | Not applicable: ...`.
425>
426> **Ready when:** scope evaluated, `docs/project-config.json` consulted, required docs checked/read or setup route completed, `lessons.md` confirmed, citation emitted.
427
428<!-- /SYNC:project-reference-docs-guide -->
429
430<!-- SYNC:task-tracking-external-report -->
431
432> **Task Tracking & External Report Persistence** — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.
433>
434> 1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
435> 2. Mark one task `in_progress` before work and `completed` immediately after evidence; never batch transitions.
436> 3. For plan/review work, create `plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md` before first finding.
437> 4. Append findings after each file/section/decision and synthesize from the report file at the end.
438> 5. Final output cites `Full report: plans/reports/{filename}`.
439>
440> **Blocked until:** task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.
441
442<!-- /SYNC:task-tracking-external-report -->
443
444<!-- SYNC:critical-thinking-mindset -->
445
446> **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
447> **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
448
449<!-- /SYNC:critical-thinking-mindset -->
450
451<!-- SYNC:sequential-thinking-protocol -->
452
453> **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.
454>
455> **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.
456>
457> **Format (explicit mode — visible thought trail):**
458>
459> 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty
460> 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact
461> 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale
462> 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting
463> 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80%
464>
465> **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.
466>
467> **Stop conditions:** confidence <80% on any critical decision → escalate by asking the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.
468>
469> **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).
470>
471> **Deep-dive:** see `$sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).
472
473<!-- /SYNC:sequential-thinking-protocol -->
474
475<!-- SYNC:understand-code-first -->
476
477> **Understand Code First** — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
478>
479> 1. Search 3+ similar patterns (`grep`/`glob`) — cite `file:line` evidence
480> 2. Read existing files in target area — understand structure, base classes, conventions
481> 3. Run `python .claude/scripts/code_graph trace <file> --direction both --json` when `.code-graph/graph.db` exists
482> 4. Map dependencies via `connections` or `callers_of` — know what depends on your target
483> 5. Write investigation to `.ai/workspace/analysis/` for non-trivial tasks (3+ files)
484> 6. Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
485> 7. NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader
486>
487> **BLOCKED until:** `- [ ]` Read target files `- [ ]` Grep 3+ patterns `- [ ]` Graph trace (if graph.db exists) `- [ ]` Assumptions verified with evidence
488
489<!-- /SYNC:understand-code-first -->
490
491<!-- SYNC:evidence-based-reasoning -->
492
493> **Evidence-Based Reasoning** — Speculation is FORBIDDEN. Every claim needs proof.
494>
495> 1. Cite `file:line`, grep results, or framework docs for EVERY claim
496> 2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
497> 3. Cross-service validation required for architectural changes
498> 4. "I don't have enough evidence" is valid and expected output
499>
500> **BLOCKED until:** `- [ ]` Evidence file path (`file:line`) `- [ ]` Grep search performed `- [ ]` 3+ similar patterns found `- [ ]` Confidence level stated
501>
502> **Forbidden without proof:** "obviously", "I think", "should be", "probably", "this is because"
503> **If incomplete →** output: `"Insufficient evidence. Verified: [...]. Not verified: [...]."`
504
505<!-- /SYNC:evidence-based-reasoning -->
506
507<!-- SYNC:cross-service-check -->
508
509> **Cross-Service Check** — Microservices/event-driven: MANDATORY before concluding investigation, plan, spec, or feature doc. Missing downstream consumer = silent regression.
510>
511> | Boundary | Grep terms |
512> | ------------------- | ------------------------------------------------------------------------------- |
513> | Event producers | `Publish`, `Dispatch`, `Send`, `emit`, `EventBus`, `outbox`, `IntegrationEvent` |
514> | Event consumers | `Consumer`, `EventHandler`, `Subscribe`, `@EventListener`, `inbox` |
515> | Sagas/orchestration | `Saga`, `ProcessManager`, `Choreography`, `Workflow`, `Orchestrator` |
516> | Sync service calls | HTTP/gRPC calls to/from other services |
517> | Shared contracts | OpenAPI spec, proto, shared DTO — flag breaking changes |
518> | Data ownership | Other service reads/writes same table/collection → Shared-DB anti-pattern |
519>
520> **Per touchpoint:** owner service · message name · consumers · risk (NONE / ADDITIVE / BREAKING).
521>
522> **BLOCKED until:** Producers scanned · Consumers scanned · Sagas checked · Contracts reviewed · Breaking-change risk flagged
523
524<!-- /SYNC:cross-service-check -->
525
526<!-- SYNC:estimation-framework -->
527
528> **Estimation Framework** — Bottom-up first; SP DERIVED; output min-max range when likely ≥3d. Stack-agnostic. Baseline: 3-5yr dev, 6 productive hrs/day. AI estimate assumes Claude Code + project context.
529>
530> **Method:**
531>
532> 1. **Blast Radius pass** (below) — drives code AND test cost
533> 2. Decompose phases → hours/phase → `bottom_up_hours = Σ phase_hours`
534> 3. `likely_days = ceil(bottom_up_hours / 6) × productivity_factor`
535> 4. Sum **Risk Margin** (base + add-ons) → `max_days = likely_days × (1 + margin)`
536> 5. `min_days = likely_days × 0.9`
537> 6. Output as range when `likely_days ≥3`; single point allowed `<3` (still record margin)
538> 7. `man_days_ai` = same range × AI speedup
539> 8. `story_points` DERIVED from `likely_days` via SP-Days — NEVER driver. Disagreement >50% → trust bottom-up
540>
541> **Productivity factor:** 0.8 strong scaffolding+codegen+AI hooks · 1.0 mature default · 1.2 weak patterns · 1.5 greenfield
542>
543> **Cost Driver Heuristic (apply BEFORE work-type row):**
544>
545> - **UI dominates** in CRUD/business apps — 1.5-3x backend (states, validation, responsive, a11y, polish)
546> - **Backend dominates ONLY:** multi-aggregate invariants, cross-service contracts, schema migrations, heavy query/perf, new event flows
547>
548> **Reuse-vs-Create axis (PRIMARY lever, per layer):**
549>
550> | UI tier | Cost |
551> | -------------------------------------------- | -------- |
552> | Reuse component on existing screen | 0.1-0.3d |
553> | Add control/column to existing screen | 0.3-0.8d |
554> | Compose components into NEW screen | 1-2d |
555> | NEW screen, custom layout/states/validation | 2-4d |
556> | NEW shared/common component (themed, tested) | 3-6d+ |
557>
558> | Backend tier | Cost |
559> | ---------------------------------------------------- | --------- |
560> | Reuse query/handler from new place | 0.1-0.3d |
561> | Small update existing handler/entity | 0.3-0.8d |
562> | NEW query on existing repo/model | 0.5-1d |
563> | NEW command/handler on existing aggregate (additive) | 1-2d |
564> | NEW aggregate/entity (repo, validation, events) | 2-4d |
565> | NEW cross-service contract OR schema migration | 2-4d each |
566> | Multi-aggregate invariant / heavy domain rule | 3-5d |
567>
568> **Rule:** Sum tiers across UI+backend+tests, apply productivity factor. Reuse short-circuits tiers — call out.
569>
570> **Test-Scope drivers (compute test_count EXPLICITLY — "+tests" hand-wave is #1 failure):**
571>
572> | Driver | Count |
573> | --------------------------------- | ------------------------------------------------------ |
574> | Happy-path journeys | 1 per story / AC main flow |
575> | State-machine transitions | reachable transitions × allowed actors |
576> | Multi-entity state combos | state(A) × state(B) — REACHABLE only, not Cartesian |
577> | Authorization matrix | (owner, non-owner, elevated, unauth) × each mutation |
578> | Validation rules | 1 per required field / boundary / format / cross-field |
579> | UI states (per new screen/dialog) | happy, loading, empty, error, partial — present only |
580> | Negative paths / invariants | 1 per violatable business rule |
581>
582> | Test tier (Trad, incl. setup+assert+flake) | Cost |
583> | ------------------------------------------ | -------- |
584> | 1-5 cases, fixtures reused | 0.3-0.5d |
585> | 6-12 cases, 1 new fixture | 0.5-1d |
586> | 13-25 cases, multi-entity setup | 1-2d |
587> | 26-50 cases OR new state-machine coverage | 2-3d |
588> | >50 cases OR full E2E journey | 3-5d |
589>
590> **Test multipliers:** new fixture/seed harness +0.5d · cross-service/bus assertion +0.3d each · UI E2E ×1.5 · each new role +1-2 cases
591>
592> **Blast Radius (mandatory pre-pass — affects code AND test):**
593>
594> 1. Files/components directly modified — count
595> 2. Of those, "complex" (>500 LOC, multi-handler, central, frequently-modified) — count
596> 3. Downstream consumers (callers, event subscribers, cross-service) — list
597> 4. Shared/common code touched (multi-app blast) — yes/no
598> 5. Regression scope — areas needing re-test
599>
600> **Rule:** Complex touch → add `risk_factors`. Each downstream consumer → +1-3 regression cases. Blast >5 areas OR >2 complex → re-evaluate SPLIT before estimating.
601>
602> **Risk Margin (drives max bound):**
603>
604> | likely_days | Base margin |
605> | ------------------- | ------------------------------- |
606> | <1d trivial | +10% |
607> | 1-2d small additive | +20% |
608> | 3-4d real feature | +35% |
609> | 5-7d large | +50% |
610> | 8-10d very large | +75% |
611> | >10d | +100% AND **flag SHOULD SPLIT** |
612>
613> **Risk-factor add-ons (additive — enumerate in `risk_factors`):**
614>
615> | Factor | +margin |
616> | --------------------------------------------------------------------- | ------- |
617> | `touches-complex-existing-feature` (>500 LOC, multi-handler, central) | +20% |
618> | `cross-service-contract` change | +25% |
619> | `schema-migration-on-populated-data` | +25% |
620> | `new-tech-or-unfamiliar-pattern` | +30% |
621> | `regression-fan-out` (≥3 downstream areas re-test) | +20% |
622> | `performance-or-latency-critical` | +20% |
623> | `concurrency-race-event-ordering` | +25% |
624> | `shared-common-code` (multi-consumer/multi-app) | +25% |
625> | `unclear-requirements-or-design` | +30% |
626>
627> **Collapse rule:** total margin >100% → STOP, split (padding past 2x is dishonesty). Margin <15% on `likely_days ≥5` → under-estimated, widen.
628>
629> **Work-Type Caps (hard ceilings on `likely_days`):**
630> | Work type | Max SP | Max likely |
631> | --- | --- | --- |
632> | Single field / config flag / style fix | 1 | 0.5d |
633> | Add property to existing model + bind to existing UI | 2 | 1d |
634> | **Additive endpoint + minor UI control** (button/menu/column), reuses fixtures | **3** | **2-3d** |
635> | Additive endpoint + **NEW UI surface** OR additive multi-layer + new domain rule + 2+ test files | 5 | 3-5d |
636> | NEW model/aggregate OR migration OR cross-module contract OR heavy test (>1.5d) OR NEW UI + non-trivial backend | 8 | 5-7d |
637> | NEW UI surface + (NEW aggregate OR migration OR cross-service contract) | 13 | SHOULD split |
638> | Cross-service contract + migration combined | 13 | SHOULD split |
639> | Beyond | 21 | MUST split |
640>
641> **SP→Days (validation only):** 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d (Trad/AI likely)
642> **AI speedup:** SP 1≈2x · 2-3≈3x · 5-8≈4x · 13+≈5x. AI cost = `(code_gen × 1.3) + (test_gen × 1.3)` (30% review overhead).
643>
644> **MANDATORY frontmatter:**
645>
646> ```yaml
647> story_points: <n>
648> complexity: low | medium | high | critical
649> man_days_traditional: '<min>-<max>d' # range when likely ≥3d; '<N>d' when <3d
650> man_days_ai: '<min>-<max>d'
651> risk_margin_pct: <n> # base + add-ons
652> risk_factors: [touches-complex-existing-feature, regression-fan-out] # closed-list from add-ons; [] if none
653> blast_radius:
654> touched_areas: <n>
655> complex_touched: <n>
656> downstream_consumers: [list or count]
657> shared_common_code: yes | no
658> estimate_scope_included: [code, integration-tests, frontend, i18n, docs]
659> estimate_scope_excluded: [unit-tests, e2e, perf, deployment, code-review-rounds]
660> estimate_reasoning: |
661> 5-7 lines covering:
662> (a) UI tier — row applied
663> (b) Backend tier — row applied
664> (c) Test scope — case breakdown by driver, file count, fixtures, tier row
665> (d) Cost driver — dominant tier + why
666> (e) Blast radius — touched, complex, regression scope
667> (f) Risk factors — list driving margin; why not larger/smaller
668> Example: "UI: compose Form/Table/Dialog → NEW screen (~1.5d). Backend: NEW command on existing aggregate,
669> reuses validation+repo (~1d). Tests: 4 transitions × 2 actors + 3 validation + 2 UI states = 13 cases,
670> 1 new fixture → tier 13-25 ~1.5d. Driver: UI composition + new states. Blast: 4 areas, 1 complex.
671> Risk: base 35% + touches-complex +20% = 55% → max 3.9d → range 2.5-4d."
672> ```
673>
674> **Sanity self-check:**
675>
676> - `likely_days ≥3d` and single-point? → reject, must be range
677> - Margin <15% on `likely_days ≥5d`? → under-estimated, widen
678> - Margin >100%? → STOP, split instead of buffer
679> - Complex existing feature touched, no regression budget in `(c)`? → reject
680> - Blast `>5` areas OR `>2` complex, no split discussion? → reject
681> - Purely additive on existing model AND existing UI? → cap SP 3 unless tests >1.5d
682> - NEW UI surface (page/complex form/dashboard)? → SP 5+ even if backend one endpoint
683> - Backend cross-service / migration / multi-aggregate? → SP 8+ regardless of UI
684> - `bottom_up_hours / 6` vs SP-Days disagreement >50%? → trust bottom-up, downgrade SP
685> - Without tests, SP drops ≥1 bucket? → tests dominate; state explicitly
686> - Reasoning called out UI vs backend vs blast vs risk factors? → if missing, add
687
688<!-- /SYNC:estimation-framework -->
689
690<!-- SYNC:red-flag-stop-conditions -->
691
692> **Red Flag Stop Conditions** — STOP and escalate to user by asking the user directly when:
693>
694> 1. Confidence drops below 60% on any critical decision
695> 2. Changes would affect >20 files (blast radius too large)
696> 3. Cross-service boundary is being crossed
697> 4. Security-sensitive code (auth, crypto, PII handling)
698> 5. Breaking change detected (interface, API contract, DB schema)
699> 6. Test coverage would decrease after changes
700> 7. Approach requires technology/pattern not in the project
701>
702> **NEVER proceed past a red flag without explicit user approval.**
703
704<!-- /SYNC:red-flag-stop-conditions -->
705
706<!-- SYNC:fix-layer-accountability -->
707
708> **Fix-Layer Accountability** — NEVER fix at the crash site. Trace the full flow, fix at the owning layer.
709>
710> AI default behavior: see error at Place A → fix Place A. This is WRONG. The crash site is a SYMPTOM, not the cause.
711>
712> **MANDATORY before ANY fix:**
713>
714> 1. **Trace full data flow** — Map the complete path from data origin to crash site across ALL layers (storage → backend → API → frontend → UI). Identify where the bad state ENTERS, not where it CRASHES.
715> 2. **Identify the invariant owner** — Which layer's contract guarantees this value is valid? That layer is responsible. Fix at the LOWEST layer that owns the invariant — not the highest layer that consumes it.
716> 3. **One fix, maximum protection** — Ask: "If I fix here, does it protect ALL downstream consumers with ONE change?" If fix requires touching 3+ files with defensive checks, you are at the wrong layer — go lower.
717> 4. **Verify no bypass paths** — Confirm all data flows through the fix point. Check for: direct construction skipping factories, clone/spread without re-validation, raw data not wrapped in domain models, mutations outside the model layer.
718>
719> **BLOCKED until:** `- [ ]` Full data flow traced (origin → crash) `- [ ]` Invariant owner identified with `file:line` evidence `- [ ]` All access sites audited (grep count) `- [ ]` Fix layer justified (lowest layer that protects most consumers)
720>
721> **Anti-patterns (REJECT these):**
722>
723> - "Fix it where it crashes" — Crash site ≠ cause site. Trace upstream.
724> - "Add defensive checks at every consumer" — Scattered defense = wrong layer. One authoritative fix > many scattered guards.
725> - "Both fix is safer" — Pick ONE authoritative layer. Redundant checks across layers send mixed signals about who owns the invariant.
726
727<!-- /SYNC:fix-layer-accountability -->
728
729<!-- SYNC:critical-thinking-mindset:reminder -->
730
731**MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.
732
733<!-- /SYNC:critical-thinking-mindset:reminder -->
734
735<!-- SYNC:sequential-thinking-protocol:reminder -->
736
737**MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `$sequential-thinking` skill.
738
739<!-- /SYNC:sequential-thinking-protocol:reminder -->
740
741<!-- SYNC:ai-mistake-prevention:reminder -->
742
743**MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.
744
745<!-- /SYNC:ai-mistake-prevention:reminder -->
746
747<!-- SYNC:task-tracking-external-report:reminder -->
748
749- **MANDATORY** Bootstrap task tracking before target work; transition one task at a time.
750- **MANDATORY** Persist plan/review findings to `plans/reports/` incrementally and synthesize from disk.
751
752<!-- /SYNC:task-tracking-external-report:reminder -->
753
754<!-- SYNC:project-reference-docs-guide:reminder -->
755
756- **MANDATORY** Before investigating, planning, or coding, read `docs/project-config.json` (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite `Reference docs read: ...`.
757- **MANDATORY** Always include `lessons.md`; project config + conventions override generic framework defaults.
758- **MANDATORY** If project config, root instruction files, or any required reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work.
759
760<!-- /SYNC:project-reference-docs-guide:reminder -->
761
762<!-- SYNC:end-to-start-debugger-trace:reminder -->
763
764**IMPORTANT MUST ATTENTION** debugger trace gate: for non-trivial bug/fix/investigation/review work, start at the observed final output and trace backward through reader -> storage/projection -> writer -> consumer/job -> producer/trigger. Enumerate all feeder paths and hypotheses before fixing. **BLOCKED until** trace, hypothesis matrix, owning fix layer, and forward convergence proof exist.
765
766<!-- /SYNC:end-to-start-debugger-trace:reminder -->
767
768<!-- SYNC:nested-task-creation:reminder -->
769
770- **MANDATORY** Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.
771- **MANDATORY** Orchestrators pre-expand child skill phases before invocation; use `[N.M] $skill-name — phase` prefixes and one-`in_progress` discipline.
772
773<!-- /SYNC:nested-task-creation:reminder -->
774
775<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->
776
777## Prompt-Enhance Closing Anchors
778
779**IMPORTANT MUST ATTENTION** follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
780**IMPORTANT MUST ATTENTION** for every step/sub-skill call: set `in_progress` before execution, set `completed` after execution
781**IMPORTANT MUST ATTENTION** every skipped step MUST include explicit reason; every completed step MUST include concise evidence
782**IMPORTANT MUST ATTENTION** if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses
783
784<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->
785
786<!-- SYNC:parallel-subagent-dispatch -->
787
788> **Parallel Sub-Agent Dispatch** — Plan parallelism the moment a task breakdown exists, BEFORE executing it — running provably independent tasks sequentially wastes wall-clock. Applies to every multi-step job: workflow steps, planning, batch updates, investigation, research, scans, reviews, doc sync. **Plan execution is metadata-gated, NEVER default-parallel** — fan-out follows ONLY what the plan declares (`PAR`/`SEQ` tags + per-phase write set); an untagged plan runs sequentially — why: a derived write set cannot see cascade or generated writes.
789>
790> 1. **Tag every task `PAR` or `SEQ`.** `PAR` = inputs exclude every pending task's output AND write set disjoint from every other `PAR`. Else `SEQ` — MUST ATTENTION name the dependency forcing it.
791> 2. **Group `PAR` into waves.** No edge between members. Two writers of one file NEVER share a wave. Read-only work (search, investigation, review, research) parallelizes freely.
792> 3. **Declare before dispatch:** `Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)`.
793> 4. **Spawn each wave in ONE message** — every `spawn_agent` call in one response, NEVER dripped per turn. Route each task to its specialist (`.claude/skills/shared/sub-agent-selection-guide.md`); NEVER `code-reviewer` as catch-all.
794> 5. **Brief each sub-agent self-contained:** goal · scope + owned files · reference docs · return contract (summary + `Full report:` path, per SYNC:subagent-return-contract) · incremental persistence to `plans/reports/` (per SYNC:incremental-persistence).
795> 6. **Barrier per wave.** Advance ONLY after EVERY member returns (a skipped conditional counts as returned). Merge, mark each task completed/skipped, THEN dispatch the next wave. Mutating steps wait for the barrier.
796> 7. **One level deep.** A dispatched sub-agent executes its own brief; further fan-out stays the orchestrator's job unless that agent's `.claude/agents/*.md` definition authorizes it.
797>
798> **NEVER parallelize:** tasks sharing a write target · a task consuming a pending task's output · trivial single-file work (dispatch overhead > gain) · an order a skill or workflow explicitly fixes · gates awaiting user approval.
799>
800> **Blocked until:** MUST ATTENTION every task tagged PAR/SEQ with a named reason per SEQ · waves declared + write-set disjointness checked · each wave spawned in ONE message · barrier honored before the next wave.
801
802<!-- /SYNC:parallel-subagent-dispatch -->
803
804<!-- SYNC:parallel-subagent-dispatch:reminder -->
805
806- **MANDATORY** After planning tasks, tag each PAR/SEQ and spawn every PAR wave as parallel sub-agents in ONE message — default parallel for workflows, batch updates, investigation, research, reviews; plan execution fans out ONLY on what the plan declares.
807- **MANDATORY** Disjoint write sets per wave · all-return barrier before the next wave · specialist routing · sub-agents NEVER fan out further unless their own agent definition authorizes it.
808
809<!-- /SYNC:parallel-subagent-dispatch:reminder -->
810
811<!-- SYNC:project-protocol-overlay -->
812
813> **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `<protocols-dir>/<Name>.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`.
814>
815> Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.
816
817<!-- /SYNC:project-protocol-overlay -->
818
819<!-- SYNC:project-protocol-overlay:reminder -->
820
821**MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `<protocols-dir>/<Name>.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.
822
823<!-- /SYNC:project-protocol-overlay:reminder -->
824
825## Closing Reminders
826
827**IMPORTANT MUST ATTENTION Goal:** Deliver a `$why-review`-validated root cause pinned to `file:line` at the invariant-owning layer — investigation-ONLY, so `$fix` corrects the cause, not the symptom — or an honest "hypothesis, not confirmed" naming the evidence gaps.
828
829**Protocols in force (concise digest of the SYNC/shared blocks this skill carries):**
830
831- **End-to-Start Debugger Trace:** MUST ATTENTION trace backward from final state.
832- **Root Cause Debugging:** reproduce, isolate, trace — NEVER guess-and-check.
833- **Incremental Persistence:** append findings to report per file.
834- **Sub-Agent Return Contract:** return summary only, full report on disk.
835- **Source/Test Drift Check:** changed behavior — reconcile affected tests from evidence.
836- **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
837- **Nested Task Creation:** expand child phases, link parent when nested.
838- **Project Reference Docs:** ALWAYS read required project docs, cite them.
839- **Task Tracking & External Report:** bootstrap tasks, persist findings incrementally.
840- **Critical Thinking:** traced proof per claim, confidence >80%.
841- **Sequential Thinking:** multi-step Thought N/M with confidence closer.
842- **Understand Code First:** read code, grep 3+ patterns before concluding.
843- **Evidence:** cite `file:line`, declare confidence — NEVER speculate.
844- **Cross-Service Check:** scan producers/consumers/sagas/contracts for silent regressions.
845- **Estimation Framework:** bottom-up hours, derived SP, min-max range.
846- **Red Flag Stop Conditions:** escalate on confidence/blast/boundary/security flags.
847- **Fix-Layer Accountability:** fix lowest invariant-owning layer — NEVER crash site.
848- **Parallel Sub-Agent Dispatch:** Tag tasks PAR/SEQ, group PAR into disjoint-write-set waves, spawn each wave in ONE message, barrier before advancing.
849
850**IMPORTANT MUST ATTENTION** investigation-ONLY — NEVER patch here; hand confirmed cause to `$fix` — why: a fix from un-validated findings patches the symptom and masks the real defect.
851**IMPORTANT MUST ATTENTION** Phase 0 FIRST (BLOCKING) — classify bug type, route to the specialized agent (`debugger` / `performance-optimizer` / `security-auditor`) before any investigation — why: classification decides which evidence matters and which agent has the right checklist.
852**IMPORTANT MUST ATTENTION** NEVER fix at the crash site — trace full data flow origin → crash, fix at the lowest invariant-owning layer that protects ALL downstream consumers — why: the crash site is a symptom; scattered guards at consumers signal nobody owns the invariant.
853**MUST ATTENTION** trace END-to-START — name Frame 0 (observed final state), walk reader → storage/projection → writer → consumer/job → producer, enumerate ALL feeder paths, build the hypothesis matrix BEFORE proposing any fix — why: the bug enters where bad state is WRITTEN, not where it crashes.
854**MUST ATTENTION** every root-cause claim carries `Confidence: X%` + `file:line` proof; <60% → report "hypothesis, not confirmed" with named evidence gaps, NEVER a guess — why: self-confirmed findings rationalize their own gaps.
855**MUST ATTENTION** NEVER declare a confirmed root cause without passing the `$why-review` gate (SAME session, SAME main agent, NO sub-agent); 2 rounds without passing → STOP, escalate by asking the user directly.
856**MUST ATTENTION** search 3+ existing patterns and READ the actual code before concluding — cite `file:line`; inference alone is insufficient — why: trial-and-error and assumed APIs hallucinate causes.
857**MUST ATTENTION** failing/flaky integration test → run **Phase 0.5 Fault Adjudication BEFORE any trace**: READ the `$integration-test-review` protocol (8 assertion-quality / repeatability / domain-logic / scenario-fidelity gates) — NEVER invoke that skill, the verify loop owns the invocation — then emit ONE verdict: TEST-WRONG · TEST-NOT-OPTIMAL · SOURCE-WRONG · ENVIRONMENT · AMBIGUOUS (→ STOP and ask) — why: without that verdict the trace targets the wrong side and can rationalize a broken invariant as green.
858**MUST ATTENTION** run a graph trace when `graph.db` exists — `callers_of` / `importers_of` / `tests_for` / `trace` reveal MESSAGE_BUS consumers and event handlers grep cannot see — why: cross-service chains are invisible to text search.
859**MUST ATTENTION** prove convergence FORWARD after choosing the fix layer — walk start → end, map each root cause to a fix part and each fix part to a test/proof; `$prove-fix` MUST run after `$fix` applies changes.
860**MUST ATTENTION** OOM/memory → check row COUNT before row SIZE (unbounded query > large row); 3+ failed fixes → STOP, question the architecture, escalate to user.
861**MUST ATTENTION** bootstrap task tracking task tracking BEFORE first file read; persist findings incrementally to `plans/reports/`; standalone (outside workflow) → add a `$changes-review` task as the LAST task — why: context cutoff loses in-memory findings.
862
863**Anti-Rationalization:**
864
865| Evasion | Rebuttal |
866| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
867| "I see the problem, let me fix it" | Symptom ≠ root cause. This skill is investigation-ONLY — trace end-to-start first. |
868| "Too simple for Phase 0" | Root-cause assumptions waste more time than classification. Apply Phase 0 anyway. |
869| "Already traced, no graph needed" | Show `file:line` evidence. No proof = no trace. Run graph trace if `graph.db` exists. |
870| "Skip `$why-review`, findings look solid" | Self-confirmed findings rationalize their own gaps. The `$why-review` gate is non-negotiable. |
871| "This is a frontend bug, no graph" | Frontend → backend → bus chains exist. Run trace first. |
872| "It's OOM, must be a large object" | Check row COUNT before row SIZE. Unbounded query > large single row. |
873| "Just try changing X and see" | One hypothesis at a time. Scientific method, not trial and error. |
874
875**IMPORTANT MUST ATTENTION** investigation-ONLY: trace end-to-start to the invariant-owning layer, NEVER patch here.
876**IMPORTANT MUST ATTENTION** every root-cause claim needs `Confidence: X%` + `file:line` proof; <60% = "hypothesis, not confirmed", NEVER a guess.
877**IMPORTANT MUST ATTENTION** NEVER declare confirmed without the `$why-review` gate; task tracking before starting.
878
879**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking.
880
881<!-- CODEX:SYNC-PROMPT-PROTOCOLS:START -->
882
883## Hookless Prompt Protocol Mirror (Auto-Synced)
884
885Source: `.claude/.ck.json` + `.claude/skills/shared/sync-inline-versions.md` (`:full` blocks) + `.claude/scripts/lib/hookless-prompt-protocol.cjs`
886
887## [WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason.
888
889**Generic portability boundary:** Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from `shared/sdd-artifact-contract.md`. Read `docs/project-config.json` and `docs/project-reference/docs-index-reference.md`, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or `docs/specs/` work, route through the local spec docs named by the docs index: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`, and `workflow-spec-test-code-cycle-reference.md` when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run `$project-init` (or the narrow lower-level route such as `$project-config`, `$docs-init`, `$scan-all`, or `$scan --target=<key>`) before ordinary project-specific work. Any supported AI tool may execute when this shared context and local docs are available.
890
8911. **DETECT:** If the prompt starts with an explicit slash skill/workflow command, execute it directly. Otherwise match the prompt against the workflow catalog and skill list.
8922. **ANALYZE:** Choose the best option: execute directly, invoke a skill, activate a standard workflow, or compose a custom step combination.
8933. **AUTO-SELECT:** Pick the best option yourself. Do not ask the user to choose between direct execution, skill, standard workflow, or custom workflow.
8944. **ACTIVATE:** For a selected workflow, call `$start-workflow <workflowId>`; for a selected skill, invoke that skill; for a custom workflow, sequence custom steps directly; for direct execution, proceed with the task.
8955. **CREATE TASKS:** task tracking for ALL workflow/skill/custom steps before execution when the selected path has multiple steps.
8966. **PARALLELIZE:** Before executing the task list, tag each task `PAR` (independent inputs + write set disjoint from every other `PAR` task) or `SEQ` (name the blocking dependency), group `PAR` tasks into waves, declare the wave plan, and spawn each wave's sub-agents in ONE message — all-return barrier per wave, fan-out one level deep unless a sub-agent's own definition authorizes further fan-out. Sequential-by-default is a defect when tasks are independent; do not parallelize shared write targets, output-consuming tasks, trivial single-file work, ordering a skill or workflow explicitly fixes, or user-approval gates.
8977. **EXECUTE:** Advance per the **Workflow Step Advancement & Parallel Phases** rule in your context instructions — model-driven; a sub-agent completion advances a step identically to an inline call; a parallel-phase group is an all-return barrier (advance only after ALL members return, never serialize it)
898
899## Shared AI-SDD Protocol Markers
900
901Source: `.claude/skills/shared/sync-inline-versions.md`
902
903## SYNC:ai-sdd-artifact-contract
904
905> **AI-SDD Artifact Contract** — Shared spec-driven development rules stay portable and source-owned.
906>
907> 1. Keep reusable AI-SDD principles in `.claude`; put repository-specific paths, commands, owners, products, and formats in project config/reference docs.
908> 2. Preserve cycle: `spec -> plan -> tasks -> implement -> verify -> update spec/docs`.
909> 3. Trace every requirement or invariant through decision, task, TC/test, source evidence, and docs/spec update.
910> 4. Treat code-to-spec extraction as reference-only until accepted by the canonical spec owner.
911> 5. Any supported AI tool may plan, implement, review, or verify with synced context; using multiple tools is optional.
912> 6. Update `.claude` source first, then sync generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. — why: mirrors are generated artifacts; hand-edits are overwritten on the next sync
913> 7. If `docs/project-config.json`, root instruction files, or a required project-reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work.
914>
915> **Active reference:** `shared/sdd-artifact-contract.md` in the active skills root.
916
917---
918
919## SYNC:ai-sdd-artifact-contract:reminder
920
921- **MANDATORY** Apply `shared/sdd-artifact-contract.md`; keep reusable AI-SDD in `.claude` and local rules in project docs.
922- **MANDATORY** Code-to-spec extraction is reference-only until canonical acceptance; any supported AI tool may execute with synced context.
923- **MANDATORY** Update `.claude` source before syncing generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`.
924- **MANDATORY** Missing or stale project config, root instruction files, or required reference docs route project-specific work through `$project-init` or the narrow setup route automatically.
925 **[TASK-PLANNING] [MANDATORY]** BEFORE executing any workflow or skill step, create/update task tracking for all planned steps, then keep it synchronized as each step starts/completes.
926
927## [LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip.
928
929Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned".
930
931**Extract lessons — ROOT CAUSE ONLY, not symptom fixes:**
932
9331. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value".
9342. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up.
9353. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase.
9364. Consolidate: multiple mistakes sharing one failure mode → ONE lesson.
9375. **Recurrence gate:** "Would this recur in future session WITHOUT this reminder?" — No → skip `$learn`.
9386. **Auto-fix gate:** "Could `$code-review`/`$code-simplifier`/`$security-review`/`$lint` catch this?" — Yes → improve review skill instead.
9397. BOTH gates pass → ask user to run `$learn`.
940 **[CRITICAL-THINKING-MINDSET]** Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
941 **Anti-hallucination principle:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
942 **AI Attention principle (Primacy-Recency):** Put the 3 most critical rules at both top and bottom of long prompts/protocols so instruction adherence survives long context windows.
943 **Goal-driven execution:** Define success criteria first, loop until verified, and stop only when observable checks pass.
944 **Tests verify intent:** Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior.
945
946## Common AI Mistake Prevention (System Lessons)
947
948- **Re-read files after context compaction.** Edit requires prior Read in same context; compaction wipes read state. Re-read before editing.
949- **Grep for old terms after bulk replacements.** AI over-trusts find/replace completeness. Grep full repo after bulk edits for missed refs in docs/configs/catalogs.
950- **Check downstream references before deleting.** Deletions cascade doc/code staleness. Map referencing files before removal.
951- **After memory loss, check existing state before creating new.** Compaction wipes prior-work memory. Query current state to resume — never blindly duplicate.
952- **Verify AI-generated content against actual code.** AI hallucinates APIs, class names, method signatures. Grep to confirm existence before documenting/referencing.
953- **Trace full dependency chain after edits.** Changing a definition misses downstream consumers. Trace the full chain.
954- **When renaming, grep ALL consumer file types.** Some file types silently ignore missing refs (no compile error). Search code, templates, configs, generated files.
955- **Trace ALL code paths when verifying correctness.** Code existing ≠ code executing. Trace early exits, error branches, conditional skips — not just happy path.
956- **Update docs that embed canonical data when source changes.** Docs inlining derived data (workflows, schemas, configs) go stale silently. Update all embedding docs alongside source.
957- **Verify sub-agent results after context recovery.** Background agents may finish while parent compacted — grep-verify output, don't trust assumed completion.
958- **Cross-check full target list against sub-agent assignments.** Parallel sub-agents by category miss boundary items. Reconcile union of assignments against target list before proceeding.
959- **Sub-agents inherit knowledge only from their agent .md definition — use custom agent types, not built-in Explore.** Tool adoption = permission + knowledge + enforcement (numbered workflow step).
960- **Persist sub-agent findings incrementally, not as a final batch.** Long sub-agents hit cutoffs before final write — findings lost. Instruct append-per-section to report file.
961- **When debugging, ask "whose responsibility?" before fixing.** Trace caller (wrong data) vs callee (wrong handling). Fix at responsible layer — never patch symptom site.
962- **Test failure → record a provisional verdict before trace/edit, then investigate.** Use the full five-way taxonomy: SOURCE-WRONG (production violates intent), TEST-WRONG (assertion/setup is stale), TEST-NOT-OPTIMAL (valid but fragile or low-signal test), ENVIRONMENT-BLOCKED (external state prevents a verdict), or AMBIGUOUS (intent/evidence cannot choose safely). Then trace root cause and triangulate against the governing spec (`docs/specs/**` if one exists) AND source. NEVER weaken an assertion, add a skip, relax a timeout, or change source merely to force green.
963- **Grep ALL removed names after extraction/refactoring.** Primary file "done" ≠ secondary files clean. Grep entire scope for every removed symbol before declaring complete.
964- **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Pattern-matching as "wrong" skips context. Before changing or reporting any constant/limit/flag/cutoff: read comments, git blame, the CALLER's ordering (the guarantee that makes the value correct usually lives in code running immediately BEFORE the cited line), and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard — and in a validation pass, an accurate `file:line` citation proves the transcription, never the defect.
965- **Verify ALL affected outputs, not just the first.** One build green ≠ all green. Multi-stack changes (backend/frontend/tests/docs) require verifying EVERY output.
966- **Evaluate fit before copying a nearby pattern.** Closest example ≠ matching preconditions — verify the new context shares the same constraints, base classes, scope, lifetime.
967- **Holistic-first debugging — resist nearest-attention trap.** Don't dive into first plausible cause. List EVERY precondition (config, env vars, paths, DB, endpoints, creds, versions, DI, data). Verify each against evidence (grep/query — not reasoning). Ask "what would falsify this?" — if nothing, it's not a hypothesis. Most expensive failure: going deeper in "obvious" layer while bug sits in layer never questioned.
968- **Surgical changes — apply the diff test (context-aware).** Two modes: (1) Bug fix → every line traces to the bug; no restyling; orphan cleanup only for imports YOUR changes made unused. (2) Review/enhancement → implement improvements AND announce as "Enhancement beyond main request: [what]". Never silently scope-creep. Diff test: "Would this line exist if I wasn't asked to do X?" — if no, delete or announce.
969- **Surface ambiguity before coding — don't pick silently.** Multiple valid interpretations → present each with effort: "[Request] could mean (1) [N h], (2) [N h]. Which matters?" List scope/format/volume/constraints assumptions first. If simpler path exists, say so. Never silently pick.
970- **[MANDATORY FIRST ACTION] ALWAYS activate a suitable skill or workflow BEFORE responding.** Match task against workflow catalog + skill list; invoke via skill invocation or `$start-workflow <workflowId>`. NEVER answer or write code before checking. Skip = protocol violation.
971- **Why-Review adversarial mindset — apply when reviewing any plan, decision, or design.** Default SKEPTIC not VALIDATOR: steel-man a rejected alternative, invert each stated reason ("what does it sacrifice?"), stress-test top 2-3 assumptions, run pre-mortem ("ships, fails in 3 months — what breaks?"), surface 1-2 alternatives author missed. Section presence ≠ quality; quality = causal reasoning + concrete mitigations + evidence, not "it's better" or "monitor closely".
972- **Front-load report-write in sub-agent prompts for large reviews.** Many-file sub-agents hit budget before final write — findings lost. Design prompts so: (1) report-write is first explicit deliverable, (2) append per-file/section (not batched), (3) scope bounded so reads don't exhaust budget. Truncated mid-sentence with no report file → spawn narrower scope, don't retry same prompt.
973- **After context compaction, re-verify all prior phase outcomes before continuing.** Summaries describe intent, not environment state (git index, filesystem, processes). On resume, FIRST audit: git status, re-read modified files, verify filesystem. Every "completed" claim is an untested hypothesis until evidence confirms.
974- **OOM/memory: check row count before row size.** Triage: (1) Unbounded query — no DB filter for trigger? Push filter to DB; eliminates OOM. (2) Large rows? Projection reduces proportionally. Row reduction > projection in ROI.
975- **Assert the outcome your system OWNS, never the intermediate state your INFRASTRUCTURE owns.** When testing anything asynchronous (queue/broker delivery, retries, background jobs, caches, replication), assert the final business/entity state. NEVER assert the delivery bookkeeping — consume/send status, attempt counts, last-error, row existence or counts in a broker, scheduler, or outbox/inbox table. That bookkeeping lives in shared infrastructure that ANY co-running process (a peer worker, a second replica, a leftover local container) can write, usually under a deterministic shared key, so the assertion silently tests the developer's environment instead of the system: green when run alone, flaky the instant anything else shares that broker + database. Gate question for every assertion: "would this hold no matter WHICH process did the work?" — if no, assert the converged data state instead. Corollary: process-local fault injection and in-process telemetry cannot gate work any process may perform — use them as stress amplifiers (arm → bounded window → disarm → assert convergence), never as preconditions.
976- **Keep domain concepts out of generic/shared/infrastructure layers.** Reusable layer (shared library, framework, infra module) must reference NO consumer-specific domain concept — tenant/customer/product IDs, business entities, feature rules. Leak compiles + runs → passes review silently while coupling the "reusable" layer to one consumer. Keep shared type domain-free; push domain fields/logic down into the consumer via subclass/composition. — why: a layer coupled to one consumer's domain is no longer reusable.
977
978<!-- CODEX:SYNC-PROMPT-PROTOCOLS:END -->