Patterns and methods for researching a codebase to understand bug context using documentarian philosophy. Documents what exists without evaluation. Provides structured research using semantic search, file reading, and symbol tracing. Use when investigating how code works, finding related files, understanding code flow, tracing execution paths, locating bug symptoms in codebase, or documenting existing implementation.
This skill provides research patterns for bug investigation, following the HumanLayer documentarian philosophy.
From HumanLayer's research_codebase pattern:
YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
- DO NOT suggest improvements or changes
- DO NOT perform root cause analysis (that's a separate phase)
- DO NOT critique the implementation
- ONLY describe what exists, where it exists, how it works
| Tool Identifier | Purpose | Example Usage |
|---|---|---|
search/codebase | Semantic search | Find conceptually related code |
search/fileSearch | File name patterns | Find *.test.ts files |
search/textSearch | Grep-style search | Find exact error messages |
search/usages | Symbol usages | Trace function calls |
read/readFile | Read file contents | Get full context |
web/githubRepo | Git/GitHub info | Historical context |
runSubagent | Spawn subagent | Comprehensive research |
edit/editFiles | Create files | Save research documents |
Since VS Code subagents run sequentially (not in parallel), combine all research tasks into a single comprehensive subagent prompt:
Use a subagent to perform comprehensive codebase research for bug {TICKET-ID}.
## Research Tasks
### Task 1: Locate Relevant Code
Find all locations related to: {bug symptoms}
- Search for: {keywords, function names, error messages}
- Return: Table of file:line references
### Task 2: Analyze Code Flow
For relevant files, document:
- Entry points, data flow, dependencies, exit points
- Return: Flow diagram with file:line citations
### Task 3: Find Related Patterns
Search for:
- Similar code, related tests, documentation
- Return: Examples with file:line references
## Rules
- Document only, no evaluations
- Include file:line for every claim
Initial investigation hypotheses created before research:
Comprehensive research findings:
Verification of research accuracy:
Templates are available in the templates/ directory:
research-template.md - Main research document structurehypothesis-template.md - Initial hypotheses formatNever use these phrases in research documents: