| name | DERIVE Methodology |
| description | This skill should be used when the user asks about "DERIVE workflow", "effective development methodology", "research-backed approach", "structured development", "how to approach this task", or wants guidance on planning and executing software development tasks systematically. Provides the complete DERIVE methodology with research-backed evidence for each phase. |
| version | 1.0.0 |
DERIVE Methodology
A research-backed workflow for effective AI-assisted software development. DERIVE improves outcomes through structured phases, persistent documentation artifacts, and iterative refinement.
Why DERIVE Works
Research shows structured workflows dramatically outperform ad-hoc prompting:
| Technique | Improvement | Source |
|---|
| Self-planning before code | +25.4% Pass@1 | Jiang et al., 2023 |
| Iterative refinement | +20% to +63% | Self-Refine, CYCLE |
| Compiler/execution feedback | +80% | CoCoGen |
| Document-based communication | +67% executability | MetaGPT (ICLR 2024) |
| Testing phase | -17% to -56% without | LCG Study |
Critically, one RCT found AI slowed experienced developers by 19% when they skipped exploration and context-gathering. DERIVE prevents this.
The Six Phases
1. DECOMPOSE
Break complex tasks into atomic, testable sub-tasks before implementation.
Why it works: Self-planning research shows +25.4% Pass@1 improvement. Complex problems see up to +61.5% relative gains when decomposed first.
How to decompose:
- Create hierarchical task tree (root problem → leaf tasks)
- Each leaf should be a single, testable unit
- Identify dependencies between tasks
- Determine implementation order
- Output to
.derive/plan.md
Anti-patterns:
- Starting to code before decomposition
- Tasks too large ("implement authentication" vs. "create login form validation")
- Missing dependency identification
2. EXPLORE
Understand existing code before proposing changes.
Why it works: The productivity RCT found 19% slowdown when developers skipped exploration. Understanding context first avoids wasted effort and incorrect assumptions.
How to explore:
- Read files that will be modified
- Understand existing patterns and conventions
- Map dependencies and relationships
- Identify reusable components
- Use the existing
Explore agent for deep codebase research
Anti-patterns:
- Proposing changes to unread code
- Ignoring existing patterns/conventions
- Reinventing existing utilities
3. REASON
Apply explicit chain-of-thought for complex decisions.
Why it works: Chain-of-thought prompting is foundational to LLM reasoning. Explicit reasoning catches errors and produces better architectural decisions.
How to reason:
- Consider multiple approaches
- Evaluate tradeoffs explicitly
- Select approach with clear justification
- Document key decisions in
.derive/decisions.md
- Reference existing patterns discovered in Explore phase
Anti-patterns:
- Jumping to first solution without alternatives
- Implicit decision-making (no rationale captured)
- Ignoring tradeoffs
4. IMPLEMENT
Build bottom-up with minimal, focused changes.
Why it works: The Guided Code Generation framework achieved +23.79% improvement by implementing leaf nodes first and composing upward. Minimal changes reduce bug surface.
How to implement:
- Start with leaf tasks from decomposition
- Implement and test each unit before composing
- Follow existing code patterns discovered in Explore
- Make minimal changes—don't over-engineer
- Update
.derive/progress.md after each completed unit
Anti-patterns:
- Top-down implementation (root before leaves)
- Over-engineering beyond requirements
- Ignoring existing patterns
- Large changes without intermediate validation
5. VALIDATE
Execute, test, and verify with real feedback.
Why it works: Research shows removing testing causes -17% to -56% degradation. Compiler/execution feedback provides +80% improvement over static generation.
How to validate:
- Run tests after implementation
- Execute/compile for immediate feedback
- Verify against requirements in
.derive/spec.md
- Check edge cases
- Use the
derive:validator agent for systematic validation
Anti-patterns:
- Skipping tests
- Manual verification only
- Not checking against original spec
- Ignoring compiler warnings/errors
6. EVOLVE
Iterate based on feedback—optimal at 2-3 cycles.
Why it works: Self-Refine shows +20% improvement from iteration. CYCLE achieves up to +63.5% with feedback loops. Diminishing returns after 2-3 iterations.
How to evolve:
- Review validation results
- Identify improvements needed
- Iterate on implementation (2-3 cycles optimal)
- Update artifacts with learnings
- Know when to stop (diminishing returns)
Anti-patterns:
- Single-shot generation (no iteration)
- Infinite iteration without convergence
- Ignoring feedback signals
Persistent Artifacts
DERIVE uses four artifacts in .derive/ for session continuity and structured handoffs:
| Artifact | Purpose | Updated During |
|---|
spec.md | Requirements & acceptance criteria | Start, Evolve |
plan.md | Decomposed tasks & architecture | Decompose, Reason |
progress.md | Current state & completed work | All phases |
decisions.md | Key choices with rationale | Reason, Evolve |
Why artifacts matter: MetaGPT found document-based communication produces +67% better executability than dialogue, -49% tokens, and -67% fewer human revisions. Artifacts also enable session continuity across compacts.
When to Use DERIVE
Use DERIVE for:
- Multi-file changes
- New feature implementation
- Complex bug fixes requiring investigation
- Refactoring with architectural decisions
- Any task requiring >30 minutes of work
Skip DERIVE for:
- Single-line fixes
- Typo corrections
- Simple, obvious changes
- Tasks with explicit, detailed instructions already provided
Integration with Existing Agents
DERIVE complements Claude Code's built-in agents:
- Explore agent: Use during Explore phase for deep codebase research
- Plan agent: Can assist with Decompose phase
- derive:architect: DERIVE-specific decomposition with artifact output
- derive:validator: DERIVE-specific validation against spec
Quick Reference
DERIVE Workflow:
┌─────────────┐
│ 1. DECOMPOSE│ → Break into atomic tasks → plan.md
├─────────────┤
│ 2. EXPLORE │ → Understand existing code
├─────────────┤
│ 3. REASON │ → Explicit decision-making → decisions.md
├─────────────┤
│ 4. IMPLEMENT│ → Bottom-up, minimal changes → progress.md
├─────────────┤
│ 5. VALIDATE │ → Test against spec.md
├─────────────┤
│ 6. EVOLVE │ → Iterate 2-3 cycles
└─────────────┘
Additional Resources
For detailed research citations and paper links:
references/papers.md - Full citations with links to 15+ arxiv papers
For advanced guidance:
references/autonomy-levels.md - Research-backed autonomy calibration per phasereferences/feedback-loops.md - Compiler, test, and self-reflection feedback integrationreferences/metrics.md - Success metrics and validation against research
For commands to execute DERIVE workflow:
/derive:start <task> - Initialize workflow with new task/derive:approve-spec - Mandatory checkpoint before implementation (+61% productivity)/derive:continue - Resume after compact or new session/derive:status - Check current progress
For specialized agents:
derive:architect - Task decomposition and implementation planningderive:tdd - Test-driven development (RED-GREEN-REFACTOR cycle)derive:validator - Systematic validation against spec
