Feature Investigation

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

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 anti-hallucination-protocol.md and knowledge-graph-template.md before starting
Evidence-based: validate every assumption with actual code references

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

Discovery - Search codebase for all files related to the feature/question. Prioritize: Entities > Commands/Queries > EventHandlers > Controllers > Consumers > Components.
Knowledge Graph - Read and analyze each file. Document purpose, symbols, dependencies, data flow. Batch in groups of 10, update progress after each batch.
Flow Mapping - Trace entry points through processing pipeline to exit points. Map data transformations, persistence, side effects, cross-service boundaries.
Analysis - Extract business rules, validation logic, authorization, error handling. Document happy path and edge cases.
Synthesis - Write executive summary answering the original question. Include key files, patterns used, and text-based flow diagrams.
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/anti-hallucination-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

regex

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

Priority Order for Analysis

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

Dependency Tracing

Backend (C#)

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 `PlatformCqrsEntityEvent<EntityName>`
Cross-service consumers	Grep `*BusMessage` type across all services
Repository usage	Grep `IRepository<EntityName>` or `IPlatformQueryableRootRepository<EntityName`

Frontend (TypeScript)

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:

text

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

Flow Documentation Checklist

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

Common Investigation Scenarios

"How does feature X work?"

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

"Where is the logic for Y?"

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

"What happens when Z occurs?"

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

"Why does A behave like B?"

Find the relevant code path
Identify decision points
Check configuration/feature flags
Document business rules

Platform Pattern Recognition

Backend Patterns

```
PlatformCqrsCommand
```
/
```
PlatformCqrsQuery
```
- CQRS entry points

PlatformCqrsEntityEventApplicationHandler

- Side effects

```
PlatformApplicationMessageBusConsumer
```
- Cross-service consumers
```
IPlatformQueryableRootRepository
```
- Data access
```
PlatformValidationResult
```
- Validation logic
```
[PlatformAuthorize]
```
- Authorization

Frontend Patterns

```
AppBaseVmStoreComponent
```
- State management components
```
PlatformVmStore
```
- Store implementations
```
effectSimple
```
/
```
tapResponse
```
- Effect handling
```
observerLoadingErrorState
```
- Loading/error states
API services extending
```
PlatformApiService
```

Evidence Collection

Analysis File Setup

Autonomous mode writes analysis to

.ai/workspace/analysis/[feature-name]-investigation.md

with:

markdown

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

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

Business Logic Extraction

Core Business Rules - What rules govern this feature
State Transitions - Entity state changes
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