# Investigate > [Fix & Debug] Use when you need to investigate and explain how existing features or logic work. Flag: --mode=explain produces a one-way developer-narrative explanation (Purpose → How → Why → Impact) tuned by coding level; use /understand for the standalone prompt-driven explainer. - Skill: `duc01226/investigate` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/investigate` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/investigate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML, Coding & Dev Tools - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/duc01226/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=`, `$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](#mode-explain-developer-narrative). 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: | Scope | Signals | Depth | | ------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Quick** | Single feature/function, clear entry point | grep → trace → answer (no analysis file needed) | | **Deep** | Multi-service, cross-boundary, ambiguous scope | Full workflow + knowledge graph template + analysis file | | **Debug** | Error/crash/unexpected behavior | Root-cause-debugging protocol above | | **Recommendation** | Code change suggested (removal, refactor) | Validation chain protocol below — MANDATORY | | **Explain** | `--mode=explain` flag | Investigation-local developer narrative — see [Mode: Explain](#mode-explain-developer-narrative). Use `$understand` for the standalone prompt-driven explainer. | 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): ```bash python .claude/scripts/code_graph connections --json python .claude/scripts/code_graph query callers_of --json python .claude/scripts/code_graph query importers_of --json # "ambiguous" → search to disambiguate, retry with qualified name python .claude/scripts/code_graph search --kind Function --json # Trace how two nodes connect python .claude/scripts/code_graph find-path --json # Filter by service, limit results python .claude/scripts/code_graph query callers_of --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: | Decomposition axis | One thread per… | Use when | | ------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------- | | **Per-module** | module / bounded context the target spans | the feature crosses several modules | | **Per-layer** | backend · frontend · data/persistence | a full-stack flow — each layer reads a disjoint file set | | **Per-question** | one hypothesis, or one "how does X work?" question | Phase 0 classified `debug`, or the prompt carries several independent questions | | **Per-service** | each service that produces/consumes the flow | cross-service / event-driven target (pairs with the Cross-Service Check protocol) | 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 | Question Type | Steps | | --------------------------- | --------------------------------------------------------------------------------------- | | "How does X work?" | Entry points → command/query handlers → entity changes → side effects | | "Where is logic for Y?" | Keywords in commands/queries/entities → event handlers → helpers → frontend stores | | "What happens when Z?" | Identify trigger → trace handler chain → document side effects + error handling | | "Why does A behave like B?" | Find code path → identify decision points → check config/feature flags → document rules | ### 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. ```bash python .claude/scripts/code_graph connections --json # Full picture python .claude/scripts/code_graph query callers_of --json python .claude/scripts/code_graph query importers_of --json python .claude/scripts/code_graph query tests_for --json python .claude/scripts/code_graph batch-query --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: ```markdown ### 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 --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 | Risk | Criteria | Required Evidence | | ---------- | ------------------------------------------------------------- | -------------------------------------------------------------- | | **HIGH** | Removing registrations, deleting classes, changing interfaces | Full usage trace + impact + cross-service check (all services) | | **MEDIUM** | Refactoring methods, changing signatures | Usage trace + test verification + cross-service check | | **LOW** | Renaming variables, formatting, comments | Code review only | ### 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*`) - [ ] 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=`, `$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)