1# Research Codebase
2
3You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
4
5## Initial Setup:
6
7When this command is invoked, respond with:
8
9```
10I'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.
11```
12
13Then wait for the user's research query.
14
15## Steps to follow after receiving the research query:
16
171. **Read any directly mentioned files first:**
18 - If the user mentions specific files (tickets, docs, JSON), read them FULLY first
19 - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
20 - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
21 - This ensures you have full context before decomposing the research
22
232. **Analyze and decompose the research question:**
24 - Break down the user's query into composable research areas
25 - Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
26 - Identify specific components, patterns, or concepts to investigate
27 - Create a research plan using TodoWrite to track all subtasks
28 - Consider which directories, files, or architectural patterns are relevant
29
303. **Spawn parallel sub-agent tasks for comprehensive research:**
31 - Create multiple Task agents to research different aspects concurrently
32 - We now have specialized agents that know how to do specific research tasks:
33
34 **For codebase research:**
35 - Use the **codebase-locator** agent to find WHERE files and components live
36 - Use the **codebase-analyzer** agent to understand HOW specific code works
37 - Use the **codebase-pattern-finder** agent if you need examples of similar implementations
38
39 **For thoughts directory:**
40 - Use the **thoughts-locator** agent to discover what documents exist about the topic
41 - Use the **thoughts-analyzer** agent to extract key insights from specific documents (only the most relevant ones)
42
43 **For web research (only if user explicitly asks):**
44 - Use the **web-search-researcher** agent for external documentation and resources
45 - IF you use web-research agents, instruct them to return LINKS with their findings, and please INCLUDE those links in your final report
46
47 **For Linear tickets (if relevant):**
48 - Use the **linear-ticket-reader** agent to get full details of a specific ticket
49 - Use the **linear-searcher** agent to find related tickets or historical context
50
51 The key is to use these agents intelligently:
52 - Start with locator agents to find what exists
53 - Then use analyzer agents on the most promising findings
54 - Run multiple agents in parallel when they're searching for different things
55 - Each agent knows its job - just tell it what you're looking for
56 - Don't write detailed prompts about HOW to search - the agents already know
57
584. **Wait for all sub-agents to complete and synthesize findings:**
59 - IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
60 - Compile all sub-agent results (both codebase and thoughts findings)
61 - Prioritize live codebase findings as primary source of truth
62 - Use thoughts/ findings as supplementary historical context
63 - Connect findings across different components
64 - Include specific file paths and line numbers for reference
65 - Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files)
66 - Highlight patterns, connections, and architectural decisions
67 - Answer the user's specific questions with concrete evidence
68
695. **Gather metadata for the research document:**
70 - Run the `hack/spec_metadata.sh` script to generate all relevant metadata
71 - Filename: `thoughts/shared/research/YYYY-MM-DD_HH-MM-SS_topic.md`
72
736. **Generate research document:**
74 - Use the metadata gathered in step 4
75 - Structure the document with YAML frontmatter followed by content:
76
77 ```markdown
78 ---
79 date: [Current date and time with timezone in ISO format]
80 researcher: [Researcher name from thoughts status]
81 git_commit: [Current commit hash]
82 branch: [Current branch name]
83 repository: [Repository name]
84 topic: "[User's Question/Topic]"
85 tags: [research, codebase, relevant-component-names]
86 status: complete
87 last_updated: [Current date in YYYY-MM-DD format]
88 last_updated_by: [Researcher name]
89 ---
90
91 # Research: [User's Question/Topic]
92
93 **Date**: [Current date and time with timezone from step 4]
94 **Researcher**: [Researcher name from thoughts status]
95 **Git Commit**: [Current commit hash from step 4]
96 **Branch**: [Current branch name from step 4]
97 **Repository**: [Repository name]
98
99 ## Research Question
100
101 [Original user query]
102
103 ## Summary
104
105 [High-level findings answering the user's question]
106
107 ## Detailed Findings
108
109 ### [Component/Area 1]
110
111 - Finding with reference ([file.ext:line](link))
112 - Connection to other components
113 - Implementation details
114
115 ### [Component/Area 2]
116
117 ...
118
119 ## Code References
120
121 - `path/to/file.py:123` - Description of what's there
122 - `another/file.ts:45-67` - Description of the code block
123
124 ## Architecture Insights
125
126 [Patterns, conventions, and design decisions discovered]
127
128 ## Historical Context (from thoughts/)
129
130 [Relevant insights from thoughts/ directory with references]
131
132 - `thoughts/shared/something.md` - Historical decision about X
133 - `thoughts/local/notes.md` - Past exploration of Y
134 Note: Paths exclude "searchable/" even if found there
135
136 ## Related Research
137
138 [Links to other research documents in thoughts/shared/research/]
139
140 ## Open Questions
141
142 [Any areas that need further investigation]
143 ```
144
1457. **Add GitHub permalinks (if applicable):**
146 - Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
147 - If on main/master or pushed, generate GitHub permalinks:
148 - Get repo info: `gh repo view --json owner,name`
149 - Create permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
150 - Replace local file references with permalinks in the document
151
1528. **Sync and present findings:**
153 - Run `humanlayer thoughts sync` to sync the thoughts directory
154 - Present a concise summary of findings to the user
155 - Include key file references for easy navigation
156 - Ask if they have follow-up questions or need clarification
157
1589. **Handle follow-up questions:**
159 - If the user has follow-up questions, append to the same research document
160 - Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update
161 - Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter
162 - Add a new section: `## Follow-up Research [timestamp]`
163 - Spawn new sub-agents as needed for additional investigation
164 - Continue updating the document and syncing
165
166## Important notes:
167
168- Always use parallel Task agents to maximize efficiency and minimize context usage
169- Always run fresh codebase research - never rely solely on existing research documents
170- The thoughts/ directory provides historical context to supplement live findings
171- Focus on finding concrete file paths and line numbers for developer reference
172- Research documents should be self-contained with all necessary context
173- Each sub-agent prompt should be specific and focused on read-only operations
174- Consider cross-component connections and architectural patterns
175- Include temporal context (when the research was conducted)
176- Link to GitHub when possible for permanent references
177- Keep the main agent focused on synthesis, not deep file reading
178- Encourage sub-agents to find examples and usage patterns, not just definitions
179- Explore all of thoughts/ directory, not just research subdirectory
180- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
181- **Critical ordering**: Follow the numbered steps exactly
182 - ALWAYS read mentioned files first before spawning sub-tasks (step 1)
183 - ALWAYS wait for all sub-agents to complete before synthesizing (step 4)
184 - ALWAYS gather metadata before writing the document (step 5 before step 6)
185 - NEVER write the research document with placeholder values
186- **Path handling**: The thoughts/searchable/ directory contains hard links for searching
187 - Always document paths by removing ONLY "searchable/" - preserve all other subdirectories
188 - Examples of correct transformations:
189 - `thoughts/searchable/allison/old_stuff/notes.md` → `thoughts/allison/old_stuff/notes.md`
190 - `thoughts/searchable/shared/prs/123.md` → `thoughts/shared/prs/123.md`
191 - `thoughts/searchable/global/shared/templates.md` → `thoughts/global/shared/templates.md`
192 - NEVER change allison/ to shared/ or vice versa - preserve the exact directory structure
193 - This ensures paths are correct for editing and navigation
194- **Frontmatter consistency**:
195 - Always include frontmatter at the beginning of research documents
196 - Keep frontmatter fields consistent across all research documents
197 - Update frontmatter when adding follow-up research
198 - Use snake_case for multi-word field names (e.g., `last_updated`, `git_commit`)
199 - Tags should be relevant to the research topic and components studied