shanepadgett 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