Investigate

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• 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.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

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.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

Quick Summary

Goal: Produce an evidence-backed understanding of how existing code works through READ-ONLY exploration with zero changes — every claim traced to file:line or explicitly marked "inferred" — so the next decision or change rests on verified system flow, never assumption.

Summary:

• Purpose: read-only, evidence-backed map of how existing code works — the next decision/fix rests on verified flow, never assumption.
• Main steps (run in order): Phase 0 Classify (quick / deep / debug / recommendation) → Discovery (Entities > Commands > Events > Controllers) → Graph Expand (2-3 key files, main agent only) → Knowledge Graph (per-file doc) → Flow Mapping (entry → exit + side effects) → Analysis (business rules / validation / authz / error paths) → Synthesis (deep scope → analysis file) → Present (structured findings + deeper-dive offer).
• Classify scope FIRST (Phase 0: quick / deep / debug / recommendation) — depth and deliverables (analysis file, validation chain) flow from this, so never skip straight to grepping.
• Graph is MANDATORY, not optional: the main agent MUST run at least one code_graph command on 2-3 key files before concluding — graph surfaces callers, bus consumers, and importers that grep alone misses (sub-agents cannot use graph).
• Stay strictly READ-ONLY and cite file:line for every claim; unverified statements MUST be marked "inferred", and recommending any code change forces the full validation chain (all impls/registrations/usages/cross-service impact + confidence declaration).
• --mode=explain only changes the deliverable (one-way developer narrative → git-ignored tmp/understand/{branch}.md ledger) — the same evidence gate, graph rule, and READ-ONLY constraint still bind; deep scope writes to .ai/workspace/analysis/[feature]-investigation.md and must be re-read in full before presenting.

Workflow:

1. Phase 0: Classify — Determine scope (quick / deep / debug / recommendation) before acting
2. Discovery — Search codebase for related files (Entities > Commands > Events > Controllers)
3. Graph Expand — Run graph queries on 2-3 key files (MANDATORY, main agent only)
4. Knowledge Graph — Read + document purpose, symbols, dependencies per file
5. Flow Mapping — Trace entry points through pipeline to exit points
6. Analysis — Extract business rules, validation, authorization, error handling
7. Synthesis — Write executive summary to .ai/workspace/analysis/[feature]-investigation.md
8. Present — Deliver structured findings, offer deeper dives

Modes:

• Default (analysis) — investigate for an engineer audience: structured findings + analysis file. Everything below applies.
• --mode=explain (developer narrative) — same READ-ONLY evidence gate, but the deliverable is a one-way developer explanation (Purpose → How → Why → Impact), tuned by coding level, written to a git-ignored ledger. See Mode: Explain. Use $understand [target] when you want the standalone prompt-driven explainer instead of a full investigation run.

Key Rules:

• Strictly READ-ONLY — NEVER make code changes
• Every claim needs file:line proof — mark unverified as "inferred"
• MUST ATTENTION run at least ONE graph command on key files before concluding
• MUST ATTENTION Plan ToDo Task to READ project-structure-reference.md (if not found, search: project documentation, coding standards, architecture docs)

Phase 0: Scope Classification

Classify before acting — route to correct depth:

Quick scope: Skip knowledge graph template + analysis file. Grep → graph trace → present findings. Deep scope: MUST ATTENTION write to .ai/workspace/analysis/[feature]-investigation.md. Explain scope: same READ-ONLY evidence gate; deliverable is an in-chat developer narrative + a git-ignored ledger (NOT the analysis file).

Investigation Mindset (NON-NEGOTIABLE)

Skeptical. Every claim needs file:line traced proof. Confidence >80% to act.

• NEVER assume code works as named — verify by reading actual implementations
• MUST ATTENTION include file:line for every finding; unproven claims MUST ATTENTION be marked "inferred"
• ALWAYS grep related usages, consumers, cross-service references — NEVER assume completeness
• ALWAYS trace actual call paths with evidence — NEVER rely on signatures alone

Logical-ID Extraction & Business-Intent Rule (M3/M5)

See .claude/skills/shared/sdd-artifact-contract.md → "AI-SDD Mandates (M1-M7)" for BLOCKING criteria. When extracting operations, business rules, or events into findings:

• Assign each extracted operation/rule/event a logical ID (FR-/BR- for operations and rules) as the PRIMARY identifier. Keep the [Source: namespace/service/id] abstract-anchor evidence (never physical code coordinates or repository-root paths — those live only in the provenance sidecar) as a SEPARATE carrier — never fold the source link into the rule statement itself (M3).
• For every rule, explain WHY it exists (the business intent / invariant it protects), not only WHAT the code does. State the rule in tech-agnostic business terms so the finding is reusable by a rebuild team on any stack (M5).

Workflow

1. Discovery — Search for all related files. Priority: Entities > Commands/Queries > EventHandlers > Controllers > Consumers > Components.

2. Graph Expand (MANDATORY — DO NOT SKIP) — YOU (main agent) MUST ATTENTION run graph queries YOURSELF on key files from Step 1. Sub-agents CANNOT use graph — only you can. Pick 2-3 key files (entities, commands, bus messages):

   python .claude/scripts/code_graph connections <key_file> --json
   python .claude/scripts/code_graph query callers_of <FunctionName> --json
   python .claude/scripts/code_graph query importers_of <file_path> --json
   # "ambiguous" → search to disambiguate, retry with qualified name
   python .claude/scripts/code_graph search <keyword> --kind Function --json
   # Trace how two nodes connect
   python .claude/scripts/code_graph find-path <source> <target> --json
   # Filter by service, limit results
   python .claude/scripts/code_graph query callers_of <name> --limit 5 --filter "ServiceName" --json
   

   Graph reveals complete dependency network (callers, importers, tests, inheritance) grep alone misses. Also run $graph-connect-api for frontend-to-backend API mapping.

3. Knowledge Graph — Read + analyze each file (from grep + graph results). Document purpose, symbols, dependencies, data flow. Batch in groups of 10; update progress after each batch. Per-file template:

4. Flow Mapping — Trace entry points through processing pipeline to exit points. Map data transformations, persistence, side effects, cross-service boundaries.

5. Analysis — Extract business rules, validation, authorization, error handling. Document happy path AND edge cases.

6. Synthesis — Executive summary answering original question. Key files, patterns used, text-based flow diagrams.

7. Present — Structured output (see Output Format). Offer deeper dives on subtopics.

If preceded by $scout: Use Scout's numbered file list as analysis targets. Skip redundant discovery. Prioritize HIGH PRIORITY files.

Parallel Investigation Threads (Discovery → ONE wave → Graph Expand)

Investigation is strictly READ-ONLY, so no two threads can ever share a write target — this is the single most parallelizable activity in the framework, and reading thread-by-thread is the default defect, not a safe choice. Once Step 1 names the surface, decompose the target into independent threads BEFORE reading anything deeply:

Dispatch rules specific to this skill:

1. Declare, then spawn in ONE message — Parallel plan: wave 1 = [thread A, thread B, …] · SEQ = [Graph Expand, Flow Mapping, Analysis, Synthesis] (each consumes the whole wave).
2. Route per thread — file/symbol landscape threads → scout (scout-external under --ext); root-cause / hypothesis threads → debugger. Never a generic reviewer for either.
3. Own scope + own report path per thread — each brief names its exact files/questions AND its own write target (.ai/workspace/analysis/[feature]-{thread}.md, or plans/reports/…); two threads NEVER write the same file, and each persists incrementally rather than returning a transcript.
4. Graph Expand stays SEQ on YOU — run Step 2's code_graph commands yourself AFTER the barrier, on 2-3 key files the wave surfaced. It is the step that reconciles independent threads into one dependency network, and it is why the barrier cannot be skipped.
5. Synthesize from the returned reports, not from memory — re-read each thread's analysis file, then write Steps 4-6 (Flow Mapping → Analysis → Synthesis) yourself.

The SEQ boundary — name it explicitly: a thread whose STARTING POINT is another thread's finding is SEQ, not PAR. "Trace the consumers of the published event" cannot start until "which event is published" returns — put it in wave 2 and name the finding it waits on. Threads that merely share a topic (same feature, different layer) are still PAR.

Investigation Techniques

Discovery Search Patterns

Grep {FeatureName} combined with: EventHandler, BackgroundJob, Consumer, Service, Component.

Priority order (stack-neutral strategy): (1) Domain model (entities/aggregates) → (2) Use-cases (commands/queries) → (3) Event handlers (side-effect logic) → (4) Entry points (controllers/API/route handlers) → (5) Cross-service consumers (message/event subscribers) → (6) Background jobs/schedulers → (7) UI components/stores → (8) Services/helpers. Concrete locators (folder names, file globs, framework markers) vary by stack — discover them from the project's structure reference + project config.

Dependency Tracing

Backend (trace these relationships — locator syntax per stack): method/function callers (grep backend source files), dependency injectors (grep the interface/type in constructors or DI wiring), domain-event subscribers (the framework's domain-event handler type), cross-service message handlers (the cross-service message/event contract across services), repository/data-access usage (the repository/data-access interface).

Frontend: component users (grep the component selector in templates), service importers (grep the class in source files), store/state chains (state-effect → API call → response handler → state), routes (grep the component in routing files). Concrete file globs and framework primitives: see the project's frontend reference + config.

Data Flow Mapping

Document as: [Entry] → [Validation] → [Processing] → [Persistence] → [Side Effects]

MUST ATTENTION trace: (1) Entry points, (2) Processing pipeline, (3) Data transformations, (4) Persistence points, (5) Exit points/responses, (6) Cross-service message bus boundaries.

Common Investigation Scenarios

Project Pattern Recognition

Backend (search for backend-patterns-reference in docs/): CQRS commands/queries, entity event handlers, message bus consumers, repository extensions, validation fluent API, authorization attributes.

Frontend (search for frontend-patterns-reference in docs/): component base classes, view-model/state store base, reactive data-fetch effects with loading/error state handling, API service base class.

Graph Intelligence (MANDATORY when graph.db exists)

MUST ATTENTION orchestrate grep → graph → grep dynamically: (1) Grep key terms to find entry files, (2) Use connections/batch-query/trace --direction both to expand dependency network, (3) Grep again to verify content. trace follows ALL edge types including MESSAGE_BUS and TRIGGERS_EVENT.

python .claude/scripts/code_graph connections <file> --json     # Full picture
python .claude/scripts/code_graph query callers_of <name> --json
python .claude/scripts/code_graph query importers_of <file> --json
python .claude/scripts/code_graph query tests_for <name> --json
python .claude/scripts/code_graph batch-query <f1> <f2> --json

Evidence Collection

Deep scope — MANDATORY: Write analysis to .ai/workspace/analysis/[feature-name]-investigation.md. MUST ATTENTION re-read ENTIRE file before presenting findings.

Structure: Metadata (original question) → Progress → File List → Knowledge Graph (per-file entries per SYNC:knowledge-graph-template) → End-to-Start Debugger Trace (when bug/fix/behavior-changing) → Data Flow → Findings.

Rule: Every 10 files → MUST ATTENTION update progress, re-check alignment with original question.

Analysis Phases

Comprehensive: (1) Happy path, (2) Error paths, (3) Edge cases, (4) Authorization checks, (5) Validation per layer. Extract: core business rules, state transitions, side effects.

Synthesis: Executive summary (1-para answer, top 5-10 key files, patterns used) + step-by-step walkthrough with file:line references + flow diagrams.

Output Format

MUST ATTENTION include: (1) Direct answer (1-2 paragraphs), (2) Step-by-step "How It Works" with file:line refs, (3) Key Files table, (4) Data Flow diagram, (5) "Want to Know More?" subtopics.

For bug, failed-verification, or behavior-changing investigations, MUST ATTENTION also include:

### Debugger Trace: End -> Start

- Observed final state:
- Final reader/query/renderer/assertion:
- Backward hops: reader -> storage/projection/cache -> writer -> consumer/handler/job -> producer/origin
- Feeder paths scanned:
- Unknown or unverified paths:

### Hypothesis Matrix

| RC  | Hypothesis | Evidence for | Evidence against | Status | Verification |
| --- | ---------- | ------------ | ---------------- | ------ | ------------ |

Guidelines

• Evidence-based — every claim needs code evidence; MUST ATTENTION mark unverified as "inferred"
• Question-focused — ALWAYS tie findings back to original question
• Read-only — NEVER suggest changes unless explicitly asked
• Layered — Start simple, offer deeper detail on request

Related Skills

scout (pre-discovery) | workflow-feature (implementation) | debug-investigate (debugging) | graph-query (natural language queries)

Mode: Explain (Developer Narrative)

Trigger: $investigate --mode=explain [target]. Manual-only — never auto-inserted into workflows. Use $understand [target] for the standalone prompt-driven explainer.

What changes vs default investigate: ONLY the deliverable's audience, shape, and write target. The evidence gate is identical and NON-NEGOTIABLE — strictly READ-ONLY on code & plans, every concrete claim cites file:line, at least ONE graph command runs on key files before concluding, confidence >80% to assert. Explain mode NEVER relaxes any of these. If a narrative point lacks file:line proof, mark it "inferred" exactly as in default mode.

Goal: make the developer understand the work via a clear, detailed, one-way explanation of WHAT it is, its PURPOSE (why it exists), HOW it works (mechanics), and WHY this way (trade-offs + rejected alternatives). AI derives WHAT to explain from the prompt. No fixed agenda; scope flexes to whatever is named.

Contract (read first)

• DERIVE SCOPE FROM THE PROMPT. No target named → default to the current working context: active tasks (the current task list) + working-tree changes (git diff --name-only + untracked via git ls-files --others --exclude-standard) + active plan / latest $watzup summary if present.
• NEVER ASK THE USER A QUESTION. Strictly one-way: no teach-back, no quiz, no ask the user directly, no ambiguity question, no comprehension gate. Infer the most likely target, state the assumption in one line, proceed. (The pre-skill workflow-detection gate is a separate concern, already exempt when the developer explicitly invokes the skill.)
• OPT-IN, NEVER BLOCKS. Explain and end. Never traps the developer in a loop; never gates commit/implementation/workflow progress.
• ALWAYS EXPLAIN IN FULL — REGARDLESS OF CODING LEVEL. Always cover purpose + how + why. Coding level only tunes vocabulary/analogy density (ELI5 ↔ terse-for-experts) — it NEVER decides whether to explain and NEVER trims the three sections.
• EXPLAIN THE WHOLE SCOPE, LEAD WITH THE NON-OBVIOUS. Cover everything in scope, but order by leverage — open with highest-blast-radius / highest-future-change-cost / most-surprising parts; treat boilerplate/CRUD briefly. Nothing silently omitted.
• WRITES ONLY to a project-root temp folder. Never edits source or plan files; never writes the .ai/workspace/analysis/... analysis file. Its only write target is the ledger at tmp/understand/{branch}.md (see Step E3).

Step E0 — Resolve scope & read the style dial

1. Derive scope from the prompt:

   Prompt signal	Scope to explain
   Bare invocation, no target named	Default: current working context — active tasks + working-tree changes + active plan / latest $watzup.
   Names a change set / PR / "what I just did"	The diff and its rationale.
   Names a plan / "the approach" / "before we build"	The active plan: problem, approach, rejected alternatives, risks, phase order.
   Names a subsystem / file / feature / "how does X work"	That code path — read files, run a graph trace, explain the flow.
   Names a single decision / "why X over Y"	That decision and its trade-offs.
   Names a concept / bug / error	That concept or root cause.
   Ambiguous / multiple plausible targets	Do NOT ask. Infer most likely (default current context), state the assumption in one line, proceed.

   State the resolved scope in one line before continuing (e.g. Explaining: current working changes (3 files) + active task #42).

2. Read the style dial (NOT a skip gate). Resolve coding level (first found wins): env CK_CODING_LEVEL → .claude/.ck.json codingLevel → default 3. Level tunes how the explanation reads only — it NEVER drops purpose/how/why. 5/-1 God Mode (terse, lead with the non-obvious trade-off) · 4 Tech Lead (concise, design trade-offs) · 3 Senior (balanced) · 2 Mid (fuller mechanics) · 1 Junior (WHY before HOW, step-by-step) · 0 ELI5 (one concept at a time, analogies). Note the level in one line, then explain. Do not offer a skip; do not ask anything.

Step E1 — Gather the material (proportional to scope)

• Current working context: the current task list; git diff --name-only (+ untracked); active plan + latest $watzup. Extract: what's being worked on, what changed, why, new behavior.
• A plan: read plan.md + phase-*.md. Extract: problem, chosen approach, rejected alternatives, design decisions, risks, phase order.
• A subsystem / "how does X work": read the files; run python .claude/scripts/code_graph trace <file> --direction both --json. Extract: entry points, data flow, key invariants.
• A single decision: the relevant code + rationale (comments, git blame, the plan's alternatives section).

Don't read the whole repo to explain one decision.

Step E2 — Order topics by leverage

Cover the whole scope; use this only to ORDER. Blast radius (run $graph-blast-radius or graph trace on key files — high reach → explain first, deepest) · Future-change-cost (schema, public contract, cross-service message, shared/framework layer → high priority) · Surprise (anything a competent engineer would NOT guess — call out explicitly). Boilerplate/generated/mechanical renames get a one-line mention.

Step E3 — Maintain the understanding ledger

[HARD RULE] Write the ledger ONLY to a project-root temp folder — NEVER inside .claude/, the source tree, or any tracked path.

Path: tmp/understand/{branch}.md (use temp/understand/{branch}.md if the project already uses temp/). Create the understand/ subdir if absent. {branch} = current git branch with / → -. Ensure the temp folder is git-ignored.

[ANNOUNCE — the chat is the deliverable] The understanding lives in the in-chat explanation, not the file. Whenever you write/append the ledger, state its path inline (Understanding ledger updated → tmp/understand/{branch}.md). NEVER let the explanation exist only inside the temp file.

Append (never overwrite) a checklist with three groups: Problem (why it exists, prior limitation, the branches) · Solution (design, business logic, edge cases, why this over alternatives) · Impact (what/who changes, blast radius, follow-ups).

Step E4 — Explain: Purpose → How → Why (the deliverable)

Deliver in-chat, in this order, for every level (depth/vocabulary tuned per E0; all sections always present). Cite file:line for every concrete claim.

1. WHAT — one-line orientation: name the thing and where it lives.
2. PURPOSE (why-it-exists) — what problem it solves; the prior limitation / alternative branch that made it necessary. Lead here.
3. HOW (mechanics) — walk the flow: entry points, data flow, key invariants, what calls what (use the graph trace). Show code paths + business logic + handled edge cases.
4. WHY-this-way (trade-offs) — why this over the obvious alternative(s); what it cost, what it bought, what is now expensive to reverse. Surface non-obvious decisions explicitly ("we did X instead of Y because Z").
5. IMPACT (blast radius & follow-ups) — what/who changes, upstream/downstream reach, open follow-ups.

Proactively offer a simpler restatement/analogy for any dense point. Responding to a developer's eli5/elii follow-up is fine — what's forbidden is you posing questions to them.

Step E5 — Recap & close (no quiz, no loop)

Mark ledger items explained. Close with a 2–3 line recap (purpose in one sentence, key mechanic in one, highest-leverage trade-off / blast-radius note in one). End there. Do NOT quiz, do NOT ask the developer to restate, do NOT loop, NEVER block the next step.

NOT for: investigation/docs/design/research where nothing was built or planned to understand; forcing comprehension as a hard gate; reviewing code quality (use $code-review, $changes-review).

Anti-Rationalization: "Senior dev, skip it" → NEVER skip by level. · "I'll quiz them" → one-way only, never ask. · "Ambiguous — I'll ask which" → infer + state assumption, proceed. · "Dump everything" → derive scope first, order by leverage. · "Skip trade-offs" → WHY-this-way is mandatory. · "Drop ledger by the skill" → only tmp/understand/{branch}.md. · "Write the doc and move on silently" → the chat is the deliverable; announce the ledger path.

Investigation & Recommendation Protocol

Applies when recommending code changes (removal, refactoring, replacement). MUST ATTENTION complete full validation chain.

Validation Chain (NEVER skip steps)

NEVER recommend code changes without completing ALL steps:

1. Interface/API identified → 2. ALL implementations found → 3. ALL registrations traced → 4. ALL usage sites verified → 5. Cross-service impact (ALL services) → 6. Impact assessment → 7. Confidence declaration → ONLY THEN output recommendation.

If ANY step incomplete → STOP. State "Insufficient evidence to recommend."

Breaking Change Risk Matrix

Removal Checklist (ALL MUST ATTENTION pass)

• No static references (rg "ClassName" {configured-source-roots} returns no live references)
• No string literals / dynamic invocations (reflection, factory, message bus)
• No DI registrations (services.Add*<ClassName>)
• No config references (appsettings, env vars)
• No test dependencies
• Cross-service impact checked (ALL microservices)

Incomplete checklist → state: Confidence: <90% — did not verify [missing items]

Evidence Hierarchy

(1) Code evidence (grep/read) → (2) Test evidence → (3) Documentation → (4) Inference. Recommendations based on inference alone FORBIDDEN — MUST ATTENTION upgrade to code evidence.

Confidence Levels

95-100% full trace + all services | 80-94% main paths verified | 60-79% partially traced | <60% DO NOT RECOMMEND

Format: Confidence: 85% — Verified main usage in ServiceC, did not check ServiceA/ServiceB

Service Comparison Pattern

Find working reference → compare implementations → identify differences → verify WHY each difference exists → recommend based on proven pattern, NEVER assumptions.

[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. For simple tasks, AI MUST ATTENTION ask user whether to skip.

• docs/project-reference/domain-entities-reference.md — domain entity catalog, relationships, cross-service sync (when task involves business entities/models).

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.

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.
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.
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.
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.
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.
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.

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.

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.

> **Knowledge Graph Template** — For each analyzed file, document: filePath, type (entity, command, query, event handler, controller, consumer, component, store, service, or repository-specific equivalent), architecturalPattern, content summary, symbols, dependencies, businessContext, referenceFiles, relevanceScore (1-10), evidenceLevel (verified/inferred), abstractions, and moduleContext. Investigation fields: entryPoints, outputPoints, dataTransformations, errorScenarios. Messaging fields: messageName, messageProducers, crossBoundaryIntegration. UI fields: componentHierarchy, stateManagementStores, dataBindingPatterns, validationStrategies.

Root Cause Debugging — Systematic approach, never guess-and-check.

1. Reproduce — Confirm the issue exists with evidence (error message, stack trace, screenshot)
2. Isolate — Narrow to specific file/function/line using binary search + graph trace
3. Trace — Follow data flow from input to failure point. Read actual code, don't infer.
4. Hypothesize — Form theory with confidence %. State what evidence supports/contradicts it
5. Verify — Test hypothesis with targeted grep/read. One variable at a time.
6. Fix — Address root cause, not symptoms. Verify fix doesn't break callers via graph connections

NEVER: Guess without evidence. Fix symptoms instead of cause. Skip reproduction step.

Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.

1. Call the current task list first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.
2. Create one task per declared phase before phase work. When nested, prefix subjects [N.M] $skill-name — phase.
3. When nested, link the parent with TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
5. Mark exactly one child in_progress before work and completed immediately after evidence is written.
6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.

Blocked until: the current task list done, child phases created, parent linked when nested, first child marked in_progress.

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.

1. Identify scope: file types, domain area, and operation.
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).
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.
4. Read every required doc, then before target work state: Reference docs read: ... | Not applicable: ....

Ready when: scope evaluated, docs/project-config.json consulted, required docs checked/read or setup route completed, lessons.md confirmed, citation emitt

…(truncated)