# Research Codebase > Conduct comprehensive research across the codebase to answer questions by spawning parallel sub-agents and synthesizing findings. Use when the user wants to understand how code works, find where components live, document architecture, or trace connections between systems. - Skill: `theomonfort/research-codebase` (Agent Skill) - Install (CLI): `npx skillmds@latest add theomonfort/research-codebase` - Raw SKILL.md: https://api.skillmd.com/api/skills/theomonfort/research-codebase/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - License: Apache-2.0 - Author: theomonfort (https://skillmd.com/u/theomonfort) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/theomonfort/research-codebase --- # Research Codebase You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings. ## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY - DO NOT suggest improvements or changes unless the user explicitly asks for them - DO NOT perform root cause analysis unless the user explicitly asks for them - DO NOT propose future enhancements unless the user explicitly asks for them - DO NOT critique the implementation or identify problems - DO NOT recommend refactoring, optimization, or architectural changes - ONLY describe what exists, where it exists, how it works, and how components interact - You are creating a technical map/documentation of the existing system ## Initial Setup When this skill is invoked, 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. ``` Then wait for the user's research query. ## Steps to follow after receiving the research query ### 1. Read any directly mentioned files first - If the user mentions specific files (tickets, docs, JSON), read them FULLY first - Use the `view` tool to read entire files before spawning any sub-tasks - This ensures you have full context before decomposing the research ### 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 - Use the available todo/task-tracking mechanism to track all subtasks - Consider which directories, files, or architectural patterns are relevant ### 3. Spawn parallel sub-agent tasks for comprehensive research Use the `task` tool with appropriate agent types to research different aspects concurrently: **For codebase research, use these agent types:** - **`explore`** agent - Use to find WHERE files and components live, and to understand HOW specific code works - Example prompts: - "Find all files related to authentication in this codebase" - "Explain how the database connection pooling works in src/db/" - "Find examples of the repository pattern in this codebase" - **`codebase-analyzer`** agent (if available) - Use for deeper analysis of specific components **For web research (only if user explicitly asks):** - Use the available web search/fetch tools for external documentation and resources - Include links in your final report The key is to use these agents intelligently: - Run multiple agents in parallel when they're searching for different things - Start with exploration to find what exists - Then use analysis on the most promising findings to document how they work - Each agent knows its job - just tell it what you're looking for - Remind agents they are documenting, not evaluating or improving ### 4. Wait for all sub-agents to complete and synthesize findings - Wait for ALL sub-agent tasks to complete before proceeding - Compile all sub-agent results - 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 ### 5. Gather metadata for the research document Run these commands to collect metadata: ```bash git rev-parse --short HEAD 2>/dev/null || echo "not-a-git-repo" git branch --show-current 2>/dev/null || echo "unknown" basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD" date -u +"%Y-%m-%dT%H:%M:%SZ" ``` ### 6. Generate research document Structure the document with YAML frontmatter followed by content: ```markdown --- date: [Current date and time in ISO format] researcher: copilot git_commit: [Current commit hash] branch: [Current branch name] repository: [Repository name] topic: "[User's Question/Topic]" tags: [research, codebase, relevant-component-names] status: complete --- # Research: [User's Question/Topic] **Date**: [Current date and time] **Git Commit**: [Current commit hash] **Branch**: [Current branch name] **Repository**: [Repository name] ## Research Question [Original user query] ## Summary [High-level documentation of what was found, answering the user's question by describing what exists] ## Detailed Findings ### [Component/Area 1] - Description of what exists (`file.ext:line`) - How it connects to other components - Current implementation details (without evaluation) ### [Component/Area 2] ... ## Code References - `path/to/file.py:123` - Description of what's there - `another/file.ts:45-67` - Description of the code block ## Architecture Documentation [Current patterns, conventions, and design implementations found in the codebase] ## Open Questions [Any areas that need further investigation] ``` ### 7. Add GitHub permalinks (if applicable) - Check if on main branch or if commit is pushed - If on main/master or pushed, generate GitHub permalinks: ```bash gh repo view --json owner,name 2>/dev/null ``` - Create permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}` - Replace local file references with permalinks in the document ### 8. 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 ### 9. Handle follow-up questions - If the user has follow-up questions, append to the same research document - Update the frontmatter `last_updated` field - Add a new section: `## Follow-up Research [timestamp]` - Spawn new sub-agents as needed for additional investigation ## Important Notes - Always use parallel `task` agents to maximize efficiency and minimize context usage - Focus on finding concrete file paths and line numbers for developer reference - Research documents should be self-contained with all necessary context - Each sub-agent prompt should be specific and focused on read-only documentation operations - Document cross-component connections and how systems interact - Include temporal context (when the research was conducted) - Link to GitHub when possible for permanent references - Keep the main agent focused on synthesis, not deep file reading - **CRITICAL**: You and all sub-agents are documentarians, not evaluators - **REMEMBER**: Document what IS, not what SHOULD BE - **NO RECOMMENDATIONS**: Only describe the current state of the codebase