---
name: codebase-documentation
description: Document codebase as-is through parallel sub-agent research and synthesis. Use when user asks to understand, explore, or document how code works without making changes.
allowed-tools: Bash(git rev-parse *) Bash(git branch *) Bash(date *) Bash(basename *) Bash(awk *) Read Write Agent
---

# Codebase Documentation

Conduct comprehensive research across the codebase by spawning parallel sub-agents and synthesizing their findings.

## Metadata

- Date: !`date '+%Y-%m-%d %H:%M:%S %Z'`
- Git commit: !`git rev-parse HEAD 2>/dev/null || echo "NO_HEAD"`
- Branch: !`git branch --show-current 2>/dev/null || echo "NO_BRANCH"`
- Repository root: !`git rev-parse --show-toplevel 2>/dev/null || echo "NO_REPO_ROOT"`
- Feature: !`awk -v k=feature_slug -v d=NO_FEATURE 'BEGIN{"git branch --show-current"|getline b;if(match(b,/[0-9]+/))f=".claude/task-context/"substr(b,RSTART,RLENGTH)".md";n=0;while(("ls .claude/task-context/ 2>/dev/null"|getline g)>0){n++;o=".claude/task-context/"g}if(f==""||(getline t<f)<0){close(f);f=(n==1)?o:".claude/task-context.md"}close(f);while((getline l<f)>0)if(l~"^"k":"){sub(/^[^:]*: */,"",l);print l;x=1}if(!x)print d}' 2>/dev/null || echo "NO_FEATURE"`

## Role boundary

You and the sub-agents document the codebase as it exists today — the research doc is a
technical map of the current system. Describe what exists, with no critiques,
recommendations, root-cause analysis, or proposed changes unless the user explicitly
asks, because the plan that consumes this doc must start from neutral inputs.

## Initial Setup

Start from the research question the invocation carries. When it carries none, ask for
the question or area of interest and wait for it.

## Steps

1. **Read any directly mentioned files first:**
   - If the user mentions specific files, `Read` them in full first (no `limit`/`offset`)
   - Read them yourself in the main context before spawning sub-agents, so the decomposition starts from full context

2. **Analyze and decompose the research question:**
   - Break down the user's query into composable research areas
   - Identify specific components, patterns, or concepts to investigate

3. **Spawn parallel sub-agents for comprehensive research:**

   Spawn ALL agents in a **single message** so they run in parallel.

   **Round 1 — Locators** (all in one message):

   | `subagent_type` | Job |
   |-----------------|-----|
   | `component-locator` | Find WHERE files and components live |
   | `pattern-scanner` | Find examples of existing patterns |

   **Round 2 — Analyzers** (after Round 1, only if findings warrant deeper analysis):

   | `subagent_type` | Job |
   |-----------------|-----|
   | `implementation-analyzer` | Understand HOW specific code works (on most promising files from Round 1) |

4. **Wait for all sub-agents to complete and synthesize findings:**
   - Compile all sub-agent results
   - Connect findings across different components
   - Include specific file paths and line numbers
   - Answer the user's specific questions with concrete evidence

5. **Generate research document:**

   Persist to `{feature_dir}/research.md` — see `../../reference/tracker.md`:

   A committed file — `Write` to `docs/features/{slug}/research.md` (feature) or `docs/research/{topic}.md` (standalone). Commit it on the branch.

   Inside a flow feature (`Feature` ≠ `NO_FEATURE`), edit `.claude/task-context/{item}.md`: `phase: research`, `last_updated: {today}`. Standalone, skip the phase update.

   **Document structure:**

   ```markdown
   # Research: [User's Question/Topic]

   **Date**: [Current date and time]
   **Git Commit**: [Current commit hash]
   **Branch**: [Current branch name]

   ## Research Question

   [Original user query]

   ## Summary

   [High-level documentation of what was found]

   ## Detailed Findings

   ### [Component/Area 1]

   - Description of what exists (file.ext:line)
   - How it connects to other components

   ## Code References

   - `path/to/file.py:123` - Description
   - `another/file.ts:45-67` - Description

   ## Open Questions

   [Any areas that need further investigation]
   ```

6. **Present findings:**
   - Concise summary to the user
   - Include key file references
   - Mention the research doc was saved
   - Ask if they have follow-up questions

## Important notes

- Always run fresh codebase research
- Focus on finding concrete file paths and line numbers
- Research documents should be self-contained

## Gotchas

_Add a line each time Claude trips on something._

- Always `Read` mentioned files in full (no `limit`/`offset`) before spawning agents — partial reads lead to missed context.
- Round 2 agents are optional — don't always spawn both rounds.