research

Guidance for effective codebase research.

When to Research

Research when you need to:

• Understand patterns before proposing changes
• Find relevant files for a task
• Locate integration points for new functionality
• Trace flows before modifying them
• Verify assumptions about structure
• Find similar implementations to follow

Research Strategy

Break Into Focused Steps

Decompose research into small, specific questions:

❌ "How does authentication work?"
✅ "Where are login routes defined?"
✅ "How are passwords hashed?"
✅ "Where are JWT tokens validated?"

Each question should:

• Have a clear, verifiable answer
• Focus on one aspect at a time
• Be answerable through code inspection

Use Available Tools

Search the codebase with available tools:

1. Start with semantic search - Ask the context engine for concepts
2. Find files by pattern - Use glob for known naming conventions
3. Search for strings - Use grep for specific terms
4. Read key files - Examine implementation directly

Delegate Background Tasks (When Supported)

If your tools support parallel/background execution:

1. Identify parallel research paths - What can be investigated independently?
2. Launch focused searches - Each search answers one specific question
3. Synthesize findings - Combine results into coherent understanding

Example:

Search 1: "Where are user models defined?"
Search 2: "Where is authentication middleware?"  
Search 3: "How are session tokens stored?"

Research Patterns

Finding Files/Locations

"Where are [X] handlers defined?"
"Find files related to [feature]"
"Locate [pattern] implementations"

Understanding Patterns

"How does this codebase handle [X]?"
"Show me error handling patterns"
"Find examples of [technique]"

Tracing Flows

"Trace: API route → controller → service → database"
"How does a request become a response?"
"Where is [X] transformed to [Y]?"

Finding Integration Points

"Where should [new feature] hook in?"
"What files would [change] affect?"

Documenting Findings

Capture discoveries concisely:

## Finding: Authentication Flow

- Entry: `src/routes/auth.js:15`
- Validation: `src/middleware/auth.js:42`
- Storage: `src/models/user.js:88`

When NOT to Research

Skip research when:

• File paths are already known
• Change is isolated and understood
• Following an existing researched plan
• Task is purely about artifacts (state.md, plan.md, etc.)

Research First, Then Act

For non-trivial changes:

1. Decompose - Break into specific questions
2. Execute - Search and investigate
3. Synthesize - Combine findings into understanding
4. Document - Capture paths and patterns
5. Implement - With confidence