Investigating a Codebase

Overview

When to Use

• Verifying design assumptions before implementation ("Design assumes auth.ts exists - verify")
• Finding existing patterns to follow ("How do we currently handle API errors?")
• Locating features or code ("Where is user authentication implemented?")
• Understanding component architecture ("How does the routing system work?")
• Confirming existence definitively ("Does feature X exist or not?")
• Preventing hallucination about file paths and structure

• Information available in external docs (use internet research)
• Questions answered by reading 1-2 specific known files (use Read directly)
• General programming questions not specific to this codebase

Core Investigation Workflow

1. Start with entry points - main files, index, package.json, config
2. Use multiple search strategies - Glob patterns, Grep keywords, Read files
3. Follow traces - imports, references, component relationships
4. Verify don't assume - confirm file locations and structure
5. Report definitively - exact paths or "not found" with search strategy

Verifying Design Assumptions

1. Extract assumptions - list what design expects to exist
2. Search for each - file paths, functions, patterns, dependencies
3. Compare reality vs expectation - matches, discrepancies, additions, missing
4. Report explicitly:
   • ✓ Confirmed: "Design assumption correct: auth.ts:42 has login()"
   • ✗ Discrepancy: "Design assumes auth.ts, found auth/index.ts instead"
   • + Addition: "Found logout() not mentioned in design"
   • - Missing: "Design expects resetPassword(), not found"

Quick Reference

Investigation Strategies

• Glob for file patterns across codebase
• Grep for keywords, function names, imports
• Read key files to understand implementation
• Follow imports and references for relationships
• Check package.json, config files for dependencies

• Explore multiple paths to verify findings
• Cross-reference different areas of codebase
• Confirm patterns are consistent not one-off
• Follow both usage and definition traces

• Never assume file locations - always verify with Read/Glob
• Never assume structure - explore and confirm
• Document search strategy when reporting "not found"
• Distinguish "doesn't exist" from "couldn't locate"

Reporting Findings

• Answer the question first
• Supporting details second
• Evidence with exact file paths and line numbers

• Exact file paths (src/auth/login.ts:42), not vague locations
• Relevant code snippets showing current patterns
• Dependencies and versions when relevant
• Configuration files and current settings
• Naming, structure, and testing conventions

• "Feature X does not exist" is valid and useful
• Explain what you searched and where you looked
• Suggest related code as starting point
• Report negative findings prevents hallucination

Common Mistakes