A Research-Plan-Implement (RPI) workflow for AI-assisted software development with human-in-the-loop checkpoints. This document serves as a reference for both AIs and humans, ensuring quality through structured research, planning, and implementation phases, each with AI self-review and human approval gates.
Learn about the theory behind RPI from Dax: https://www.youtube.com/watch?v=rmvDxxNubIg
All work for a feature or change happens in a dedicated plan folder (e.g., plans/a7z-feature-name/). Each plan folder has a corresponding git branch and pull request, keeping code changes tied to their documentation.
Each step is labeled as [entity]:[task] where entity is either AI or Human, and task describes the action. Each AI: step should start a fresh session with context limited to the relevant plan folder files. This practice of scoping AI context to specific artifacts is called Context Engineering—it keeps sessions focused and prevents context pollution across phases.
-
Research
- AI:Work Write research.md detailing requirements, system architecture, and exploring decisions
- AI:Review Write research-review-NNN.md
- AI:Gate Needs revision? If yes, go back to 1:AI:Work, else continue
- Human:Review Approve research findings and decisions before proceeding to Plan
-
Plan
- AI:Work Write plan.md detailing the changes we plan to make given decisions in research.md
- AI:Review Write plan-review-NNN.md
- AI:Gate Needs revision? If yes, go back to 2:AI:Work, else continue
- Human:Review Approve plan before proceeding to Implement
-
Implement
- AI:Work Implement the plan.md (or plan-NNN.md if revising) and then write devlog-NNN.md covering what was done, tricky, and decisions made during implementation
- AI:Review Review the implementation in a code-review-NNN.md
- AI:Gate Needs revision? If yes, write plan-NNN.md and go back to 3:AI:Work, else write pr.md and continue
- Human:Review Final approval of implementation
File/folder naming conventions:
- XXX = 3-char alphanumeric code (e.g.,
a7z,k3p; avoid sequential or word-like codes) - name = kebab-case (e.g.,
foo-bar) - NNN = 3-digit number, zero-padded, for versioning iterations (e.g.,
001,002)
Location: plans/XXX-name/
Files:
research.md- Requirements, system architecture, constraints, prior artresearch-review-NNN.md- AI self-review of research findingsplan.md- Main spec with motivation, goals, design, and implementation approachplan-review-NNN.md- AI self-review when iterating on plandecision-XXX-name.md- Optional ADR-style decisions as neededdevlog-NNN.md- Implementation journal: what was done, tricky parts, decisions madecode-review-NNN.md- AI self-review when iterating on code during implementationpr.md- PR description: summary paragraph, code walkthrough, test instructions
Read CONTRIBUTING.md for context. You are starting research for [feature/task].
Requirements: [paste requirements or link to issue]
Write research.md covering requirements, system architecture, constraints, prior art, and open questions.
Read CONTRIBUTING.md for context. Review research.md and write research-review-NNN.md following the template.
Read CONTRIBUTING.md for context. Read research.md and research-review-NNN.md. Are there any High gaps or unresolved questions? If yes, summarize what needs revision. If no, confirm ready for human review.
Read CONTRIBUTING.md for context. Read research.md for decisions and context.
Write plan.md detailing the implementation approach.
Read CONTRIBUTING.md for context. Review plan.md against research.md and write plan-review-NNN.md following the template.
Read CONTRIBUTING.md for context. Read plan.md and plan-review-NNN.md. Are there any High concerns? If yes, summarize what needs revision. If no, confirm ready for human review.
Read CONTRIBUTING.md for context. Read plan.md (or plan-NNN.md if revising).
Implement the plan. When done, write devlog-001.md covering what was done, tricky parts, and any decisions made.
Read CONTRIBUTING.md for context. Review the implementation against plan.md and write code-review-NNN.md following the template.
Read CONTRIBUTING.md for context. Read devlog-NNN.md and code-review-NNN.md. Are there any High issues? If yes, write plan-NNN.md with fixes needed. If no, write pr.md and confirm ready for human review.
# Research: [Brief Title]
**Requester:** [Who asked]
**Date:** [Date]
## Requirements
### Original Request
[The ask verbatim or paraphrased]
### Context
[Context that came with the request]
### Open Questions
- [Questions to explore]
## System Architecture
### Related Components
[Overview of existing systems this feature touches]
### Data Flow
[How data moves through the relevant systems]
### Constraints
[Technical or business constraints to consider]
## Prior Art
[Similar implementations, patterns, or references]# Plan: [Feature Name]
**Status:** Draft | In Review | Approved | Implemented
**Author:** [Name]
**Created:** [Date]
## Summary
[One paragraph]
## Motivation
[Why is this needed?]
## Goals
- [What this achieves]
## Non-Goals
- [What this does not address]
## Technical Design
[Detailed approach]
## Implementation Approach
[Step-by-step implementation plan, key files to modify, order of operations]
## Alternatives Considered
[Other approaches and why not chosen]# Decision: [Brief Title]
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** [Date]
**Deciders:** [Who made the decision]
## Context
[What is the situation? What problem or question prompted this decision?]
## Options
### Option 1: [Name]
[Brief description]
**Pros:**
- [Advantage]
**Cons:**
- [Disadvantage]
### Option 2: [Name]
[Brief description]
**Pros:**
- [Advantage]
**Cons:**
- [Disadvantage]
## Decision
[Which option was chosen and why]
## Consequences
### Positive
- [Benefits of this decision]
### Negative
- [Drawbacks or tradeoffs]
### Neutral
- [Other effects]# Research Review: [Brief Title]
**Reviewer:** AI
**Date:** [Date]
**Reviewing:** research.md
## Summary
[One paragraph assessment of the research]
## Strengths
- [What the research does well]
## Gaps
### High
- [Critical missing information that blocks planning]
### Medium
- [Important gaps that should be addressed]
### Low
- [Nice-to-have information]
## Questions
- [Clarifications needed before planning]
## Recommendation
[ ] Ready for human review
[ ] Needs revision (see gaps/questions above)# Plan Review: [Brief Title]
**Reviewer:** AI
**Date:** [Date]
**Reviewing:** plan.md (or plan-NNN.md)
## Summary
[One paragraph assessment of the plan]
## Strengths
- [What the plan does well]
## Concerns
### High
- [Critical issues that could cause failure]
### Medium
- [Significant risks or unclear areas]
### Low
- [Minor issues or suggestions]
## Suggestions
- [Improvements or alternatives to consider]
## Recommendation
[ ] Ready for human review
[ ] Needs revision (see concerns/suggestions above)# Devlog: [Brief Title]
**Date:** [Date]
**Implementing:** plan.md (or plan-NNN.md)
## What Was Done
- [Completed work]
## Tricky Parts
- [Challenges encountered and how they were resolved]
## Decisions Made
- [Implementation decisions not covered in the plan]
## Deviations from Plan
- [Any changes from the original plan and why]
## Next Steps
- [If incomplete, what remains]# Code Review: [Brief Title]
**Reviewer:** AI
**Date:** [Date]
**Reviewing:** [commit hash or file list]
## Summary
[One paragraph assessment of the implementation]
## What Works Well
- [Positive aspects of the code]
## Issues
### High
- [ ] [Critical bugs or security issues]
### Medium
- [ ] [Significant problems that should be fixed]
### Low
- [ ] [Minor improvements or style issues]
## Questions
- [Clarifications or design questions]
## Recommendation
[ ] Ready for human review
[ ] Needs revision (see issues above)# [PR Title]
[One paragraph: what changed and why]
## Architecture
```mermaid
[Diagram showing key components and data flow]
```
## Decisions
1. [list of decisions made during planning, one paragraph each]
## Code Walkthrough
1. [Recommended order of reading through code]
## Testing Instructions
1. [Steps to test]