microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/rpi/README.md
139lines · modecode
| 1 | --- |
| 2 | title: Understanding the RPI Workflow |
| 3 | description: Learn the Research, Plan, Implement, Review workflow for transforming complex tasks into validated code |
| 4 | sidebar_position: 1 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-02-18 |
| 7 | ms.topic: concept |
| 8 | keywords: |
| 9 | - rpi workflow |
| 10 | - task researcher |
| 11 | - task planner |
| 12 | - task implementor |
| 13 | - task reviewer |
| 14 | - github copilot |
| 15 | estimated_reading_time: 4 |
| 16 | --- |
| 17 | |
| 18 | The RPI (Research, Plan, Implement, Review) workflow transforms complex coding tasks into validated solutions through four structured phases. Think of it as a type transformation pipeline: |
| 19 | |
| 20 | > Uncertainty → Knowledge → Strategy → Working Code → Validated Code |
| 21 | |
| 22 | ## Why Use RPI? |
| 23 | |
| 24 | AI coding assistants are brilliant at simple tasks and break everything they touch on complex ones. The root cause: AI can't tell the difference between investigating and implementing. When you ask for code, it writes code. It doesn't stop to verify that patterns match your existing modules or that the APIs it's calling actually exist. |
| 25 | |
| 26 | RPI solves this through a counterintuitive insight: when AI knows it cannot implement, it stops optimizing for "plausible code" and starts optimizing for "verified truth." The constraint changes the goal. |
| 27 | |
| 28 | ### Key Benefits |
| 29 | |
| 30 | * Uses verified existing patterns instead of inventing plausible ones. |
| 31 | * Traces every decision to specific files and line numbers. |
| 32 | * Creates research documents anyone can follow, eliminating tribal knowledge. |
| 33 | |
| 34 | > [!TIP] |
| 35 | > **Want the full explanation?** See [Why the RPI Workflow Works](why-rpi.md) for the psychology, quality comparisons, and guidance on choosing between strict RPI and rpi-agent. |
| 36 | |
| 37 | RPI separates concerns into distinct phases, each with its own specialized custom agent. |
| 38 | |
| 39 | ## The Four Phases |
| 40 | |
| 41 | ### 🔬 Research Phase (Task Researcher) |
| 42 | |
| 43 | This phase transforms uncertainty into verified knowledge. |
| 44 | |
| 45 | * Investigates codebase, external APIs, and documentation |
| 46 | * Documents findings with evidence and sources |
| 47 | * Creates ONE recommended approach per scenario |
| 48 | * Output: `{{YYYY-MM-DD}}-<topic>-research.md` |
| 49 | |
| 50 | ### 📋 Plan Phase (Task Planner) |
| 51 | |
| 52 | This phase transforms knowledge into actionable strategy. |
| 53 | |
| 54 | * Creates coordinated planning files with checkboxes and details |
| 55 | * Includes line number references for precision |
| 56 | * Validates research exists before proceeding |
| 57 | * Output: Plan and details files |
| 58 | |
| 59 | ### ⚡ Implement Phase (Task Implementor) |
| 60 | |
| 61 | This phase transforms strategy into working code. |
| 62 | |
| 63 | * Executes plan task by task with verification |
| 64 | * Tracks all changes in a changes log |
| 65 | * Supports stop controls for review |
| 66 | * Output: Working code + `{{YYYY-MM-DD}}-<topic>-changes.md` |
| 67 | |
| 68 | ### ✅ Review Phase (Task Reviewer) |
| 69 | |
| 70 | This phase transforms working code into validated code. |
| 71 | |
| 72 | * Validates implementation against research and plan specifications |
| 73 | * Checks convention compliance using instruction files |
| 74 | * Runs validation commands (lint, build, test) |
| 75 | * Identifies follow-up work and iteration needs |
| 76 | * Output: `{{YYYY-MM-DD}}-<topic>-review.md` |
| 77 | |
| 78 | ## The Critical Rule: Clear Context Between Phases |
| 79 | |
| 80 | 🔴 **Always use `/clear` or start a new chat between phases.** |
| 81 | |
| 82 | Each custom agent has different instructions. Accumulated context causes confusion: |
| 83 | |
| 84 | ```text |
| 85 | Task Researcher → /clear → Task Planner → /clear → Task Implementor → /clear → Task Reviewer |
| 86 | ``` |
| 87 | |
| 88 | Research findings are preserved in files, not chat history. Clean context lets each agent work optimally. After clearing, open the relevant `.copilot-tracking/` artifact in your editor so the next agent can see it (for example, open the research document before invoking Task Planner). |
| 89 | |
| 90 | For the technical explanation of why this matters, see [Context Engineering](context-engineering.md). |
| 91 | |
| 92 | ## When to Use RPI |
| 93 | |
| 94 | | Use RPI When... | Use Quick Edits When... | |
| 95 | |--------------------------------|-------------------------| |
| 96 | | Changes span multiple files | Fixing a typo | |
| 97 | | Learning new patterns/APIs | Adding a log statement | |
| 98 | | External dependencies involved | Refactoring < 50 lines | |
| 99 | | Requirements are unclear | Change is obvious | |
| 100 | |
| 101 | **Rule of Thumb:** If you need to understand something before implementing, use RPI. |
| 102 | |
| 103 | ## Quick Start |
| 104 | |
| 105 | 1. **Define the problem** clearly |
| 106 | 2. **Research** using `/task-research <topic>` (automatically switches to Task Researcher) |
| 107 | 3. **Clear context** with `/clear` |
| 108 | 4. **Plan** using `/task-plan` (automatically switches to Task Planner) |
| 109 | 5. **Clear context** with `/clear` |
| 110 | 6. **Implement** using `/task-implement` (automatically switches to Task Implementor) |
| 111 | 7. **Clear context** with `/clear` |
| 112 | 8. **Review** using `/task-review` (automatically switches to Task Reviewer) |
| 113 | |
| 114 | > [!TIP] |
| 115 | > The `/task-research`, `/task-plan`, `/task-implement`, and `/task-review` prompts automatically switch to their respective custom agents, so you don't need to manually select them. |
| 116 | |
| 117 | ## Next Steps |
| 118 | |
| 119 | * [Task Researcher Guide](task-researcher.md) - Deep dive into research phase |
| 120 | * [Task Planner Guide](task-planner.md) - Create actionable plans |
| 121 | * [Task Implementor Guide](task-implementor.md) - Execute with precision |
| 122 | * [Task Reviewer Guide](task-reviewer.md) - Validate implementations |
| 123 | * [Using Them Together](using-together.md) - Complete workflow example |
| 124 | * [Context Engineering](context-engineering.md) - Why context management matters |
| 125 | * [Agents Reference](https://github.com/microsoft/hve-core/blob/main/.github/CUSTOM-AGENTS.md) - All available agents |
| 126 | * [Agent Systems Catalog](../agents/) - Browse all agent families beyond RPI |
| 127 | |
| 128 | ## See Also |
| 129 | |
| 130 | * [Engineer Guide](../hve-guide/roles/engineer.md) - Role-specific guide for engineers using RPI agents |
| 131 | * [Tech Lead Guide](../hve-guide/roles/tech-lead.md) - Architecture review and prompt engineering workflows |
| 132 | * [Stage 6: Implementation](../hve-guide/lifecycle/implementation.md) - Where RPI fits in the project lifecycle |
| 133 | |
| 134 | --- |
| 135 | |
| 136 | <!-- markdownlint-disable MD036 --> |
| 137 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 138 | then carefully refined by our team of discerning human reviewers.* |
| 139 | <!-- markdownlint-enable MD036 --> |
| 140 | |