[IMPORTANT] Use

TaskCreate

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.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. 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.

AI Mistake Prevention — Failure modes to avoid on every task:

• Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal.
• Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing.
• Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain.
• Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path.
• When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site.
• Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code.
• Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks.
• Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis.
• Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly.
• Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

1. Cite

   file:line

   , grep results, or framework docs for EVERY claim
2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
3. Cross-service validation required for architectural changes
4. "I don't have enough evidence" is valid and expected output

BLOCKED until:

- [ ]

Evidence file path (

file:line

)

- [ ]

Grep search performed

- [ ]

3+ similar patterns found

- [ ]

Confidence level stated

Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output:

"Insufficient evidence. Verified: [...]. Not verified: [...]."

• docs/project-reference/domain-entities-reference.md

  — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (content auto-injected by hook — check for [Injected: ...] header before reading)

Rationalization Prevention — AI skips steps via these evasions. Recognize and reject:

Evasion	Rebuttal
"Too simple for a plan"	Simple + wrong assumptions = wasted time. Plan anyway.
"I'll test after"	RED before GREEN. Write/verify test first.
"Already searched"	Show grep evidence with file:line . No proof = no search.
"Just do it"	Still need TaskCreate. Skip depth, never skip tracking.
"Just a small fix"	Small fix in wrong location cascades. Verify file:line first.
"Code is self-explanatory"	Future readers need evidence trail. Document anyway.
"Combine steps to save time"	Combined steps dilute focus. Each step has distinct purpose.

Fix-Layer Accountability — NEVER fix at the crash site. Trace the full flow, fix at the owning layer.

AI default behavior: see error at Place A → fix Place A. This is WRONG. The crash site is a SYMPTOM, not the cause.

MANDATORY before ANY fix:

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

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)

Anti-patterns (REJECT these):

• "Fix it where it crashes" — Crash site ≠ cause site. Trace upstream.
• "Add defensive checks at every consumer" — Scattered defense = wrong layer. One authoritative fix > many scattered guards.
• "Both fix is safer" — Pick ONE authoritative layer. Redundant checks across layers send mixed signals about who owns the invariant.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in

plans/reports/

— prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires

file:line

proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

Quick Summary

Goal: Fast, parallel codebase file discovery to locate all files relevant to a task.

Workflow:

1. Analyze Request — Extract entity names, feature keywords, file types from prompt
2. Parallel Search — Spawn 3 agents searching backend core, backend infra, and frontend paths
3. Graph Expand (MANDATORY — DO NOT SKIP) — YOU MUST ATTENTION run

   /graph-query

   on 2-3 key files found in Step 2. This is NOT optional. Graph reveals the complete dependency network that grep alone CANNOT find. Use

   /graph-connect-api

   for frontend↔backend API tracing. Without this step, investigation results are incomplete.
4. Synthesize — Combine grep + graph results into numbered, prioritized file list with suggested starting points

Key Rules:

• Speed over depth -- return file paths only, no content analysis
• Target 3-5 minutes total completion time
• 3-minute timeout per agent; skip agents that don't return in time

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Scout - Fast Codebase File Discovery

Fast codebase search to locate files needed for a task. Token-efficient, parallel execution.

KEY PRINCIPLE: Speed over depth. Return file paths only - no content analysis. Target 3-5 minutes total.

When to Use

• Quickly locating relevant files across a large codebase
• Beginning work on features spanning multiple directories
• Before making changes that might affect multiple parts
• Mapping file landscape before investigation or implementation
• Finding all files related to an entity, feature, or keyword

NOT for: Deep code analysis (use

feature-investigation

debug-investigate

feature-implementation

Quick Reference

USER_PROMPT

SCALE

REPORT_OUTPUT_DIR

Report:

## Naming

Workflow

Step 1: Analyze Search Request

Extract keywords from USER_PROMPT to identify:

• Entity names (e.g., User, Customer, Order)
• Feature names (e.g., authentication, notification)
• File types needed (backend, frontend, or both)

Step 2: Execute Parallel Search

Spawn SCALE number of

scout

subagent_type: "scout"

WHY

scout

Explore

scout

.claude/agents/scout.md

Explore

Agent Distribution Strategy

• Agent 1 - Backend Core:

  src/Services/*/Domain/

  ,

  src/Services/*/UseCaseCommands/

  ,

  src/Services/*/UseCaseQueries/

• Agent 2 - Backend Infra:

  src/Services/*/UseCaseEvents/

  ,

  src/Services/*/Controllers/

  ,

  src/Services/*/BackgroundJobs/

• Agent 3 - Frontend:

  {frontend-apps-dir}/

  ,

  {frontend-libs-dir}/{domain-lib}/

  ,

  {frontend-libs-dir}/{common-lib}/

Agent Instructions

• Timeout: 3 minutes per agent
• Skip agents that don't return within timeout
• Use Glob for file patterns, Grep for content search, Bash for graph CLI
• Return only file paths, no content

Step 3: Graph Expand (MANDATORY — DO NOT SKIP)

YOU (the main agent) MUST ATTENTION run these graph commands YOURSELF after sub-agents return. This step is NOT optional — without graph, results are incomplete. Sub-agents cannot use graph — only you can.

# Check graph exists
ls .code-graph/graph.db 2>/dev/null && echo "GRAPH_AVAILABLE" || echo "NO_GRAPH"

If GRAPH_AVAILABLE, pick 2-3 key files from sub-agent results (entities, commands, bus messages) and run:

# Get full dependency network of a key file
python .claude/scripts/code_graph connections <key_file> --json

# Find ALL callers of a key command/handler
python .claude/scripts/code_graph query callers_of <FunctionName> --json

# Find ALL importers of a bus message class
python .claude/scripts/code_graph query importers_of <file_path> --json

# Batch query multiple files at once
python .claude/scripts/code_graph batch-query <file1> <file2> <file3> --json

# If graph returns "ambiguous" — search to disambiguate, then retry with qualified name
python .claude/scripts/code_graph search <keyword> --kind Function --json

# Find shortest path between two nodes (trace how A connects to B)
python .claude/scripts/code_graph find-path <source_qn> <target_qn> --json

# Filter results by service and limit count
python .claude/scripts/code_graph query callers_of <name> --limit 5 --filter "ServiceName" --json

Merge graph results with sub-agent grep results. Graph discovers files that grep missed (structural relationships).

Step 4: Synthesize Results

Combine grep + graph results into a numbered, prioritized file list (see Results Format below).

Search Patterns by Priority

# HIGH PRIORITY - Core Logic
**/Domain/Entities/**/*{keyword}*.cs
**/UseCaseCommands/**/*{keyword}*.cs
**/UseCaseQueries/**/*{keyword}*.cs
**/UseCaseEvents/**/*{keyword}*.cs
**/*{keyword}*.component.ts
**/*{keyword}*.store.ts

# MEDIUM PRIORITY - Infrastructure
**/Controllers/**/*{keyword}*.cs
**/BackgroundJobs/**/*{keyword}*.cs
**/*Consumer*{keyword}*.cs
**/*{keyword}*-api.service.ts

# LOW PRIORITY - Supporting
**/*{keyword}*Helper*.cs
**/*{keyword}*Service*.cs
**/*{keyword}*.html

Graph Intelligence (MANDATORY when graph.db exists)

Graph-Assisted Investigation — MANDATORY when

.code-graph/graph.db

exists.

HARD-GATE: MUST ATTENTION run at least ONE graph command on key files before concluding any investigation.

Pattern: Grep finds files →

trace --direction both

reveals full system flow → Grep verifies details

Task	Minimum Graph Action
Investigation/Scout	trace --direction both on 2-3 entry files
Fix/Debug	callers_of on buggy function + tests_for
Feature/Enhancement	connections on files to be modified
Code Review	tests_for on changed functions
Blast Radius	trace --direction downstream

CLI:

python .claude/scripts/code_graph {command} --json

. Use

--node-mode file

first (10-30x less noise), then

--node-mode function

for detail.

Incremental Result Persistence — MANDATORY for all sub-agents or heavy inline steps processing >3 files.

1. Before starting: Create report file

   plans/reports/{skill}-{date}-{slug}.md

2. After each file/section reviewed: Append findings to report immediately — never hold in memory
3. Return to main agent: Summary only (per SYNC:subagent-return-contract) with

   Full report:

   path
4. Main agent: Reads report file only when resolving specific blockers

Why: Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results.

Report naming:

plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md

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.

## Sub-Agent Result: [skill-name]

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
Confidence: [0-100]%

### Findings (Critical/High only — max 10 bullets)

- [severity] [file:line] [finding]

### Actions Taken

- [file changed] [what changed]

### Blockers (if any)

- [blocker description]

Full report: plans/reports/[skill-name]-[date]-[slug].md

Main agent reads

Full report

file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan. Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.

If

.code-graph/graph.db

Grep-First Discovery (When Query is Semantic)

When the user's prompt describes a behavior or flow (not a specific file), use Grep/Glob/Search FIRST to discover entry point files before using graph tools:

1. Grep for key terms from the user's query (class names, commands, handlers, endpoints)
2. Use discovered files as input to

   connections

   ,

   batch-query

   , or

   trace

   commands
3. Use

   trace --direction both

   on middle files (controllers, commands) to see full upstream + downstream flow

After grep/glob finds entry files, use graph to expand the network:

# Check graph exists
ls .code-graph/graph.db 2>/dev/null && echo "AVAILABLE" || echo "MISSING"

# Full picture of a key file (callers + importers + tests in one call)
python .claude/scripts/code_graph connections <file> --json

# Find all callers of a function/command (e.g., after finding a handler)
python .claude/scripts/code_graph query callers_of <name> --json

# Find all importers of a module/entity (e.g., after finding a BusMessage)
python .claude/scripts/code_graph query importers_of <file> --json

# Batch query multiple files at once (most efficient)
python .claude/scripts/code_graph batch-query <f1> <f2> <f3> --json

Key: Graph results get HIGHER priority than grep (structural relationships > text matches). After graph expansion, grep again to verify content in discovered files.

Results Format

## Scout Results: {USER_PROMPT}

### High Priority - Core Logic

1. `src/Services/{Service}/Domain/Entities/{Entity}.cs`
2. `src/Services/{Service}/UseCaseCommands/{Feature}/Save{Entity}Command.cs`
   ...

### Medium Priority - Infrastructure

10. `src/Services/{Service}/Controllers/{Entity}Controller.cs`
11. `src/Services/{Service}/UseCaseEvents/{Feature}/SendNotificationOn{Entity}CreatedEventHandler.cs`
    ...

### Low Priority - Supporting

20. `src/Services/{Service}/Helpers/{Entity}Helper.cs`
    ...

### Frontend Files

30. `{frontend-libs-dir}/{domain-lib}/src/lib/{feature}/{feature}-list.component.ts`
    ...

**Total Files Found:** {count}
**Search Completed In:** {time}

### Suggested Starting Points

1. `{most relevant file}` - {reason}
2. `{second most relevant}` - {reason}

### Unresolved Questions

- {any questions that need clarification}

Quality Standards

Report Output

Use naming pattern:

plans/reports/scout-{date}-{slug}.md

Output Standards:

• Sacrifice grammar for concision
• List unresolved questions at end
• Always provide numbered file list with priority ordering

See Also

• feature-investigation

  skill - Deep analysis of discovered files

• feature-implementation

  skill - Implementing features after scouting

• planning

  skill - Creating implementation plans from scouted files

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use

AskUserQuestion

to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:

1. Activate

   investigation

   workflow (Recommended) — scout → investigate
2. Execute

   /scout

   directly — run this skill standalone

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use

AskUserQuestion

• "/investigate (Recommended)" — Deep-dive into discovered files to understand logic and relationships
• "/plan" — If scouted files are sufficient to start planning implementation
• "Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using

TaskCreate

AskUserQuestion

• IMPORTANT MUST ATTENTION cite

  file:line

  evidence for every claim. Confidence >80% to act, <60% = do NOT recommend. <!-- /SYNC:evidence-based-reasoning:reminder --> <!-- SYNC:rationalization-prevention:reminder -->
• IMPORTANT MUST ATTENTION never skip steps via evasions. Plan anyway. Test first. Show grep evidence with

  file:line

  . <!-- /SYNC:rationalization-prevention:reminder --> <!-- SYNC:graph-assisted-investigation:reminder -->
• IMPORTANT MUST ATTENTION run at least ONE graph command on key files before concluding when

  .code-graph/graph.db

  exists. <!-- /SYNC:graph-assisted-investigation:reminder --> <!-- SYNC:fix-layer-accountability:reminder -->
• IMPORTANT MUST ATTENTION trace full data flow and fix at the owning layer, not the crash site. Audit all access sites before adding

  ?.

  . <!-- /SYNC:fix-layer-accountability:reminder --> <!-- SYNC:critical-thinking-mindset:reminder -->
• MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact. <!-- /SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->
• MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction. <!-- /SYNC:ai-mistake-prevention:reminder -->