dotfiles/dot_claude/commands/research_codebase.md

description, model

description	model
Document codebase as-is	opus

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

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
   • 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 agents to research different aspects concurrently:
     • Use an agent to locate WHERE files and components live
     • Use an agent analyze and understand HOW specific code works (without critiquing it)
     • Use an agent to find examples of existing patterns (without evaluating them)
     • Use an agent for web research for external documentation and resources, but only if the user epplicitly asks for this. 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
   • 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 thoughts findings)
   • Prioritize live codebase findings as primary source of truth
   • Use thoughts and findings as supplementary historical context
   • Connect findings across different components
   • Include specific file paths and line numbers for reference
   • Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files)
   • Highlight patterns, connections, and architectural decisions
   • Answer the user's specific questions with concrete evidence

5. Generate research document:

   • Create a structured research document with your findings as markdown file.
   • Structure the document with YAML frontmatter followed by content:

     ---
     repository: [Repository name]
     branch: [Current branch name]
     git_commit: [Current commit hash]
     topic: "[User's Question/Topic]"
     last_updated: [Current date in YYYY-MM-DD format]
     ---
     
     # [User's Question/Topic]
     
     ## 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](link))
     - 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]
     
     ## Historical Context (from thoughts/)
     [Relevant insights from thoughts/ directory with references]
     - `thoughts/shared/something.md` - Historical decision about X
     - `thoughts/local/notes.md` - Past exploration of Y
     Note: Paths exclude "searchable/" even if found there
     
     ## Related Research
     [Links to other research documents in thoughts/shared/research/]
     
     ## Open Questions
     [Any areas that need further investigation]
     

6. 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

7. Handle follow-up questions:

   • If the user has follow-up questions, append to the same research document
   • Spawn new sub-agents as needed for additional investigation
   • Continue updating the document until no more follow up questions are asked

Important notes:

• Always use parallel Task agents to maximize efficiency and minimize context usage
• Always validate exsisting research documents during research. Don't rely on old documents
• Old research documents provide 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
• Keep the main agent focused on synthesis, not deep file reading
• Have sub-agents document examples and usage patterns as they exist
• Explore all existing research documents and documentation.
• 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