Research Codebase

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

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.

Steps to follow after receiving the research query:

1. Read any directly mentioned files first:
   • If the user mentions specific files or docs, 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 think deeply about the underlying patterns, connections, and architectural implications the user might be seeking
   • Identify specific components, patterns, or concepts to investigate
   • If you have a todo list, use it to track progress
   • Consider which directories, files, or architectural patterns are relevant
3. Spawn parallel sub-agents to identify relevant files and map the landscape:
   • Create multiple Task agents to search for files and identify what's relevant
   • Each sub-agent should focus on locating files and reporting back paths and brief summaries — NOT on deeply analyzing code
   • The key is to use these agents for discovery:
     • Search for files related to each research area
     • Identify entry points, key types, and important functions
     • Report back file paths, line numbers, and short descriptions of what each file contains
     • Run multiple agents in parallel when they're searching for different things
     • Remind agents they are documenting, not evaluating or improving
   • If the user explicitly asks for web research, spawn additional agents with WebSearch/WebFetch tools and instruct them to return links with their findings
4. Read the most relevant files yourself in the main context:
   • After sub-agents report back, identify the most important files for answering the research question
   • Read these files yourself using the Read tool — you need them in your own context to write an accurate, detailed research document
   • Do NOT rely solely on sub-agent summaries for the core findings — sub-agent summaries may miss nuances, connections, or important details
   • Prioritize files that are central to the research question; skip peripheral files that sub-agents already summarized adequately
   • This is the step where you build deep understanding — the previous step was just finding what to read
5. Synthesize findings into a complete picture:
   • Combine your own reading with sub-agent discoveries
   • 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
6. Gather metadata for the research document:
   • Run

     python3 <skill_directory>/scripts/metadata.py

     to get date, commit, branch, and repository info
   • Determine the output filename:

     docs/agents/research/YYYY-MM-DD-description.md

     • YYYY-MM-DD is today's date
     • description is a brief kebab-case description of the research topic
     • Example:

       2025-01-08-authentication-flow.md

     • The output folder (

       docs/agents/research/

       ) can be overridden by instructions in the project's

       AGENTS.md

       or

       CLAUDE.md

7. Generate research document:
   • Use the metadata gathered in step 5
   • Ensure the

     docs/agents/research/

     directory exists (create if needed)
   • Structure the document with YAML frontmatter followed by content:
     markdown

     ---
     date: [ISO date/time from metadata]
     git_commit: [Current commit hash from metadata]
     branch: [Current branch name from metadata]
     topic: "[User's Question/Topic]"
     tags: [research, codebase, relevant-component-names]
     status: complete
     ---
     
     # Research: [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)
     - 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]

8. Present findings to the user:
   • Present a concise summary of findings
   • 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
   • Add a new section:

     ## Follow-up Research [timestamp]

   • Spawn new sub-agents as needed for additional investigation
   • Continue updating the document

Important notes:

• Use parallel sub-agents for file discovery and landscape mapping, but read the most important files yourself in the main context
• Sub-agents are scouts that find relevant files — the main agent must read key files to build deep understanding
• Do NOT rely solely on sub-agent summaries for your core findings; they may miss nuances and connections
• 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 locating files and reporting back paths
• Document cross-component connections and how systems interact
• 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 read key files yourself after sub-agents report back (step 4)
  • ALWAYS wait for your own reading to complete before synthesizing (step 5)
  • ALWAYS gather metadata before writing the document (step 6 before step 7)
  • NEVER write the research document with placeholder values