What is codebase-research?

The Codebase Research skill provides a structured, 'documentarian' framework for deep-dive investigation into complex codebases. It streamlines the process of understanding bug contexts, mapping execution flows, and locating relevant code symbols by focusing on factual documentation rather than premature fixes, ensuring developers have a verified foundation before starting root cause analysis.

When should I use codebase-research?

codebase-research is useful in the following scenarios: • Bug Context Investigation: Systematically identifying all files, functions, and error message locations related to a specific ticket to understand the full scope of an issue. • Legacy Code Onboarding: Rapidly mapping out data flows, entry points, and dependencies when navigating unfamiliar repositories or poorly documented legacy systems. • Impact Analysis: Tracing symbol usages and code relationships to determine the potential side effects of a proposed change across the entire codebase. • Technical Documentation Generation: Creating factual, citation-backed research documents (like codebase-research.md) that describe how a feature is currently implemented for team knowledge sharing.

name	codebase-research
description	Patterns and methods for researching a codebase to understand bug context. Use when investigating how code works, finding related files, or understanding code flow.
license	MIT
compatibility	VS Code Insiders with GitHub Copilot
author	accruent
version	"2.0"
based-on	HumanLayer research_codebase pattern

Codebase Research

This skill provides research patterns for bug investigation, following the HumanLayer documentarian philosophy.

Core Principles

The 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

Research Best Practices

Read files FULLY first - Never use limit/offset for initial reads
Use a single comprehensive subagent - VS Code subagents run sequentially
Wait for subagent to complete - Synthesize only after it returns
Verify every claim - Include file:line references
Stay factual - No opinions, evaluations, or suggestions

VS Code Copilot Tool Reference

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

Subagent Research Pattern

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

Research Document Structure

hypothesis.md

Initial investigation hypotheses created before research:

Symptom analysis
Investigation areas with search targets
Priority order