[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 ask user whether to skip.

Prerequisites: MUST READ before executing:

• .claude/skills/shared/understand-code-first-protocol.md
• .claude/skills/shared/evidence-based-reasoning-protocol.md
• .claude/skills/shared/graph-assisted-investigation-protocol.md — Graph ↔ Grep ↔ Glob orchestration (MANDATORY when graph.db exists)
• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

Quick Summary

Goal: READ-ONLY exploration of existing features and logic — understand how code works without making changes.

MANDATORY IMPORTANT MUST Plan ToDo Task to READ the following project-specific reference doc:

• project-structure-reference.md -- project patterns and structure

If file not found, search for: project documentation, coding standards, architecture docs.

Workflow:

1. Discovery — Search codebase for related files (Entities > Commands > Events > Controllers)
2. Knowledge Graph — Read and document purpose, symbols, dependencies per file
3. Flow Mapping — Trace entry points through pipeline to exit points
4. Analysis — Extract business rules, validation, authorization, error handling
5. Synthesis — Write executive summary with key files and flow diagrams
6. Present — Deliver findings, offer deeper dives on subtopics

Key Rules:

• Strictly READ-ONLY — no code changes allowed
• Evidence-based: every claim needs file:line proof (grep results, read confirmations)
• Mark unverified claims as "inferred" with low confidence
• Write analysis to .ai/workspace/analysis/[feature-name]-investigation.md
• For UI investigation, activate visual-component-finder skill FIRST

Feature Investigation

READ-ONLY exploration skill for understanding existing features. No code changes.

Investigation Mindset (NON-NEGOTIABLE)

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

• Do NOT assume code works as named — verify by reading actual implementations
• Every finding must include file:line evidence (grep results, read confirmations)
• If you cannot prove a claim with a code trace, mark it as "inferred" with low confidence
• Question assumptions: "Does this actually do what I think?" → read the implementation, not just the signature
• Challenge completeness: "Is this all?" → grep for related usages, consumers, and cross-service references
• Verify relationships: "Does A really call B?" → trace the actual call path with evidence
• No "looks like it works" without proof — state what you verified and how

Summary

Goal: READ-ONLY exploration of existing features and logic — understand how code works without making changes.

Step	Action	Key Notes
1	Discovery	Search codebase for related files (Entities > Commands > Events > Controllers)
2	Knowledge Graph	Read and document purpose, symbols, dependencies per file
3	Flow Mapping	Trace entry points through pipeline to exit points
4	Analysis	Extract business rules, validation, authorization, error handling
5	Synthesis	Write executive summary with key files and flow diagrams
6	Present	Deliver findings, offer deeper dives on subtopics

Key Principles:

• Strictly READ-ONLY — no code changes allowed
• MUST read evidence-based-reasoning-protocol.md and knowledge-graph-template.md before starting
• Evidence-based: validate every assumption with actual code references

UI/Frontend Investigation? If investigating a UI component from a screenshot, image, or visual reference, activate visual-component-finder skill FIRST. It uses a pre-built component index (docs/component-index.json) to match visuals to Angular components with >=85% confidence before deeper investigation.

Mode Selection

Mode	Use When	Workflow
Interactive	User available, exploratory question	Real-time collaboration, iterative tracing
Autonomous	Deep analysis, complex cross-service tracing	Structured 4-phase workflow with analysis artifact

Workflow

1. Discovery - Search codebase for all files related to the feature/question. Prioritize: Entities > Commands/Queries > EventHandlers > Controllers > Consumers > Components.
2. Graph Expand (MANDATORY — DO NOT SKIP) - YOU (the main agent) MUST run graph queries YOURSELF on key files found in Step 1. This step is NOT optional — without graph, your understanding is incomplete. Sub-agents CANNOT use graph — only you can. Pick 2-3 key files (entities, commands, bus messages) and run:

   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
   # If "ambiguous" → search to disambiguate, then 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 the complete dependency network (callers, importers, tests, inheritance) that grep alone misses. This is essential for understanding features and workflows fully. Also run /graph-connect-api for frontend-to-backend API mapping.
3. Knowledge Graph - Read and analyze each file (from grep + graph results). Document purpose, symbols, dependencies, data flow. Batch in groups of 10, update progress after each batch.
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 logic, authorization, error handling. Document happy path and edge cases.
6. Synthesis - Write executive summary answering the original question. Include key files, patterns used, and text-based flow diagrams.
7. Present - Deliver findings using the structured output format. Offer deeper dives on subtopics.

⚠️ MUST READ Before Investigation

IMPORTANT: You MUST read these files before starting. Do NOT skip.

• ⚠️ MUST READ .claude/skills/shared/evidence-based-reasoning-protocol.md — Assumption validation, evidence chains, context anchoring
• ⚠️ MUST READ .claude/skills/shared/knowledge-graph-template.md — Per-file analysis structure

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

Investigation Techniques

Discovery Search Patterns

File Discovery by Feature Name

.*EventHandler.*{FeatureName}|{FeatureName}.*EventHandler
.*BackgroundJob.*{FeatureName}|{FeatureName}.*BackgroundJob
.*Consumer.*{FeatureName}|{FeatureName}.*Consumer
.*Service.*{FeatureName}|{FeatureName}.*Service
.*Component.*{FeatureName}|{FeatureName}.*Component

Priority Order for Analysis

1. Domain Entities - Core business objects
2. Commands/Queries - CQRS entry points (UseCaseCommands/, UseCaseQueries/)
3. Event Handlers - Side effects (UseCaseEvents/, *EventHandler.cs)
4. Controllers - API endpoints (Controllers/, *Controller.cs)
5. Consumers - Cross-service (*Consumer.cs, *BusMessage.cs)
6. Background Jobs - Scheduled processing (*BackgroundJob*.cs, *Job.cs)
7. Components/Stores - Frontend (*.component.ts, *.store.ts)
8. Services/Helpers - Supporting logic (*Service.cs, *Helper.cs)

Dependency Tracing

Backend

Looking for	Search pattern
Who calls this method	Grep method name across *.cs
Who injects this service	Grep interface name in constructors
What events this entity raises	Grep EntityEvent<EntityName> (search for: project entity event class)
Cross-service consumers	Grep *BusMessage type across all services
Repository usage	Grep IRepository<EntityName> or project queryable repository interface

Frontend

Looking for	Search pattern
Who uses this component	Grep selector app-component-name in *.html
Who imports this service	Grep service class name in *.ts
Store effects chain	Trace effectSimple -> API call -> tapResponse -> state update
Route entry	Grep component name in *routing*.ts

Data Flow Mapping

Document flow as text diagram:

[Entry Point] --> [Step 1: Validation] --> [Step 2: Processing] --> [Step 3: Persistence]
                                                  |
                                                  v
                                          [Side Effect: Event]

Flow Documentation Checklist

1. Entry Points - API endpoint, UI action, scheduled job, message bus
2. Processing Pipeline - Step-by-step through handlers
3. Data Transformations - How data changes at each step
4. Persistence Points - Where data is saved/loaded
5. Exit Points - Responses, events, side effects
6. Cross-Service Flows - Message bus boundaries

Common Investigation Scenarios

"How does feature X work?"

1. Find entry points (API, UI, job)
2. Trace through command/query handlers
3. Document entity changes
4. Map side effects (events, notifications)

"Where is the logic for Y?"

1. Search keywords in commands, queries, entities
2. Check event handlers for side effect logic
3. Look in helper/service classes
4. Check frontend stores and components

"What happens when Z occurs?"

1. Identify trigger (user action, event, schedule)
2. Trace the handler chain
3. Document all side effects
4. Map error handling

"Why does A behave like B?"

1. Find the relevant code path
2. Identify decision points
3. Check configuration/feature flags
4. Document business rules

Project Pattern Recognition (see docs/project-reference/backend-patterns-reference.md and docs/project-reference/frontend-patterns-reference.md)

Backend Patterns

• CQRS command / query base classes - CQRS entry points
• Entity event application handler - Side effects
• Message bus consumer base class - Cross-service consumers
• Project queryable root repository - Data access
• Project validation fluent API - Validation logic
• Project authorization attributes - Authorization

Frontend Patterns

• Project store component base (search for: store component base class) - State management components
• Project store base (search for: store base class) - Store implementations
• effectSimple / tapResponse - Effect handling
• observerLoadingErrorState - Loading/error states
• API services extending project API service base class

Evidence Collection

Analysis File Setup

MANDATORY (all modes): Write analysis to .ai/workspace/analysis/[feature-name]-investigation.md. Re-read ENTIRE file before presenting findings in Step 6. This prevents knowledge loss during long investigations.

Analysis file structure:

## Metadata

> Original question: [user's exact question]

## Investigation Question

[Clearly stated investigation goal]

## Progress

- **Phase**: 1
- **Items Processed**: 0 / [total]
- **Current Focus**: [original question]

## File List

[All discovered files, grouped by priority]

## Knowledge Graph

[Per-file analysis entries - see template below]

## Data Flow

[Flow diagrams and pipeline documentation]

## Findings

[Populated in Phase 2+]

Per-File Analysis Entry

For each file, document in ## Knowledge Graph:

Core Fields

• filePath: Full path
• type: Component classification (Entity, Command, Handler, Controller, Component, Store, etc.)
• architecturalPattern: Design pattern used
• content: Purpose and logic summary
• symbols: Key classes, interfaces, methods
• dependencies: Imports/injections
• relevanceScore: 1-10 (to investigation question)
• evidenceLevel: "verified" or "inferred"

Investigation-Specific Fields

• entryPoints: How this code is triggered/called
• outputPoints: What this code produces/returns
• dataTransformations: How data is modified
• conditionalLogic: Key decision points and branches
• errorScenarios: What can go wrong, error handling
• externalDependencies: External services, APIs, databases

Cross-Service Fields (if applicable)

• messageBusMessage: Message type consumed/produced
• messageBusProducers: Who sends this message
• crossServiceIntegration: Cross-service data flow

Rule: After every 10 files, update progress and re-check alignment with original question.

Structured Findings Format

Phase 2: Comprehensive Analysis

Workflow Analysis

1. Happy Path - Normal successful execution flow
2. Error Paths - How errors are handled at each stage
3. Edge Cases - Special conditions
4. Authorization - Permission checks
5. Validation - Input validation at each layer

Business Logic Extraction

1. Core Business Rules - What rules govern this feature
2. State Transitions - Entity state changes
3. Side Effects - Notifications, events, external calls

Phase 3: Synthesis

Executive Summary

• One-paragraph answer to user's question
• Top 5-10 key files
• Key patterns used

Detailed Explanation

• Step-by-step walkthrough with file:line references
• Architectural decisions explained

Diagrams

+-----------+     +-----------+     +-----------+
| Component |---->|  Command  |---->|  Handler  |
+-----------+     +-----------+     +-----------+
                                          |
                                          v
                                    +-----------+
                                    |Repository |
                                    +-----------+

Output Format

## Answer

[Direct answer in 1-2 paragraphs]

## How It Works

### 1. [Step] - [Explanation with `file:line` reference]

### 2. [Step] - [Explanation with `file:line` reference]

## Key Files

| File | Purpose |
| ---- | ------- |

## Data Flow

[Text diagram: Entry -> Processing -> Persistence -> Side Effects]

## Want to Know More?

- [Subtopic 1]
- [Subtopic 2]

Guidelines

• Evidence-based: Every claim needs code evidence. Mark unverified claims as "inferred".
• Question-focused: Tie all findings back to the original question.
• Read-only: Never suggest changes unless explicitly asked.
• Layered explanation: Start simple, offer deeper detail on request.

Graph Intelligence (MANDATORY when graph.db exists)

See .claude/skills/shared/graph-assisted-investigation-protocol.md for full orchestration guidance. See .claude/skills/shared/graph-intelligence-queries.md for CLI command reference.

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:

1. Grep for key terms from the user's query (class names, commands, handlers, endpoints)
2. Use discovered files as input to graph connections, batch-query, or trace commands
3. Use trace --direction both on middle files (controllers, commands) to see full upstream + downstream flow
4. The trace command follows ALL edge types including implicit connections (MESSAGE_BUS, TRIGGERS_EVENT)

Orchestrate grep ↔ graph ↔ glob dynamically. After grep/glob finds entry files, use graph to expand the dependency network. Then grep again to verify content in discovered files.

# Full picture of a key file
python .claude/scripts/code_graph connections <file> --json

# Find all callers of a function
python .claude/scripts/code_graph query callers_of <name> --json

# Find all importers of a module
python .claude/scripts/code_graph query importers_of <file> --json

# Find tests covering a function
python .claude/scripts/code_graph query tests_for <name> --json

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

Related Skills

• feature - Implementing new features (code changes)
• debug - Debugging and fixing issues
• scout - Quick codebase discovery (run before investigation)
• graph-query - Natural language graph queries for code relationships

IMPORTANT Task Planning Notes

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed

---

Investigation & Recommendation Protocol

Moved from CLAUDE.md. This protocol applies when recommending code changes (removal, refactoring, replacement) — not just feature investigation. It ensures evidence-based architectural decisions and prevents mistakes like the Npgsql IDbContextFactory incident.

📚 Reference: See .claude/skills/shared/evidence-based-reasoning-protocol.md for comprehensive evidence-based reasoning protocols with verification commands and forbidden phrases. See .claude/docs/anti-hallucination-patterns.md for bad vs good response examples.

Golden Rule: Evidence Before Conclusion

NEVER recommend code changes (removal, refactoring, replacement) without completing this validation chain:

1. Interface/API identified
   ↓
2. ALL implementations found (Grep: "class.*:.*IInterfaceName")
   ↓
3. ALL registrations traced (Grep: "AddScoped.*IInterfaceName|AddSingleton.*IInterfaceName")
   ↓
4. ALL usage sites verified (Grep: "IInterfaceName" in context of injection/calls)
   ↓
5. Cross-service impact: Check ALL project services (ServiceB, ServiceA, ServiceC, ServiceD)
   ↓
6. Impact assessment: What breaks if removed?
   ↓
7. Confidence declaration: X% confident based on [evidence list]
   ↓
ONLY THEN → Output recommendation

If ANY step incomplete → STOP and gather more evidence OR state "Insufficient evidence to recommend removal"

Mistake Patterns & Prevention

Mistake Pattern	Prevention Rule	Grep Pattern
"This is unused"	Require proof of zero references	grep -r "TargetName" --include="*.cs"
"Remove this registration"	Trace interface → impl → ALL call sites	grep "IInterfaceName" -A 5 -B 5
"Replace X with Y"	Impact analysis: what depends on X?	grep "using.*X|: X|<X>" --include="*.cs"
"This can be simplified"	Verify edge cases preserved	Check tests, usage contexts
"Dual registration"	Compare services: ServiceA vs ServiceB pattern	Cross-service comparison required

Breaking Change Risk Matrix

Before recommending ANY architectural change, assess risk level:

Risk Level	Criteria	Required Evidence
HIGH	Removing registrations, deleting classes, changing interfaces	Full usage trace + impact analysis + cross-service check (all project services)
MEDIUM	Refactoring methods, changing signatures, updating patterns	Usage trace + test verification + cross-service check (all project services)
LOW	Renaming variables, formatting, adding comments	Code review only

For HIGH/MEDIUM risk changes: Require explicit confidence declaration with evidence summary before proceeding.

Evidence Hierarchy

1. Code Evidence (Primary) — Actual usage in codebase (Grep results, Read file confirmations)
2. Test Evidence — Unit/integration tests covering the code path
3. Documentation — Comments, docs explaining purpose
4. Inference — Logical deduction (LOWEST priority, must be validated)

Rule: Recommendations based on inference alone are FORBIDDEN. Always upgrade to code evidence.

Validation Checklist for Code Removal

Before recommending removal of ANY code element, verify ALL of these:

• No static references — grep -r "ClassName" --include="*.cs" returns 0 results
• No string literals — grep -r "\"ClassName\"|'ClassName'" returns 0 results
• No dynamic invocations — Check reflection, factory patterns, message bus registrations
• No DI container registrations — Search services.Add*<ClassName> patterns
• No configuration references — Check appsettings.json, environment variables
• No test dependencies — Check test projects for usage
• Cross-service impact — Search ALL project's microservices (ServiceB, ServiceA, ServiceC, ServiceD)

Confidence Declaration: If checklist not 100% complete, state: "Confidence: <90% — did not verify [missing items]"

Interface → Implementation → Usage Trace Protocol

For any interface-based recommendation:

# Step 1: Find ALL implementations
grep -r "class.*:.*ITargetInterface" --include="*.cs"

# Step 2: Find ALL registrations
grep -r "AddScoped\|AddSingleton\|AddTransient.*ITargetInterface" --include="*.cs"

# Step 3: Find ALL injection points
grep -r "ITargetInterface" --include="*.cs" -A 5 -B 5

# Step 4: Find ALL usage in found implementations
# Read each file from Step 3, trace method calls

# Step 5: Cross-service check (MANDATORY - all project services)
for svc in ServiceB ServiceA ServiceC Accounts ServiceD; do
    grep -r "ITargetInterface" "services directory/$svc" --include="*.cs"
done

# ONLY if ALL steps show zero usage → recommend removal

Comparison Pattern (Service vs Service)

When investigating service-specific implementations:

1. Find working reference service — Identify service where feature works correctly
2. Compare implementations — Side-by-side file comparison
3. Identify differences — List what's different between working vs non-working
4. Verify each difference — Understand WHY each difference exists
5. Recommend changes — Based on proven working pattern, not assumptions

Confidence Levels (Required for Architectural Recommendations)

Every recommendation for code removal/refactoring MUST include confidence level:

• 95-100% — Full trace completed, all checklist items verified, all project services checked
• 80-94% — Main usage paths verified, some edge cases unverified
• 60-79% — Implementation found, usage partially traced
• <60% — Insufficient evidence → DO NOT RECOMMEND, gather more evidence first

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

When to Activate This Protocol

Trigger the full validation chain for:

• Any recommendation to remove registrations, classes, interfaces
• Architectural changes affecting multiple services
• "This seems unused" observations
• Cross-service dependency analysis
• Breaking change impact assessment