Researching Codebases

Coordinate parallel sub-agents to answer complex codebase questions.

When to Use

• Questions spanning multiple files or components
• "How does X work?" requiring tracing through code
• Finding patterns or examples across the codebase
• Understanding architectural decisions or data flow

When NOT to Use

• Simple "where is X?" - use code-locator directly
• Single file questions - just read the file
• External/web research only - use web-searcher directly

Workflow

0. Check past research (optional)

Before decomposing a new research question, consider checking for related past research:

1. Run list-research.py script to see recent research docs
2. Run search-research.py script with relevant keywords
3. If related research exists, run read-research.py script to load it
4. Build on previous findings instead of starting fresh

See research-tools.md for script usage.

1. Read mentioned files first

If the user references specific files, read them FULLY before spawning agents. This gives you context for decomposition.

2. Decompose the question

Break the query into parallel research tasks. Consider:

• Which areas of the codebase are relevant?
• Do I need locations, analysis, or examples?
• See agent-selection.md for agent capabilities

3. Spawn parallel agents

Launch multiple agents concurrently for independent tasks. Use the task tool with appropriate subagent_type.

Wait for ALL agents to complete before synthesizing.

4. Synthesize and respond

Combine findings into a coherent answer:

• Direct answer to the question
• Key file:line references
• Connections between components
• Open questions if any areas need more investigation

5. Offer to save (optional)

For substantial research, ask:

Want me to save this to a research doc? (project: .research/ or global: ~/.research/)

Skip this for quick answers.

When saving:

1. Run gather-metadata.py script to get date, repo, branch, commit, cwd.
2. Add query (from user's question) and tags (from content)
3. Format YAML frontmatter per output-format.md
4. Create directory if it doesn't exist
5. Use filename: {filename_date}_topic-slug.md

Agent Reference

See agent-selection.md for when to use each agent.

Common Mistakes

Spawning agents before reading context: Read any files the user mentions first.

Not waiting for all agents: Synthesize only after ALL agents complete.

Over-documenting simple answers: Not every question needs a saved research doc.

Sequential when parallel works: If tasks are independent, spawn them together.