# Research Codebase

> Document the codebase as-is via parallel read-only sub-agents and write findings under flow/research/. Explicit workflow command; run only when invoked via /research-codebase or explicitly asked.

- Skill: `corticalstack/research-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add corticalstack/research-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/corticalstack/research-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: corticalstack (https://skillmd.com/u/corticalstack)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/corticalstack/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 command 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 research query is a tracker URL or work-item id:
     - Fetch work-item content: `tracker view <id> --json title,body,state,comments`
     - Transition state: `tracker set-state <id> research-in-progress`
   - If the user mentions specific files (tickets, docs, JSON), read them FULLY first
   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
   - **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 research question:**
   - Break down the user's query into composable research areas
   - Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
   - Identify specific components, patterns, or concepts to investigate
   - Create a research plan using TodoWrite 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
   - We now have specialized agents that know how to do specific research tasks:

   **For codebase research:**
   - Use the **codebase-locator** agent to find WHERE files and components live
   - Use the **codebase-analyzer** agent to understand HOW specific code works (without critiquing it)
   - Use the **codebase-pattern-finder** agent to find examples of existing patterns (without evaluating them)

   **IMPORTANT**: All agents are documentarians, not critics. They will describe what exists without suggesting improvements or identifying issues.

   **For flow directory:**
   - Use the **flow-locator** agent to discover what documents exist about the topic
   - Use the **flow-analyzer** agent to extract key insights from specific documents (only the most relevant ones)

   **For web research (only if user explicitly asks):**
   - Use the **web-search-researcher** agent for external documentation and resources
   - IF you use web-research agents, instruct them to return LINKS with their findings, and please INCLUDE those links in your final report

   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 to document how they work
   - 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

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 flow findings)
   - Prioritize live codebase findings as primary source of truth
   - Use flow/ findings as supplementary historical context
   - Connect findings across different components
   - Include specific file paths and line numbers for reference
   - Verify all flow/ paths are correct
   - Highlight patterns, connections, and architectural decisions
   - Answer the user's specific questions with concrete evidence

5. **Gather metadata for the research document:**
   - Gather metadata using git commands:
     - `git rev-parse HEAD` for commit hash
     - `git branch --show-current` for branch name
     - `git remote get-url origin` for repository
   - Filename: `flow/research/YYYY-MM-DD-gh-<number>-description.md`
     - Format: `YYYY-MM-DD-gh-<number>-description.md` where:
       - YYYY-MM-DD is today's date
       - gh-<number> is the tracker work-item id (omit if no work item; the literal "gh-" prefix is a stable filename convention)
       - description is a brief kebab-case description of the research topic
     - Examples:
       - With issue: `flow/research/2025-01-08-gh-42-parent-child-tracking.md`
       - Without issue: `flow/research/2025-01-08-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]
     researcher: [Researcher name or "Claude"]
     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
     last_updated: [Current date in YYYY-MM-DD format]
     last_updated_by: [Researcher name]
     ---

     # Research: [User's Question/Topic]

     **Date**: [Current date and time with timezone from step 4]
     **Researcher**: [Researcher name or "Claude"]
     **Git Commit**: [Current commit hash from step 4]
     **Branch**: [Current branch name from step 4]
     **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](https://github.com/{owner}/{repo}/blob/{commit}/file.ext#L{line}))
     - How it connects to other components
     - Current implementation details (without evaluation)

     ### [Component/Area 2]
     ...

     ## Code References
     - [path/to/file.py:123](https://github.com/{owner}/{repo}/blob/{commit}/path/to/file.py#L123) - Description of what's there
     - [another/file.ts:45-67](https://github.com/{owner}/{repo}/blob/{commit}/another/file.ts#L45-L67) - Description of the code block

     ## Architecture Documentation
     [Current patterns, conventions, and design implementations found in the codebase]

     ## Historical Context (from flow/)
     [Relevant insights from flow/ directory with references]
     - `flow/research/something.md` - Previous research about X
     - `flow/plans/feature.md` - Related implementation plan

     ## Related Research
     [Links to other research documents in flow/research/]

     ## Open Questions
     [Any areas that need further investigation]
     ```

7. **Add repository permalinks (if applicable; GitHub URL shape shown - substitute for other hosts):**
   - Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
   - For GitHub, get repo info: `tracker repo-info` and form permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
   - For other hosts, substitute the appropriate URL shape (e.g. Azure DevOps: `https://dev.azure.com/{org}/{project}/_git/{repo}?path=/{file}&version=GC{commit}&line={line}`)
   - **Every `path:line` reference in the document body MUST be its own clickable markdown link** - `[path:line](permalink)`, with ranges as `#L{start}-L{end}` - across Detailed Findings, the Code References section, and any tables. Do NOT leave bare `path:line` text, and do NOT just state a single "permalink base" at the top and leave the references plain; render each reference individually.
   - Use the full commit permalink when the commit is pushed; if the branch/commit is not pushed, fall back to a repo-relative link `[path:line](path)` so every reference stays navigable.

8. **Present findings:**
   - Transition the work-item state (if applicable): `tracker set-state <id> research-complete research-in-progress`
   - 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 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 flow/ 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 documentation operations
- Document cross-component connections and how systems interact
- Include temporal context (when the research was conducted)
- Link to the repository host when possible for permanent references
- Keep the main agent focused on synthesis, not deep file reading
- Have sub-agents document examples and usage patterns as they exist
- Explore all of flow/ directory, not just research subdirectory
- **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
- **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