| name | research |
| description | Research and discover codebase information by breaking tasks into focused steps. Use when you need to understand existing patterns, find relevant files, locate integration points, or trace how something works before making changes. |
Research - Codebase Discovery
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:
- Start with semantic search - Ask the context engine for concepts
- Find files by pattern - Use glob for known naming conventions
- Search for strings - Use grep for specific terms
- Read key files - Examine implementation directly
Delegate Background Tasks (When Supported)
If your tools support parallel/background execution:
- Identify parallel research paths - What can be investigated independently?
- Launch focused searches - Each search answers one specific question
- 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:
- Decompose - Break into specific questions
- Execute - Search and investigate
- Synthesize - Combine findings into understanding
- Document - Capture paths and patterns
- Implement - With confidence
