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:

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