# Research Codebase > Research codebase comprehensively using parallel sub-agents. Use when the user asks to "research the codebase", "understand how X works", or "investigate Y". Use when this capability is needed. - Skill: `tomevault-io/research-codebase` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/research-codebase` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/research-codebase/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/research-codebase --- # Research Codebase You are tasked with conducting comprehensive research across the codebase, spawning parallel sub-agents if necessary 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 explicitly asked for them - DO NOT propose future enhancements unless explicitly asked for them - 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 ## Steps to follow 1. **Read any directly mentioned files first:** - If the user mentions specific files, read them FULLY first - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks - This ensures you have full context before decomposing the research 2. **Analyze and decompose the goal of the research:** - Think deeply about the research goal and break it down into composable research areas - Take time to ultrathink about the underlying patterns, connections, and architectural implications. - Identify specific components, patterns, or concepts to investigate - Create a research plan using TodoWrite/write_todos to track all subtasks - Consider which directories, files, or architectural patterns are relevant 3. **Spawn parallel sub-agent tasks for comprehensive research:** - Create multiple Task agents to research different aspects concurrently The key is to use these agents intelligently: - 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 4. **Wait for all sub-agents to complete and synthesize findings:** - IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding - Compile all sub-agent results (both codebase and thoughts findings) - Prioritize live codebase findings as primary source of truth - Use dev/log/ as supplementary historical context - Connect findings across different components - Include specific file paths and line numbers for reference - Highlight patterns, connections, and architectural insights and decisions - Answer the user's specific questions with concrete evidence 5. **Gather metadata for the research document:** - Generate all relevant metadata - Filename: `dev/research/YYYYMMDD-description.md` - Format: `YYYYMMDD-description.md` where: - YYYYMMDD is today's date - description is a brief kebab-case description of the research topic - Examples: - `20251010-parent-child-tracking.md` - `20260114-authentication-flow.md` 6. **Generate research document:** - Use the metadata gathered in step 4 - Structure the document with YAML frontmatter followed by content: ```markdown --- date: [Current date and time with timezone in ISO format] topic: "[User's Question/Topic]" tags: [research, codebase, relevant-component-names] status: complete last_updated: [Current date in YYYY-MM-DD format] --- # Research: [User's Question/Topic] **Date**: [Current date and time with timezone from step 4] ## Research Question [Original query or research goal] ## Summary [High-level findings] ## Detailed Findings ### [Component/Area 1] - Finding with reference ([file.ext:line](link)) - Connection to other components - Implementation details ### [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 Insights [Patterns, conventions, and design decisions discovered] ## Historical Context (from dev/log/) [Relevant insights from dev/log/ directory with references] - `dev/log/something.md` - Historical decision about X - `dev/log/notes.md` - Past implementation of Y ## Related Research [Links to other research documents in dev/research/] ## Open Questions [Any areas that need further investigation] ``` 7. **Sync and 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 8. **Handle follow-up questions:** - If the user has follow-up questions, append to the same research document - Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update - Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter - Add a new section: `## Follow-up Research [timestamp]` - Spawn new sub-agents as needed for additional investigation - Continue updating the document and syncing ## Important notes: - Always use parallel Task agents to maximize efficiency and minimize context usage - Always run fresh codebase research - never rely solely on existing research documents - The dev/log/ directory provides historical context to supplement live findings - 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 operations - Consider cross-component connections and architectural patterns - Include temporal context (when the research was conducted) - Keep the main agent focused on synthesis, not deep file reading - Encourage sub-agents to find examples and usage patterns, not just definitions - Explore all of dev/ directory, not just research subdirectory - **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks - **Critical ordering**: Follow the numbered steps exactly - ALWAYS read mentioned files first before spawning sub-tasks (step 1) - ALWAYS wait for all sub-agents to complete before synthesizing (step 4) - ALWAYS gather metadata before writing the document (step 5 before step 6) - NEVER write the research document with placeholder values - **Frontmatter consistency**: - Always include frontmatter at the beginning of research documents - Keep frontmatter fields consistent across all research documents - Update frontmatter when adding follow-up research - Use snake_case for multi-word field names (e.g., `last_updated`, `git_commit`) - Tags should be relevant to the research topic and components studied --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ferueda) — claim your Tome and manage your conversions.