Investigating Code Patterns

When to Use This Skill

• Understanding how existing systems work end-to-end
• Researching concepts or technologies in your codebase
• Exploring code structure, patterns, and dependencies
• Answering "how/where/what" questions about implementations
• NOT for building new features (use implementation skills for that)

Core Investigation Types

1. Code Flow: "How does X work?"

Trace execution end-to-end from entry point to outcome.

Steps:

1. Find the entry point (API endpoint, component, function)
2. Trace function calls and data transformations
3. Follow imports and dependencies
4. Identify key decision points and error handling

2. Code Location: "Where is X implemented?"

Find where functionality lives in the codebase.

Steps:

1. Search for relevant keywords using grep
2. Check related files and modules
3. Identify main implementation and supporting files
4. Verify entry points and usage patterns

3. Performance Analysis: "Why is X slow?"

Diagnose bottlenecks using 3-phase approach.

Phase 1: Locate bottleneck

• Find entry point where slowness occurs
• Trace execution path
• Identify all operations (DB queries, API calls, compute, I/O)
• Look for obvious issues: N+1 queries, nested loops, large payloads

Phase 2: Root cause (if unclear)

• Generate hypotheses ranked by likelihood
• Validate with evidence from code

Phase 3: Fix or instrument

• If fix clear → implement optimization
• If uncertain → add logging/profiling for user testing

Common performance patterns:

4. Architecture Mapping: "How is X structured?"

Understand system organization, components, and integration points.

Steps:

1. Map component boundaries and responsibilities
2. Identify data flow patterns between layers
3. Document integration points and dependencies
4. Trace external service interactions

Investigation Strategy

Start with Documentation

Read in this order:

1. docs/product-requirements.md — project overview and features (F-##)
2. docs/feature-spec/F-##-*.md — technical details
3. docs/system-design.md — architecture
4. docs/api-contracts.yaml — API reference

Choose Your Tools

For known file paths:

• Read — examine specific files directly

For pattern searches:

• Grep — find exact text matches (function names, imports, error messages)
• Glob — discover files by name pattern

For semantic queries:

• Launch context-engineer agent for complex, multi-file pattern discovery
• Use senior-engineer agent for subtle performance bottlenecks

Parallel Investigation

Launch 2-4 independent agents for large codebases:

Full-stack flow:

• Agent 1: Frontend (UI, state, API calls)
• Agent 2: Backend (endpoints, services, database)
• Agent 3: Integration (tests, config, external APIs)

Multi-service architecture:

• Agent 1: Auth (authentication, tokens)
• Agent 2: User service (profile, sync)
• Agent 3: Authorization (permissions, RBAC)

Performance issues:

• Agent 1: Frontend perf (renders, bundle, assets)
• Agent 2: API/network (queries, payloads, caching)
• Agent 3: Backend perf (algorithms, database, services)

Documenting Findings

Code Flow Template

## How [Feature] Works

### Purpose
[Brief description and why it exists]

### High-Level Flow
1. User action triggers [component/function] (file:line)
2. [Step 2 with file:line reference]
3. [Step 3 with file:line reference]
4. Final outcome

### Key Files
- `path/to/file.ts:123` - [Purpose]
- `path/to/other.ts:45` - [Purpose]

### Important Details
- Error handling: [Approach with file references]
- Edge cases: [How handled]
- Security: [Considerations if applicable]

Code Location Template

## Location: [Functionality]

### Main Implementation
`path/to/file.ts:45-120` - [Purpose]

### Related Files
- `path/component.tsx` - UI layer
- `path/service.ts` - Business logic
- `path/api.ts` - API integration

### Entry Points
1. [How users trigger this]
2. [System-initiated triggers]

Performance Analysis Template

## Performance Analysis: [Feature]

### Symptoms
- Slow when: [Condition]
- Observed: [X] seconds
- Expected: [Y] seconds

### Root Cause
[What's causing it with file:line evidence]

### Fix Options
**Option A: [Name]**
- Change: [What to do]
- Impact: [Expected improvement]
- Effort: [Time estimate]

**Recommendation:** [Which option and why]

Architecture Mapping Template

## Architecture: [System/Feature]

### Overview
[High-level description]

### Component Breakdown
**[Layer/Module Name]:**
- Responsibility: [What it does]
- Key files: [File paths]
- Dependencies: [What it needs]

### Data Flow
[Step-by-step or diagram]

### Integration Points
- [External services]
- [Related features]

Investigation Workflow

1. Clarify the question — What are you trying to understand?
2. Read project docs — Start with overview, feature specs, architecture
3. Choose investigation type — Flow, location, performance, or architecture
4. Search strategically — Use direct tools or delegate to agents
5. Document with file references — Use file:line format for all findings
6. Offer next steps — Deeper investigation, documentation, or implementation

Key Principles

• File references matter — Always cite file:line for evidence
• Evidence-based — Quote actual code, don't guess
• Multi-domain issues need parallel agents — Frontend + backend require separate investigators
• Start simple — Use direct grep/read before delegating
• Consolidate findings — Synthesize parallel agent results into coherent explanation