Research Codebase

Conduct comprehensive research across the codebase to answer user questions by spawning parallel agents and synthesizing their findings.

When This Skill Applies

• •Exploring existing implementations before making changes
• •Understanding architecture or system design
• •Answering "how does X work?" questions about the codebase
• •Documenting component interactions and data flows
• •Gathering historical context from docs directory
• •User asks to "research", "document", or "understand" something

Invocation

Command: /researching-codebase or /researching-codebase [topic]

Initial Response

When invoked:

1. •

   If a topic was provided: Begin decomposing the research question

2. •

   If no topic provided, respond with:

I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.

Critical Principle

Focus on documentation. Your primary job is to explain the codebase as it exists today.

• •Describe what exists, where it exists, how it works, and how components interact
• •You are creating a technical map/documentation of the existing system
• •Only suggest improvements or identify problems if explicitly asked

Decomposition Phase

Goal: Understand the research context and break down the question.

Step 1: Read Mentioned Files

If the user mentions specific files (tickets, docs, JSON):

• •Read them FULLY using the Read tool WITHOUT limit/offset parameters
• •CRITICAL: Read these files yourself in the main context before spawning any agents
• •This ensures you have full context before decomposing the research

Step 2: Analyze and Decompose

• •Break down the user's query into composable research areas
• •Identify specific components, patterns, or concepts to investigate
• •Consider which directories, files, or architectural patterns are relevant
• •Create a research plan using TodoWrite to track all subtasks

User Confirmation

Present your understanding of the research question and decomposition, then use AskUserQuestion to confirm:

• •Header: "Research plan"
• •Question: "Does this capture your research question correctly?"
• •Options:
  • •"Yes, proceed with research" → Continue to Research Phase
  • •"Adjust the scope" → Ask what to adjust, then re-confirm
  • •"Let me clarify" → Wait for clarification

Research Phase

Goal: Spawn specialized agents to gather information concurrently.

Specialized Agents

For codebase research:

• •codebase-navigator: Find WHERE files and components live
• •codebase-analyzer: Understand HOW specific code works (without critiquing it)
• •codebase-pattern-finder: Find examples of existing patterns (without evaluating them)

For docs directory:

• •docs-locator: Discover what documents exist about the topic
• •docs-analyzer: Extract key insights from specific documents (only the most relevant ones)

For web research (only if user explicitly asks):

• •web-search-researcher: External documentation and resources
• •IF you use web-research agents, instruct them to return LINKS with their findings, and INCLUDE those links in your final report

Agent Usage Guidelines

• •Start with locator agents to find what exists
• •Then use analyzer agents on the most promising findings
• •Run multiple agents in parallel when they're searching for different things
• •Each agent knows its job—just tell it what you're looking for
• •Don't write detailed prompts about HOW to search—the agents already know
• •Remind agents they are documenting, not evaluating or improving

Important

• •WAIT for ALL agent tasks to complete before proceeding to Synthesis Phase
• •All agents are documentarians, not critics—they describe what exists without suggesting improvements

Synthesis Phase

Goal: Compile findings and generate the research document.

Step 1: Synthesize Findings

• •Compile all agent results (both codebase and docs findings)
• •Prioritize live codebase findings as primary source of truth
• •Use docs directory findings as supplementary historical context
• •Connect findings across different components
• •Include specific file paths and line numbers for reference
• •Highlight patterns, connections, and architectural decisions
• •Answer the user's specific questions with concrete evidence

Step 2: Gather Metadata

For document path resolution and frontmatter, see the managing-claude-docs skill.

MUST run the git metadata command to generate all relevant metadata.

Filename format: $(claude-docs-path research)/YYYY-MM-DD-description.md

Examples:

• •2025-01-08-parent-child-tracking.md
• •2025-01-08-authentication-flow.md

Step 3: Generate Research Document

Infer the project name from the repository name via git metadata. If ambiguous, ask the user.

Generate the document using the template at templates/research-document.md.

Required sections:

• •YAML frontmatter (tags, Area, Created, Modified, Project)
• •Header metadata block (Date, Git Commit, Branch, Repository, Topic, Tags, Status)
• •Research Question, Summary, Detailed Findings
• •Code References with file:line format
• •Architecture Documentation, Historical Context, Related Research
• •Open Questions for areas needing follow-up

Step 4: Add GitHub Permalinks (if applicable)

• •Check if on main branch or if commit is pushed: git branch --show-current and git status
• •If on main/master or pushed, generate GitHub permalinks:
  • •Get repo info: gh repo view --json owner,name
  • •Create permalinks: https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}
• •Replace local file references with permalinks in the document

User Review

Present a summary of the document, then use AskUserQuestion:

• •Header: "Document review"
• •Question: "Here's the research document. Does it address your question?"
• •Options:
  • •"Yes, looks good" → Continue to Follow-up Phase
  • •"Add more detail on [area]" → Expand that section
  • •"I have follow-up questions" → Address them and update document

Follow-up Phase

Goal: Present findings and handle additional questions.

Present Findings

• •Present a concise summary of findings to the user
• •Include key file references for easy navigation
• •Ask if they have follow-up questions or need clarification

Handle Follow-up Questions

If the user has follow-up questions:

• •Append to the same research document
• •Update the heading fields Last Updated to reflect the update
• •Add Last Updated Note: "Added follow-up research for [brief description]" to headings
• •Add a new section: ## Follow-up Research [timestamp]
• •Spawn new agents as needed for additional investigation
• •Continue updating the document

Next Action

Use AskUserQuestion for next action:

• •Header: "Next step"
• •Question: "Research is complete. What would you like to do?"
• •Options:
  • •"Follow-up question" → Handle follow-up and update document
  • •"Start related research" → Begin new research with shared context
  • •"Done" → End workflow

Anti-Patterns

Suggesting Improvements

❌ "The authentication flow could be simplified by..."
❌ "This would benefit from refactoring..."

✅ "The authentication flow works by first checking..."
✅ "This module handles X by doing Y..."

Critiquing Implementation

❌ "This is a problematic pattern because..."
❌ "The code has issues with..."

✅ "The current implementation uses this pattern..."
✅ "The code handles this case by..."

Missing Concrete References

❌ "The system handles authentication somewhere in the codebase"

✅ "Authentication is handled in `src/auth/handler.ts:45-89`"

Skipping Agent Completion

❌ Synthesizing findings before all agents return

✅ ALWAYS wait for ALL agents to complete before synthesizing

Placeholder Values

❌ Writing document with "[TBD]" or placeholder metadata

✅ ALWAYS gather metadata before writing the document

Troubleshooting

git metadata fails:

• •Verify you're in a git repository: git rev-parse --git-dir
• •Check if the command exists: which git-metadata or check aliases
• •Fall back to manual: git log -1 --format="%H" for commit hash

claude-docs-path returns nothing:

• •Check if CLAUDE_DOCS_ROOT is set: echo $CLAUDE_DOCS_ROOT
• •Fall back to .claude/docs/research/ in project root

Agent returns empty results:

• •Verify the search terms match what's in the codebase
• •Try broader search terms with a different agent
• •Check if the component exists at all using codebase-navigator

Research scope too broad:

• •Narrow to specific components or files
• •Break into multiple focused research sessions
• •Ask user to prioritize which aspect to investigate first

Example Session

User: /researching-codebase How does user authentication work in this app?

Decomposition Phase output:

I'll research the authentication flow by investigating:
1. Entry points (login routes, middleware)
2. Token/session management
3. User validation logic
4. Protected route enforcement

Spawning agents:
- codebase-navigator: "authentication login routes middleware"
- codebase-analyzer: "src/auth/" (after locator finds it)

Synthesized finding excerpt:

## Authentication Flow

### Entry Point
Login requests hit `src/routes/auth.ts:23-45`, which validates
credentials against the User model.

### Session Management
Sessions are stored in Redis via `src/lib/session.ts:12`. The
`createSession()` function generates a JWT with 24h expiry.

### Protected Routes
The `requireAuth` middleware (`src/middleware/auth.ts:8-34`)
checks the Authorization header and validates the JWT signature.

Agent Selection

Critical rules:

1. •Read mentioned files before spawning agents
2. •Wait for ALL agents to complete before synthesizing
3. •Gather metadata before writing the document
4. •Never use placeholder values

Integration with Other Skills

Before Implementation

Research feeds into /plan or implementation workflows:

• •Research documents WHAT exists
• •Plan documents HOW to change it

With Thinking Patterns

For complex research:

• •atomic-thought → Decompose research question into parts
• •graph-of-thoughts → Synthesize findings from multiple agents
• •chain-of-thought → Trace execution paths through code

Documentation Lifecycle

Research documents live in $(claude-docs-path research)/ and provide:

• •Historical context for future research
• •Starting point for implementation planning
• •Reference for understanding past decisions