research-synthesis
Synthesize research findings for OAK planning using the oak.plan-research workflow. Use when consolidating findings from codebase exploration, comparing approaches, or creating research/*.md documents.
When & Why to Use This Skill
The Research Synthesis skill is a specialized tool for the OAK planning workflow designed to bridge the gap between codebase exploration and task implementation. It automates the creation of structured research documents by synthesizing findings from local code analysis, project documentation, and external web research, ensuring that every technical decision is backed by evidence and aligned with project-specific standards (the 'Constitution').
Use Cases
- Codebase Pattern Analysis: Consolidating existing architectural patterns and conventions from a repository to ensure new features maintain consistency.
- Technical Trade-off Evaluation: Comparing multiple implementation approaches (e.g., different libraries or caching strategies) to provide a formal recommendation with a clear rationale.
- Project Planning & Task Generation: Transforming high-level research topics into detailed Markdown findings that directly inform the creation of actionable development tasks.
- Compliance & Standards Alignment: Cross-referencing proposed technical solutions with a project's 'Constitution' to guarantee adherence to testing, security, and documentation requirements.
| name | research-synthesis |
|---|---|
| description | Synthesize research findings for OAK planning using the oak.plan-research workflow. Use when consolidating findings from codebase exploration, comparing approaches, or creating research/*.md documents. |
OAK Research Synthesis
This skill provides expertise in synthesizing research findings for OAK's planning system - creating structured findings documents that inform task generation and implementation decisions.
OAK Research System Overview
Research in the OAK Workflow
/oak.plan-create /oak.plan-research /oak.plan-tasks
│ │ │
↓ ↓ ↓
plan.md with research/<topic>.md tasks.md
Research Topics ────► for each topic ────► informed by
research
File Structure
oak/plan/<plan-name>/
├── plan.md # Contains ## Research Topics
└── research/
├── research-manifest.yml # Tracks research state
├── <topic-slug>.md # Finding for each topic
├── api-integration.md
├── auth-patterns.md
└── performance-approach.md
When to Use This Skill
Use when you need to:
- Research topics identified in an OAK plan
- Consolidate findings from codebase exploration
- Compare multiple technical approaches
- Create
research/<topic>.mddocuments - Synthesize web research and documentation review
Source Categories for OAK Research
Codebase Analysis (Primary)
- Existing patterns and conventions
- Similar feature implementations
- Test patterns and coverage strategies
- Architecture decisions in code
Project Documentation
oak/constitution.md- Project standards- Architecture docs in
docs/ - API documentation
- README files
External Research (via web search)
- Library documentation
- Best practices guides
- Similar project implementations
- Industry standards (2024-2025 content preferred)
OAK Research Document Format
Each topic becomes research/<topic-slug>.md:
# Research: [Topic Name]
## Objective
What we're trying to learn or decide.
## Sources Consulted
- [x] Codebase patterns (searched: [what])
- [x] Project documentation
- [ ] External resources
- [ ] Constitution requirements
## Key Findings
### Finding 1: [Title]
- **Source**: [Where discovered - file path, URL, or doc]
- **Relevance**: [How it applies to our plan]
- **Confidence**: High/Medium/Low
### Finding 2: [Title]
- **Source**: [Where discovered]
- **Relevance**: [How it applies]
- **Confidence**: High/Medium/Low
## Synthesis
### Patterns Identified
- [Pattern 1]: [Where found, how to apply]
- [Pattern 2]: [Where found, how to apply]
### Contradictions/Tensions
- [Issue 1]: [Resolution approach]
### Gaps Identified
- [Gap 1]: [Mitigation or acceptance]
## Recommendation
**Decision**: [Chosen approach]
**Rationale**:
- [Reason 1 with evidence]
- [Reason 2 with evidence]
**Alternatives Considered**:
- [Alternative 1]: [Why not chosen]
## Impact on Tasks
[How this research affects task generation]
## Open Questions
[Things still needing investigation - may spawn additional research]
Research Workflow
Step 1: Load Plan Context
Read the plan to understand research topics:
## Research Topics (from plan.md)
- **API Integration**: How to integrate with external service
- Questions: Authentication pattern? Rate limiting?
- Priority: High
- **Caching Strategy**: Where and how to cache
- Questions: Redis vs in-memory? TTL approach?
- Priority: Medium
Step 2: Prioritize and Research
Research topics by priority:
- High priority - Research immediately, blocks other work
- Medium priority - Research before task generation
- Low priority - Can research during implementation
Step 3: Synthesis Process
For each topic:
- Organize findings by source type and confidence
- Identify patterns - consistent approaches across sources
- Note contradictions - resolve or escalate
- Create recommendation with evidence-based rationale
- Document impact on upcoming tasks
Step 4: Cross-Reference with Constitution
Every recommendation should reference constitution alignment:
## Constitution Alignment
- **Architecture**: Recommendation follows [pattern] per constitution §Architecture
- **Testing**: Will require [test approach] per constitution §Testing
- **Documentation**: Need to document [what] per constitution §Documentation
Quality Indicators for OAK Research
Good synthesis demonstrates:
- Multiple source corroboration (code + docs + external)
- Clear reasoning chain from findings to recommendation
- Constitution alignment explicitly stated
- Practical applicability to tasks
- Acknowledged uncertainties with mitigation
Best Practices
- Cite sources - Include file paths, URLs, line numbers for traceability
- Quantify confidence - Not all findings are equal
- Note contradictions - Don't force false consensus
- Prioritize codebase - Existing patterns often trump external best practices
- Test assumptions - Validate critical findings with actual code
- Update manifest - Mark topics as complete in research-manifest.yml
Integration with OAK Commands
| Command | Research Role |
|---|---|
/oak.plan-create |
Identifies research topics |
/oak.plan-research |
This is the research command |
/oak.plan-tasks |
Consumes research findings |
/oak.plan-implement |
May spawn ad-hoc research |
Quick Reference
- Research location:
oak/plan/<name>/research/<topic-slug>.md - State tracking:
oak/plan/<name>/research/research-manifest.yml - Input: Topics from
oak/plan/<name>/plan.md§ Research Topics - Output: Feeds into
/oak.plan-tasksfor task generation - Constitution: Always check
oak/constitution.mdfor alignment