Plan Research
The Planner drives this workflow. Investigate a problem space by gathering evidence from the codebase, documentation, and external sources. Produce a structured research summary with cited sources.
Phase 1: Scope the Investigation
Define the boundaries before researching.
Steps
- State the research question clearly
- Identify what you need to learn and why
- Define what is in-scope and out-of-scope
- List known starting points (files, docs, APIs, prior ADRs)
Output
Produce a scoped research brief covering: research question, in/out scope, starting points.
Approval Required: No
Phase 2: Gather Evidence
Collect evidence from internal and external sources.
Internal Sources
- Search the codebase for relevant patterns, implementations, and conventions
- Read existing ADRs, architecture docs, and design notes
- Review git history for context on past decisions
- Quantify where possible (line counts, file counts, dependency counts)
External Sources
- Use
WebFetch to read official documentation, changelogs, or specifications
- Use
mcp__github__search_repositories to explore prior art in open source
- Do NOT rely solely on training knowledge for version-specific behavior, API signatures, or configuration options — verify against the source
- Cite every external source with a URL or repository reference
Evidence Standards
- Every claim must link to a specific file, line, URL, or commit
- Distinguish verified facts from inferences
- Note contradictions between sources
- Record what you searched for and didn't find (negative evidence)
Output
Produce a findings report covering: topic-by-topic findings with sources, negative evidence.
Approval Required: No
Phase 3: Synthesize
Combine findings into a structured research summary.
Steps
- Combine findings into a coherent picture
- Identify patterns, gaps, and contradictions
- State implications for the original research question
- List open questions that remain unanswered
Output
Produce a research summary covering: synthesis narrative, key insights (numbered), open questions, sources table (source | type | key finding).
⛔ CHECKPOINT
STOP. Do not proceed until human confirms the research summary is accurate and sufficient.
Approval Required: Yes
Error Handling
| Error |
Recovery |
| Research question too broad |
Narrow scope, break into sub-questions |
| External source unavailable |
Note the gap, try alternative sources |
| Contradictory evidence |
Document both sides, flag for human judgment |
| Insufficient evidence |
State what's missing, recommend additional investigation |
1---2name: plan-research-23description: Research a problem space with evidence gathering and source validation.4---5
6# Plan Research
7
8The Planner drives this workflow. Investigate a problem space by gathering evidence from the codebase, documentation, and external sources. Produce a structured research summary with cited sources.
9
10---
11
12## Phase 1: Scope the Investigation
13
14Define the boundaries before researching.
15
16### Steps
17
181. State the research question clearly
192. Identify what you need to learn and why
203. Define what is in-scope and out-of-scope
214. List known starting points (files, docs, APIs, prior ADRs)
22
23### Output
24
25Produce a scoped research brief covering: research question, in/out scope, starting points.
26
27**Approval Required:** No
28
29---
30
31## Phase 2: Gather Evidence
32
33Collect evidence from internal and external sources.
34
35### Internal Sources
36
371. Search the codebase for relevant patterns, implementations, and conventions
382. Read existing ADRs, architecture docs, and design notes
393. Review git history for context on past decisions
404. Quantify where possible (line counts, file counts, dependency counts)
41
42### External Sources
43
441. Use `WebFetch` to read official documentation, changelogs, or specifications
452. Use `mcp__github__search_repositories` to explore prior art in open source
463. Do NOT rely solely on training knowledge for version-specific behavior, API signatures, or configuration options — verify against the source
474. Cite every external source with a URL or repository reference
48
49### Evidence Standards
50
51- Every claim must link to a specific file, line, URL, or commit
52- Distinguish verified facts from inferences
53- Note contradictions between sources
54- Record what you searched for and didn't find (negative evidence)
55
56### Output
57
58Produce a findings report covering: topic-by-topic findings with sources, negative evidence.
59
60**Approval Required:** No
61
62---
63
64## Phase 3: Synthesize
65
66Combine findings into a structured research summary.
67
68### Steps
69
701. Combine findings into a coherent picture
712. Identify patterns, gaps, and contradictions
723. State implications for the original research question
734. List open questions that remain unanswered
74
75### Output
76
77Produce a research summary covering: synthesis narrative, key insights (numbered), open questions, sources table (source | type | key finding).
78
79### ⛔ CHECKPOINT
80
81**STOP.** Do not proceed until human confirms the research summary is accurate and sufficient.
82
83**Approval Required:** Yes
84
85---
86
87## Error Handling
88
89| Error | Recovery |
90| --------------------------- | -------------------------------------------------------- |
91| Research question too broad | Narrow scope, break into sub-questions |
92| External source unavailable | Note the gap, try alternative sources |
93| Contradictory evidence | Document both sides, flag for human judgment |
94| Insufficient evidence | State what's missing, recommend additional investigation |
majiayu000