275 lines
6.8 KiB
Markdown
275 lines
6.8 KiB
Markdown
# Research Prompt Template
|
|
|
|
For phases requiring research before planning:
|
|
|
|
```markdown
|
|
---
|
|
phase: XX-name
|
|
type: research
|
|
topic: [research-topic]
|
|
---
|
|
|
|
<session_initialization>
|
|
Before beginning research, verify today's date:
|
|
!`date +%Y-%m-%d`
|
|
|
|
Use this date when searching for "current" or "latest" information.
|
|
Example: If today is 2025-11-22, search for "2025" not "2024".
|
|
</session_initialization>
|
|
|
|
<research_objective>
|
|
Research [topic] to inform [phase name] implementation.
|
|
|
|
Purpose: [What decision/implementation this enables]
|
|
Scope: [Boundaries]
|
|
Output: FINDINGS.md with structured recommendations
|
|
</research_objective>
|
|
|
|
<research_scope>
|
|
<include>
|
|
- [Question to answer]
|
|
- [Area to investigate]
|
|
- [Specific comparison if needed]
|
|
</include>
|
|
|
|
<exclude>
|
|
- [Out of scope for this research]
|
|
- [Defer to implementation phase]
|
|
</exclude>
|
|
|
|
<sources>
|
|
Official documentation (with exact URLs when known):
|
|
- https://example.com/official-docs
|
|
- https://example.com/api-reference
|
|
|
|
Search queries for WebSearch:
|
|
- "[topic] best practices {current_year}"
|
|
- "[topic] latest version"
|
|
|
|
Context7 MCP for library docs
|
|
Prefer current/recent sources (check date above)
|
|
</sources>
|
|
</research_scope>
|
|
|
|
<verification_checklist>
|
|
{If researching configuration/architecture with known components:}
|
|
□ Enumerate ALL known options/scopes (list them explicitly):
|
|
□ Option/Scope 1: [description]
|
|
□ Option/Scope 2: [description]
|
|
□ Option/Scope 3: [description]
|
|
□ Document exact file locations/URLs for each option
|
|
□ Verify precedence/hierarchy rules if applicable
|
|
□ Check for recent updates or changes to documentation
|
|
|
|
{For all research:}
|
|
□ Verify negative claims ("X is not possible") with official docs
|
|
□ Confirm all primary claims have authoritative sources
|
|
□ Check both current docs AND recent updates/changelogs
|
|
□ Test multiple search queries to avoid missing information
|
|
□ Check for environment/tool-specific variations
|
|
</verification_checklist>
|
|
|
|
<research_quality_assurance>
|
|
Before completing research, perform these checks:
|
|
|
|
<completeness_check>
|
|
- [ ] All enumerated options/components documented with evidence
|
|
- [ ] Official documentation cited for critical claims
|
|
- [ ] Contradictory information resolved or flagged
|
|
</completeness_check>
|
|
|
|
<blind_spots_review>
|
|
Ask yourself: "What might I have missed?"
|
|
- [ ] Are there configuration/implementation options I didn't investigate?
|
|
- [ ] Did I check for multiple environments/contexts?
|
|
- [ ] Did I verify claims that seem definitive ("cannot", "only", "must")?
|
|
- [ ] Did I look for recent changes or updates to documentation?
|
|
</blind_spots_review>
|
|
|
|
<critical_claims_audit>
|
|
For any statement like "X is not possible" or "Y is the only way":
|
|
- [ ] Is this verified by official documentation?
|
|
- [ ] Have I checked for recent updates that might change this?
|
|
- [ ] Are there alternative approaches I haven't considered?
|
|
</critical_claims_audit>
|
|
</research_quality_assurance>
|
|
|
|
<incremental_output>
|
|
**CRITICAL: Write findings incrementally to prevent token limit failures**
|
|
|
|
Instead of generating full FINDINGS.md at the end:
|
|
1. Create FINDINGS.md with structure skeleton
|
|
2. Write each finding as you discover it (append immediately)
|
|
3. Add code examples as found (append immediately)
|
|
4. Finalize summary and metadata at end
|
|
|
|
This ensures zero lost work if token limits are hit.
|
|
|
|
<workflow>
|
|
Step 1 - Initialize:
|
|
```bash
|
|
# Create skeleton file
|
|
cat > .planning/phases/XX-name/FINDINGS.md <<'EOF'
|
|
# [Topic] Research Findings
|
|
|
|
## Summary
|
|
[Will complete at end]
|
|
|
|
## Recommendations
|
|
[Will complete at end]
|
|
|
|
## Key Findings
|
|
[Append findings here as discovered]
|
|
|
|
## Code Examples
|
|
[Append examples here as found]
|
|
|
|
## Metadata
|
|
[Will complete at end]
|
|
EOF
|
|
```
|
|
|
|
Step 2 - Append findings as discovered:
|
|
After researching each aspect, immediately append to Key Findings section
|
|
|
|
Step 3 - Finalize at end:
|
|
Complete Summary, Recommendations, and Metadata sections
|
|
</workflow>
|
|
</incremental_output>
|
|
|
|
<output_structure>
|
|
Create `.planning/phases/XX-name/FINDINGS.md`:
|
|
|
|
# [Topic] Research Findings
|
|
|
|
## Summary
|
|
[2-3 paragraph executive summary]
|
|
|
|
## Recommendations
|
|
|
|
### Primary Recommendation
|
|
[What to do and why]
|
|
|
|
### Alternatives Considered
|
|
[What else was evaluated]
|
|
|
|
## Key Findings
|
|
|
|
### [Category 1]
|
|
- Finding with source URL
|
|
- Relevance to our case
|
|
|
|
### [Category 2]
|
|
- Finding with source URL
|
|
- Relevance
|
|
|
|
## Code Examples
|
|
[Relevant patterns, if applicable]
|
|
|
|
## Metadata
|
|
|
|
<metadata>
|
|
<confidence level="high|medium|low">
|
|
[Why this confidence level]
|
|
</confidence>
|
|
|
|
<dependencies>
|
|
[What's needed to proceed]
|
|
</dependencies>
|
|
|
|
<open_questions>
|
|
[What couldn't be determined]
|
|
</open_questions>
|
|
|
|
<assumptions>
|
|
[What was assumed]
|
|
</assumptions>
|
|
|
|
<quality_report>
|
|
<sources_consulted>
|
|
[List URLs of official documentation and primary sources]
|
|
</sources_consulted>
|
|
<claims_verified>
|
|
[Key findings verified with official sources]
|
|
</claims_verified>
|
|
<claims_assumed>
|
|
[Findings based on inference or incomplete information]
|
|
</claims_assumed>
|
|
<confidence_by_finding>
|
|
- Finding 1: High (official docs + multiple sources)
|
|
- Finding 2: Medium (single source)
|
|
- Finding 3: Low (inferred, requires verification)
|
|
</confidence_by_finding>
|
|
</quality_report>
|
|
</metadata>
|
|
</output_structure>
|
|
|
|
<success_criteria>
|
|
- All scope questions answered
|
|
- All verification checklist items completed
|
|
- Sources are current and authoritative
|
|
- Clear primary recommendation
|
|
- Metadata captures uncertainties
|
|
- Quality report distinguishes verified from assumed
|
|
- Ready to inform PLAN.md creation
|
|
</success_criteria>
|
|
```
|
|
|
|
<when_to_use>
|
|
Create RESEARCH.md before PLAN.md when:
|
|
- Technology choice unclear
|
|
- Best practices needed for unfamiliar domain
|
|
- API/library investigation required
|
|
- Architecture decision pending
|
|
- Multiple valid approaches exist
|
|
</when_to_use>
|
|
|
|
<example>
|
|
```markdown
|
|
---
|
|
phase: 02-auth
|
|
type: research
|
|
topic: JWT library selection for Next.js App Router
|
|
---
|
|
|
|
<research_objective>
|
|
Research JWT libraries to determine best option for Next.js 14 App Router authentication.
|
|
|
|
Purpose: Select JWT library before implementing auth endpoints
|
|
Scope: Compare jose, jsonwebtoken, and @auth/core for our use case
|
|
Output: FINDINGS.md with library recommendation
|
|
</research_objective>
|
|
|
|
<research_scope>
|
|
<include>
|
|
- ESM/CommonJS compatibility with Next.js 14
|
|
- Edge runtime support
|
|
- Token creation and validation patterns
|
|
- Community adoption and maintenance
|
|
</include>
|
|
|
|
<exclude>
|
|
- Full auth framework comparison (NextAuth vs custom)
|
|
- OAuth provider configuration
|
|
- Session storage strategies
|
|
</exclude>
|
|
|
|
<sources>
|
|
Official documentation (prioritize):
|
|
- https://github.com/panva/jose
|
|
- https://github.com/auth0/node-jsonwebtoken
|
|
|
|
Context7 MCP for library docs
|
|
Prefer current/recent sources
|
|
</sources>
|
|
</research_scope>
|
|
|
|
<success_criteria>
|
|
- Clear recommendation with rationale
|
|
- Code examples for selected library
|
|
- Known limitations documented
|
|
- Verification checklist completed
|
|
</success_criteria>
|
|
```
|
|
</example>
|