Investigating a Codebase
Overview
Understand current codebase state to ground planning and design decisions in reality, not assumptions. Find existing patterns, verify design assumptions, and provide definitive answers about what exists and where.
When to Use
Use for:
- 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
Don't use for:
- 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
- Start with entry points - main files, index, package.json, config
- Use multiple search strategies - Glob patterns, Grep keywords, Read files
- Follow traces - imports, references, component relationships
- Verify don't assume - confirm file locations and structure
- Report definitively - exact paths or "not found" with search strategy
Verifying Design Assumptions
When given design assumptions to verify:
- Extract assumptions - list what design expects to exist
- Search for each - file paths, functions, patterns, dependencies
- Compare reality vs expectation - matches, discrepancies, additions, missing
- 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"
Why this matters: Prevents implementation plans based on wrong assumptions about codebase structure.
Quick Reference
| Task |
Strategy |
| Where is X |
Glob likely names → Grep keywords → Read matches |
| How does X work |
Find entry point → Follow imports → Read implementation |
| What patterns exist |
Find examples → Compare implementations → Extract conventions |
| Does X exist |
Multiple searches → Definitive yes/no → Evidence |
| Verify assumptions |
Extract claims → Search each → Compare reality vs expectation |
Investigation Strategies
Multiple search approaches:
- 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
Don't stop at first result:
- 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
Verify everything:
- 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
Lead with direct answer:
- Answer the question first
- Supporting details second
- Evidence with exact file paths and line numbers
Provide actionable intelligence:
- 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
Handle "not found" confidently:
- "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
| Mistake |
Fix |
| Assuming file locations |
Always verify with Read/Glob before reporting |
| Stopping at first result |
Explore multiple paths to verify findings |
| Vague locations ("in auth folder") |
Exact paths (src/auth/index.ts:42) |
| Not documenting search strategy |
Explain what was checked when reporting "not found" |
| Confusing "not found" types |
Distinguish "doesn't exist" from "couldn't locate" |
| Skipping design assumption comparison |
Explicitly report: confirmed/discrepancy/addition/missing |
| Reporting assumptions as facts |
Only report what was verified in codebase |
1---2name: investigating-a-codebase3description: Use when planning or designing features and need to understand current codebase state, find existing patterns, or verify assumptions about what exists - prevents hallucination by grounding plans in reality4---5
6# Investigating a Codebase
7
8## Overview
9
10Understand current codebase state to ground planning and design decisions in reality, not assumptions. Find existing patterns, verify design assumptions, and provide definitive answers about what exists and where.
11
12## When to Use
13
14**Use for:**
15- Verifying design assumptions before implementation ("Design assumes auth.ts exists - verify")
16- Finding existing patterns to follow ("How do we currently handle API errors?")
17- Locating features or code ("Where is user authentication implemented?")
18- Understanding component architecture ("How does the routing system work?")
19- Confirming existence definitively ("Does feature X exist or not?")
20- Preventing hallucination about file paths and structure
21
22**Don't use for:**
23- Information available in external docs (use internet research)
24- Questions answered by reading 1-2 specific known files (use Read directly)
25- General programming questions not specific to this codebase
26
27## Core Investigation Workflow
28
291. **Start with entry points** - main files, index, package.json, config
302. **Use multiple search strategies** - Glob patterns, Grep keywords, Read files
313. **Follow traces** - imports, references, component relationships
324. **Verify don't assume** - confirm file locations and structure
335. **Report definitively** - exact paths or "not found" with search strategy
34
35## Verifying Design Assumptions
36
37When given design assumptions to verify:
38
391. **Extract assumptions** - list what design expects to exist
402. **Search for each** - file paths, functions, patterns, dependencies
413. **Compare reality vs expectation** - matches, discrepancies, additions, missing
424. **Report explicitly**:
43 - ✓ Confirmed: "Design assumption correct: auth.ts:42 has login()"
44 - ✗ Discrepancy: "Design assumes auth.ts, found auth/index.ts instead"
45 - + Addition: "Found logout() not mentioned in design"
46 - - Missing: "Design expects resetPassword(), not found"
47
48**Why this matters:** Prevents implementation plans based on wrong assumptions about codebase structure.
49
50## Quick Reference
51
52| Task | Strategy |
53|------|----------|
54| **Where is X** | Glob likely names → Grep keywords → Read matches |
55| **How does X work** | Find entry point → Follow imports → Read implementation |
56| **What patterns exist** | Find examples → Compare implementations → Extract conventions |
57| **Does X exist** | Multiple searches → Definitive yes/no → Evidence |
58| **Verify assumptions** | Extract claims → Search each → Compare reality vs expectation |
59
60## Investigation Strategies
61
62**Multiple search approaches:**
63- Glob for file patterns across codebase
64- Grep for keywords, function names, imports
65- Read key files to understand implementation
66- Follow imports and references for relationships
67- Check package.json, config files for dependencies
68
69**Don't stop at first result:**
70- Explore multiple paths to verify findings
71- Cross-reference different areas of codebase
72- Confirm patterns are consistent not one-off
73- Follow both usage and definition traces
74
75**Verify everything:**
76- Never assume file locations - always verify with Read/Glob
77- Never assume structure - explore and confirm
78- Document search strategy when reporting "not found"
79- Distinguish "doesn't exist" from "couldn't locate"
80
81## Reporting Findings
82
83**Lead with direct answer:**
84- Answer the question first
85- Supporting details second
86- Evidence with exact file paths and line numbers
87
88**Provide actionable intelligence:**
89- Exact file paths (src/auth/login.ts:42), not vague locations
90- Relevant code snippets showing current patterns
91- Dependencies and versions when relevant
92- Configuration files and current settings
93- Naming, structure, and testing conventions
94
95**Handle "not found" confidently:**
96- "Feature X does not exist" is valid and useful
97- Explain what you searched and where you looked
98- Suggest related code as starting point
99- Report negative findings prevents hallucination
100
101## Common Mistakes
102
103| Mistake | Fix |
104|---------|-----|
105| Assuming file locations | Always verify with Read/Glob before reporting |
106| Stopping at first result | Explore multiple paths to verify findings |
107| Vague locations ("in auth folder") | Exact paths (src/auth/index.ts:42) |
108| Not documenting search strategy | Explain what was checked when reporting "not found" |
109| Confusing "not found" types | Distinguish "doesn't exist" from "couldn't locate" |
110| Skipping design assumption comparison | Explicitly report: confirmed/discrepancy/addition/missing |
111| Reporting assumptions as facts | Only report what was verified in codebase |
majiayu000