// Use when writing ANY implementation code, fixing bugs, or modifying existing code. Delegates research to a fast subagent that distills WebSearch results into compact RAG-efficient summaries. Main context never sees raw output.
| name | research-before-coding |
| description | Use when writing ANY implementation code, fixing bugs, or modifying existing code. Delegates research to a fast subagent that distills WebSearch results into compact RAG-efficient summaries. Main context never sees raw output. |
Core principle: "You don't know anything until research confirms it"
You MUST research before writing implementation code. No exceptions.
The Iron Law:
NO IMPLEMENTATION CODE WITHOUT RESEARCH FIRST
Architecture: Research runs in a Task agent (haiku model). Raw WebSearch output stays in the agent's context. Only a distilled ~20-30 line summary returns to your context. This prevents context bloat from raw search responses.
Main Session Task Agent (haiku)
| |
|-- spawn with query ----------->|
| |-- run 10 WebSearch queries (parallel)
| |-- receive ~10 pages of raw output
| |-- distill to structured summary
| <-- return ~25 lines --------|
| | (agent context discarded)
|-- implement with knowledge |
ALWAYS use when:
Never skip research. Ever.
Use the Task tool with this exact pattern. Replace TECHNOLOGY, TASK, and QUESTION with your actual values:
Task(
subagent_type: "general-purpose",
model: "haiku",
description: "Research [TECHNOLOGY] [TASK]",
prompt: <see template below>
)
Agent Prompt Template:
You are a research distillation agent. Your job is to run WebSearch queries, read ALL raw output, and return ONLY a compact structured summary.
RESEARCH TOPIC: [TECHNOLOGY] [TASK]
CALLER NEEDS TO KNOW: [QUESTION - what specifically the main session needs answered]
## Step 1: Run ALL 10 WebSearch queries
Use the WebSearch tool to run ALL of these queries (run them in parallel where possible, replacing TECHNOLOGY and TASK):
1. WebSearch("best practices TECHNOLOGY TASK 2026")
2. WebSearch("TECHNOLOGY architecture patterns TASK")
3. WebSearch("github TECHNOLOGY TASK examples")
4. WebSearch("TECHNOLOGY TASK error handling 2026")
5. WebSearch("TECHNOLOGY TASK performance optimization 2026")
6. WebSearch("TECHNOLOGY TASK security best practices 2026")
7. WebSearch("TECHNOLOGY TASK testing 2026")
8. WebSearch("TECHNOLOGY vs alternatives comparison 2026")
9. WebSearch("TECHNOLOGY common pitfalls mistakes TASK 2026")
10. WebSearch("TECHNOLOGY TASK production deployment 2026")
## Step 2: Distill into structured summary
After ALL queries complete, read through every result carefully. Then produce EXACTLY this output format and nothing else:
---
## Research: TECHNOLOGY TASK
**Date**: YYYY-MM-DD
### Answer
[2-4 sentences directly answering QUESTION - the caller's specific need]
### Recommended Approach
- **Pattern**: [name the pattern/approach]
- **Library**: [recommended library + version if mentioned]
- **Why**: [1 sentence trade-off reasoning]
### Key Code Pattern
```[language]
[Most relevant code snippet, max 15 lines - the ONE pattern they should follow]
RULES:
### Step 2: Use context7 if library docs are needed (optional)
After the Task agent returns, if you need specific API syntax for a library mentioned in the summary, use context7 **directly in the main session** (these are lightweight calls):
1. `resolve-library-id`: `{"libraryName": "<library>", "query": "<what you need>"}`
2. `query-docs`: `{"libraryId": "<id>", "query": "<specific API question>"}`
context7 returns focused API docs, not bloated content, so it's safe in the main context.
### Step 3: Implement
You now have:
- Distilled research summary (~25 lines in your context)
- Optional API docs from context7
Proceed with implementation.
## Complete Example
**Scenario:** About to implement React authentication with NextAuth.
**What you do:**
Task( subagent_type: "general-purpose", model: "haiku", description: "Research React NextAuth authentication", prompt: "You are a research distillation agent. Your job is to run WebSearch queries, read ALL raw output, and return ONLY a compact structured summary.
RESEARCH TOPIC: React NextAuth authentication CALLER NEEDS TO KNOW: How to implement OAuth authentication in a Next.js 14 app using NextAuth v5, including session management and protected routes.
Use the WebSearch tool to run ALL of these queries (run them in parallel where possible):
[... same distillation instructions as template above ...]" )
**What comes back to your context (~25 lines):**
Date: 2026-02-10
NextAuth v5 (Auth.js) uses a new auth() function replacing getServerSession(). Configure providers in auth.ts at project root. Use middleware for protected routes. Session strategy defaults to JWT.
// auth.ts import NextAuth from "next-auth" import GitHub from "next-auth/providers/github" export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [GitHub], })
## Rationalization Table
| Excuse | Reality |
|--------|---------|
| "I know this pattern" | You're an AI trained on old data. APIs change. Research. |
| "This is obvious/standard" | 15 seconds of agent research vs 15 minutes of revert hell. |
| "Simple one-line fix" | Simple fixes break things when you're wrong. Verify first. |
| "This is slowing me down" | Broken code + revert + context loss = way slower. Research IS speed. |
## Red Flags - STOP and Research
**You are about to break things if:**
- Thinking "I know this"
- Thinking "it's just..."
- Thinking "quick fix"
- About to type code without spawning a research agent first
## The Cost Calculation
Agent research: 10 parallel queries + distillation = ~20 seconds, ~25 lines in your context Direct research: 10 parallel queries raw = ~20 seconds, ~500+ lines flooding your context Guessing: Type code -> Wrong -> Debug -> Revert -> Lost context = 15+ minutes
The math is unambiguous. Agent-delegated research is strictly better than both alternatives.
## The 10 Query Categories
| # | Query Type | Purpose |
|---|------------|---------|
| 1 | Best Practices | Latest established patterns |
| 2 | Architecture | Structural decisions |
| 3 | GitHub Examples | Real working code |
| 4 | Error Handling | Failure scenarios |
| 5 | Performance | Optimization techniques |
| 6 | Security | Safety considerations |
| 7 | Testing | Test strategies |
| 8 | Alternatives | Comparison shopping |
| 9 | Pitfalls | Common mistakes to avoid |
| 10 | Deployment | Production readiness |
## After Research
Once research is complete:
- Use `superpowers:writing-plans` to create implementation plan
- Use `superpowers:brainstorming` if design needs clarification
Log an accomplishment to Daily_Accomplishments and session-context. Use when the user wants to record a win, milestone, or personal achievement.
Refactor any skill by extracting deterministic operations into a Python script and slimming the SKILL.md to only AI judgment parts. Use when user says /codify, codify a skill, or optimize a skill.
Smart PRD generator with TaskMaster integration. Detects existing PRDs and offers execute/update/replace options. Generates comprehensive technical PRDs optimized for task breakdown, validates with 13 automated checks, and optionally executes tasks autonomously with datetime tracking and rollback support. Use when user requests "PRD", "product requirements", or mentions task-driven development. Defaults to PRD generation with handoff to TaskMaster. Optionally supports autonomous execution with 4 modes.
Session initialization and lifecycle management: bootstraps session context, organizes files, generates CLAUDE.md, manages soul purpose lifecycle with completion protocol and active context harvesting. Use when user says /start, /init, bootstrap session, initialize session, or organize project.