Initial commit
This commit is contained in:
Zhongwei Li
106
skills/research-synthesis/reference/examples.md
Normal file
106
skills/research-synthesis/reference/examples.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Research Synthesis Examples
|
||||
|
||||
## Example: OKR Outputs vs Outcomes
|
||||
|
||||
This example shows how to use research-synthesis to validate a claim, synthesize findings into narrative, and integrate naturally into conversation.
|
||||
|
||||
```
|
||||
[During brainstorming]
|
||||
|
||||
You: I want to argue that OKRs fail because they measure outputs not outcomes
|
||||
|
||||
AI: [invokes research-synthesis]
|
||||
That's a common critique - let me see if there's data to support it...
|
||||
|
||||
[uses Perplexity: "OKR failures output vs outcome measurement"]
|
||||
|
||||
Found strong supporting evidence:
|
||||
|
||||
- Reforge 2024 study: 68% of failed OKR implementations measured
|
||||
outputs (features shipped) vs outcomes (user behavior change)
|
||||
- Amplitude research: Companies measuring outcomes had 3x higher
|
||||
product-market fit scores
|
||||
- Example: Spotify's "squad health" framework specifically avoided
|
||||
output metrics for this reason
|
||||
|
||||
Key pattern: Output metrics are easier to measure but don't correlate
|
||||
with business value. This ties directly to your Goodhart's Law point.
|
||||
|
||||
[updates braindump.md under Research section]
|
||||
|
||||
Added to braindump. This gives you concrete data to back the claim.
|
||||
Want to explore specific examples of good outcome metrics?
|
||||
|
||||
You: Yes, give me 2-3 examples
|
||||
|
||||
AI: [uses Perplexity: "good OKR outcome metrics examples"]
|
||||
|
||||
Strong examples:
|
||||
|
||||
1. Netflix: "Hours of satisfied viewing" (outcome) vs "hours watched" (output)
|
||||
2. Airbnb: "Nights booked by repeat guests" (outcome) vs "total bookings" (output)
|
||||
3. Stripe: "Developer time to first API call" (outcome) vs "API calls made" (output)
|
||||
|
||||
Pattern: Outcome metrics measure behavior change or satisfaction,
|
||||
outputs just measure activity.
|
||||
|
||||
[adds to braindump under Examples]
|
||||
|
||||
These work well as concrete illustrations. Should we outline the post now?
|
||||
```
|
||||
|
||||
## What This Example Demonstrates
|
||||
|
||||
**MCP Tool Selection:**
|
||||
- Used Perplexity for broad research (not a specific URL)
|
||||
- Searched for both validation and examples
|
||||
- Second query built on first findings
|
||||
|
||||
**Synthesis Techniques:**
|
||||
- Identified pattern across sources (68% correlation)
|
||||
- Connected findings to user's framework (Goodhart's Law)
|
||||
- Provided concrete examples, not just statistics
|
||||
- Noted implications (easier to measure ≠ more valuable)
|
||||
|
||||
**Integration with Conversation:**
|
||||
- Research happened naturally when claim needed support
|
||||
- Didn't interrupt flow—enhanced the argument
|
||||
- Asked follow-up question to continue exploration
|
||||
- Updated braindump.md in structured way
|
||||
|
||||
**Braindump Updates:**
|
||||
|
||||
Research section received:
|
||||
```markdown
|
||||
### Output vs Outcome Metrics
|
||||
Reforge study: 68% of failed OKR implementations measured outputs
|
||||
rather than outcomes. Companies measuring outcomes had 3x higher
|
||||
product-market fit scores.
|
||||
|
||||
Pattern: Output metrics (features shipped, API calls) are easier to
|
||||
measure but don't correlate with business value. Outcome metrics
|
||||
(user satisfaction, behavior change) harder but more meaningful.
|
||||
```
|
||||
|
||||
Examples section received:
|
||||
```markdown
|
||||
- Netflix: "Hours of satisfied viewing" vs "hours watched"
|
||||
- Airbnb: "Nights booked by repeat guests" vs "total bookings"
|
||||
- Stripe: "Developer time to first API call" vs "API calls made"
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
**Good Research Synthesis:**
|
||||
- 3-5 sources, not 20
|
||||
- Pattern identified across sources
|
||||
- Connected to user's existing framework
|
||||
- Concrete examples included
|
||||
- Source attribution maintained
|
||||
- Implications stated clearly
|
||||
|
||||
**Avoided Pitfalls:**
|
||||
- No information overload (focused on key findings)
|
||||
- Not just listing stats—synthesized into narrative
|
||||
- Didn't break creative flow—enhanced it
|
||||
- Asked before continuing (user control maintained)
|
||||
127
skills/research-synthesis/reference/multi-agent-invocation.md
Normal file
127
skills/research-synthesis/reference/multi-agent-invocation.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Multi-Agent Invocation Pattern
|
||||
|
||||
Guide for using specialized research agents in parallel for comprehensive investigation.
|
||||
|
||||
## Research Agents Overview
|
||||
|
||||
| Agent | Tool | Use Cases | Output |
|
||||
|-------|------|-----------|--------|
|
||||
| **research-breadth** (haiku, blue) | Perplexity | Industry trends, best practices, multiple perspectives, comparative analyses, "What are common patterns?" | Narrative patterns with consensus, confidence ratings, contradictions |
|
||||
| **research-depth** (haiku, purple) | Firecrawl | Specific URLs, detailed implementations, code examples, gotchas, "How did X implement Y?" | Source-by-source analysis with code, tradeoffs, applicability |
|
||||
| **research-technical** (haiku, green) | Context7 | Official docs, API signatures, TypeScript types, configs, migration guides, "What's the official API?" | Exact API specs with types, configurations, official examples |
|
||||
|
||||
## Agent Selection Decision Tree
|
||||
|
||||
| Question Type | Agent Combination | Rationale |
|
||||
|--------------|-------------------|-----------|
|
||||
| **New technology/framework** | breadth + technical | Industry patterns + Official API |
|
||||
| **Specific error/bug** | depth + technical | Detailed solutions + API reference |
|
||||
| **API integration** | technical + depth | Official docs + Real examples |
|
||||
| **Best practices/patterns** | breadth + depth | Industry trends + Case studies |
|
||||
| **Comparison/decision** | breadth + depth | Broad survey + Detailed experiences |
|
||||
| **Official API only** | technical | Just need documentation |
|
||||
|
||||
**Default when unsure**: breadth + technical
|
||||
|
||||
## Parallel Invocation Syntax
|
||||
|
||||
**Always use Promise.all for parallel execution:**
|
||||
|
||||
```typescript
|
||||
await Promise.all([
|
||||
Task({
|
||||
subagent_type: 'research-breadth', // or 'research-depth' or 'research-technical'
|
||||
model: 'haiku',
|
||||
description: 'Brief description',
|
||||
prompt: `Specific research question with focus areas and MCP tool guidance`
|
||||
}),
|
||||
|
||||
Task({
|
||||
subagent_type: 'research-technical',
|
||||
model: 'haiku',
|
||||
description: 'Brief description',
|
||||
prompt: `Specific research question with focus areas and MCP tool guidance`
|
||||
})
|
||||
]);
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: New Technology
|
||||
**Scenario**: Learning a new framework
|
||||
**Agents**: breadth + technical
|
||||
**Focus**: breadth (architectural patterns, industry trends), technical (official API, configs)
|
||||
**Consolidation**: Industry patterns → Official implementation
|
||||
|
||||
### Pattern 2: Specific Solution
|
||||
**Scenario**: Debugging or implementing known solution
|
||||
**Agents**: depth + technical
|
||||
**Focus**: depth (blog posts, implementations, gotchas), technical (official API, types)
|
||||
**Consolidation**: Real-world patterns → Official API usage
|
||||
|
||||
### Pattern 3: API Integration
|
||||
**Scenario**: Integrating with library/API
|
||||
**Agents**: technical + depth
|
||||
**Focus**: technical (official API, error codes), depth (tutorials, testing approaches)
|
||||
**Consolidation**: Official API first → Battle-tested patterns
|
||||
|
||||
### Pattern 4: Comparative Analysis
|
||||
**Scenario**: Choosing between approaches
|
||||
**Agents**: breadth + depth
|
||||
**Focus**: breadth (comparisons, trends), depth (migration experiences, lessons)
|
||||
**Consolidation**: Industry trends → Real experiences
|
||||
|
||||
## Synthesis Strategy
|
||||
|
||||
Use **research-synthesis skill** to consolidate findings:
|
||||
|
||||
1. **Consolidate**: Group by theme, identify consensus, note contradictions
|
||||
2. **Narrativize**: Weave findings into story (not bullet dumps): "Industry uses X (breadth), implemented via Y (technical), as shown by Z (depth)"
|
||||
3. **Attribute**: Link claims to sources, note which agent provided insights
|
||||
4. **Identify Gaps**: Unanswered questions, contradictions, disagreements
|
||||
5. **Extract Actions**: Implementation path, code/configs, risks, constraints
|
||||
|
||||
## Anti-Patterns vs Best Practices
|
||||
|
||||
| ❌ Anti-Pattern | ✅ Best Practice |
|
||||
|----------------|------------------|
|
||||
| Single agent for multi-faceted question | 2-3 agents for comprehensive coverage |
|
||||
| Sequential: `await` each agent | Parallel: `Promise.all([...])` |
|
||||
| Copy agent outputs verbatim in sections | Synthesize into narrative with attribution |
|
||||
| Skip source attribution | Note which agent/source for each claim |
|
||||
| List findings separately | Weave into coherent story |
|
||||
|
||||
## Complete Example
|
||||
|
||||
**User**: "How do I implement real-time notifications in Next.js?"
|
||||
|
||||
**Step 1: Analyze** → New technology + implementation
|
||||
**Step 2: Launch** → breadth + technical in parallel
|
||||
**Step 3: Synthesize**:
|
||||
|
||||
```markdown
|
||||
## Findings
|
||||
|
||||
Industry research shows three approaches: SSE (most popular for Next.js), WebSockets
|
||||
(bidirectional), Polling (fallback). Official Next.js docs indicate route handlers
|
||||
support SSE via ReadableStream, but WebSockets require external service on Vercel.
|
||||
|
||||
**Recommendation**: Use SSE via Next.js route handlers - aligns with framework
|
||||
capabilities and industry best practices.
|
||||
|
||||
**Implementation**: Create API route with ReadableStream → Client uses EventSource
|
||||
→ Handle reconnection/errors → Consider Vercel limitations
|
||||
|
||||
**Sources**: [Perplexity] Next.js real-time patterns 2024-2025 | [Context7] Next.js Route Handlers
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
**Used by**:
|
||||
- `/research` command (essentials) - User-initiated research
|
||||
- `implementing-tasks` skill (experimental) - Auto-launch when STUCK
|
||||
- `planning` skill (experimental) - Uses exploration agents instead
|
||||
|
||||
**Other agent categories**:
|
||||
- **Exploration** (codebase): architecture-explorer + codebase-analyzer (parallel)
|
||||
- **Review** (code quality): test-coverage + error-handling + security (all 3 parallel)
|
||||
Reference in New Issue
Block a user