Research-Driven Development

Overview

Every decision is research-informed. Every phase gates the next. No code without validated specifications.

Core principle: Research drives all phases of product development — from technology choices to deployment strategy. The quality of your output is bounded by the quality of your research.

Iron Law: NO IMPLEMENTATION WITHOUT RESEARCH-VALIDATED SPECIFICATIONS.

When to Use

Always use when:

• Building a new feature (any size beyond trivial)
• Choosing a technology, library, or pattern
• Setting up project infrastructure (CI/CD, deployment, repo)
• Making architectural decisions
• Starting a new project phase

Don't use when:

• Fixing a typo or single-line bug
• Task has explicit, detailed instructions with no ambiguity
• Pure research/exploration (use Explore agent directly)

The Pipeline

digraph pipeline {
    rankdir=LR;
    node [shape=box];

    R [label="RESEARCH" style=filled fillcolor="#e3f2fd"];
    V [label="VALIDATE" style=filled fillcolor="#fff3e0"];
    P [label="PLAN" style=filled fillcolor="#e8f5e9"];
    I [label="IMPLEMENT" style=filled fillcolor="#f3e5f5"];
    RV [label="REVIEW" style=filled fillcolor="#fce4ec"];
    VF [label="VERIFY" style=filled fillcolor="#e0f7fa"];
    D [label="DELIVER" style=filled fillcolor="#f1f8e9"];

    R -> V -> P -> I -> RV -> VF -> D;
    RV -> I [label="fix issues" style=dashed];
}

Each phase produces an artifact. Each artifact is validated before the next phase begins. Phases cannot be skipped.

Phase 1: RESEARCH

Goal: Understand the problem space, current best practices, and existing patterns before any decisions.

Model: Haiku or Sonnet (read-only, speed over depth)

Actions:

1. Explore codebase — Dispatch Explore agent to understand existing patterns, conventions, and architecture
2. Search documentation — Use Context7 MCP or web search for current framework/library docs
3. Research best practices — Web search for 2-3 independent sources on the specific technology/pattern
4. Check community patterns — Search for how others solved similar problems (GitHub, Stack Overflow, official guides)

Output artifact: Research summary with:

• Current best practices (with sources)
• Relevant existing patterns in codebase
• Technology-specific considerations
• Security implications (if applicable)

Quality gate: Research must include at least 2 independent sources. Single-source research is insufficient.

REQUIRED SUB-SKILL: Use superpowers:dispatching-parallel-agents for independent research queries.

Phase 2: VALIDATE

Goal: Cross-reference research findings against community consensus and project constraints.

Model: Sonnet

Actions:

1. Cross-reference sources — Do findings agree? Flag contradictions.
2. Check against project context — Does the approach fit existing architecture, tech stack, team conventions?
3. Evaluate trade-offs — Cost, complexity, maintenance burden, learning curve
4. Security review — Flag any security implications from research

Output artifact: Validated decision document:

• Recommended approach with justification
• Rejected alternatives with reasons
• Identified risks and mitigations
• Alignment with project conventions

Quality gate: Approach must be validated against at least 2 sources AND project context. Contradictions must be resolved, not ignored.

Phase 3: PLAN

Goal: Create a detailed, research-informed implementation plan with explicit success criteria per task.

Model: Opus (architectural decisions require deep reasoning)

Actions:

1. Write specification — Define WHAT and WHY, informed by validated research
2. Decompose into atomic tasks — Each task modifies 3-5 files max, completable in one agent context
3. Define success criteria — Each task has explicit, testable acceptance criteria
4. Assign model per task — Use ACR scoring (E+R+I) to select Opus/Sonnet/Haiku per task
5. Map dependencies — Identify which tasks can run in parallel vs. sequential

Output artifact: Implementation plan saved to docs/plans/YYYY-MM-DD-<feature>.md

Quality gate: Plan must reference research findings. Each task must have files, code, test commands, and success criteria.

REQUIRED SUB-SKILL: Use superpowers:writing-plans for plan format and structure.

Phase 4: IMPLEMENT

Goal: Execute the plan task-by-task with fresh sub-agents, following TDD.

Model: Per-task ACR routing

Actions:

1. Dispatch fresh sub-agent per task — Complete task context provided upfront (no file reading needed)
2. Sub-agent follows TDD — RED (failing test) → GREEN (minimal implementation) → REFACTOR
3. Sub-agent self-reviews — Before reporting back, verify own work
4. Commit per task — Small, atomic commits with descriptive messages

Quality gate: Each task must have passing tests before moving to review.

REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development for dispatch and coordination. REQUIRED SUB-SKILL: Sub-agents MUST use superpowers:test-driven-development.

Phase 5: REVIEW

Goal: Two-stage review ensures both correctness and quality.

Model: Sonnet for spec compliance, Opus for code quality

Stage 1 — Spec Compliance:

• Does implementation match specification?
• Are all acceptance criteria addressed?
• Any missing requirements? Any extra/unneeded work?
• Uses: spec-reviewer-prompt.md template

Stage 2 — Code Quality (only after Stage 1 passes):

• Clean, maintainable, follows project conventions?
• Security vulnerabilities?
• Performance issues?
• Test quality and coverage?
• Uses: code-quality-reviewer-prompt.md template

Quality gate: Both stages must pass. Issues found → implementer fixes → re-review. No skipping re-reviews.

REQUIRED SUB-SKILL: Use superpowers:requesting-code-review for review dispatch.

Phase 6: VERIFY

Goal: Run all verification commands and confirm against requirements.

Model: Sonnet

Actions:

1. Run full test suite — Not just new tests, ALL tests
2. Run linter/formatter — Zero warnings on new code
3. Run type checker — If applicable (mypy, dart analyze, tsc)
4. Requirements checklist — Line-by-line verification against plan
5. Regression check — Ensure no existing functionality broken

Quality gate: ALL verification commands must produce passing output in THIS message. No claims without evidence.

REQUIRED SUB-SKILL: Use superpowers:verification-before-completion — this is non-negotiable.

Phase 7: DELIVER

Goal: Package, document, and ship the work following best practices.

Model: Sonnet

Actions (context-dependent, use what applies):

• Git: Clean commit history, descriptive messages, proper branching
• CI/CD: Ensure pipelines pass, add/update workflows if needed
• Documentation: Update README, API docs, changelogs as needed
• Repository setup: .gitignore, dependabot, branch protection, security settings
• Deployment: Infrastructure config, environment variables, monitoring
• PR/Merge: Present structured options per superpowers:finishing-a-development-branch

Quality gate: All CI checks pass. Documentation reflects current state.

REQUIRED SUB-SKILL: Use superpowers:finishing-a-development-branch for merge/PR workflow.

Model Selection Quick Reference