How the Four-Phase RPI Workflow Improves Code Quality in AI-Assisted Development

The four-phase RPI (Research → Plan → Implement → Review) workflow improves code quality by forcing AI agents to change objectives at each step, isolating context between phases, and requiring evidence-backed artifacts that prevent hallucinations from propagating.

The four-phase RPI workflow is a structured approach to AI-assisted coding implemented in the microsoft/hve-core repository. Unlike single-shot code generation that invites "creative drift," this methodology treats AI agents as specialized workers with distinct mandates. By compartmentalizing discovery, planning, execution, and validation into discrete phases with context isolation, the workflow transforms speculative generation into auditable, high-quality software engineering.

The Four Phases and Specialized Agents

The RPI workflow assigns a specialized agent to each phase, ensuring that concerns remain separated and each step produces a verifiable artifact before the next begins.

Research Phase: Task Researcher

In docs/rpi/task-researcher.md, the Task Researcher explores the repository, external documentation, and APIs without writing implementation code. The agent produces a research document stored under .copilot-tracking/research/ that cites exact file locations and line numbers (e.g., variables.tf#L47 or src/pipeline/writers/file_writer.py#L22-L34).

This phase prevents "plausible-but-wrong" architectural guesses. According to the source code in docs/rpi/why-rpi.md (lines 64-72), creating a traceable evidence base upfront eliminates the assumptions that typically plague AI-generated code.

Plan Phase: Task Planner

The Task Planner transforms the research artifact into a step-by-step implementation contract. This plan file records dependencies, execution order, and explicit success criteria for each step.

As documented in docs/rpi/why-rpi.md (lines 75-82), this guarantees that every change has a known intent and defined boundaries, reducing scope creep and preventing the AI from inventing requirements during implementation.

Implement Phase: Task Implementor

The Task Implementor executes the plan verbatim, re-using only the patterns discovered during the Research phase. The agent does not improvise or introduce new libraries not validated in the research document.

According to docs/rpi/why-rpi.md (lines 86-93), this eliminates creative drift and ensures the generated code follows established repository conventions rather than generic or hallucinated patterns.

Review Phase: Task Reviewer

The Task Reviewer validates the implementation against both the research artifact and the plan. This agent runs linting, executes test suites, and surfaces mismatches in a review log.

As noted in docs/rpi/why-rpi.md (lines 95-102), this provides a final safety net that catches regressions and deviations before merge, effectively creating a four-step quality gate.

Context Isolation Through Clean Hand-offs

Each phase begins with a clean context command (/clear), ensuring the next agent never sees the "noise" or intermediate reasoning of the previous step.

In docs/rpi/why-rpi.md (lines 50-52), the documentation emphasizes that this context isolation prevents hallucinations from propagating between phases. Without the /clear mechanism, an error in the Research phase could contaminate the Plan phase, leading to cascading failures in implementation.

Evidence-Backed Artifacts and Traceability

The workflow generates three persistent artifacts that traditional AI coding lacks:

1. Research documents containing exact citations (file.py#L47)
2. Plan files with success criteria and dependency ordering
3. Review logs capturing verification results and iteration needs

This creates institutional memory. As documented in docs/rpi/why-rpi.md (lines 32-34), these artifacts accumulate as "how-we-did-it" documentation that future contributors can reference instead of asking the AI to rediscover the same patterns.

The traceability difference is stark: traditional AI offers "The AI wrote it this way," while RPI provides research citing concrete lines like src/pipeline/writers/file_writer.py#L22-L34 (docs/rpi/why-rpi.md, lines 13-14).

Quantifiable Quality Improvements

The quality comparison table in docs/rpi/why-rpi.md (lines 12-17) demonstrates measurable advantages:

Aspect	Traditional AI	Four-Phase RPI
Pattern matching	Invents plausible patterns	Uses verified existing patterns
Traceability	Opaque generation logic	Research cites concrete lines
Rework	Frequent after-the-fact fixes	Rare, because assumptions are verified first
Validation	Manual testing only	Formal review against specs with evidence

Workflow Variants: Strict RPI vs. rpi-agent

The repository supports two execution modes that maintain the same four-phase discipline:

Strict RPI requires manual hand-offs using /clear commands between each phase. This variant, recommended in docs/rpi/why-rpi.md (lines 38-46), is best for high-risk changes or work in unfamiliar codebases where human oversight at each boundary provides safety.

rpi-agent (defined in .github/agents/hve-core/rpi-agent.agent.md) operates as a single autonomous agent that internally dispatches the four sub-agents automatically. While faster for simple, well-known changes, it maintains the same artifact generation and validation steps (docs/rpi/why-rpi.md, lines 54-62).

Practical Implementation Examples

Strict RPI Session

The following commands demonstrate a complete strict workflow in GitHub Copilot Chat:

# 1. Research phase

/task-research Add Azure Blob Storage integration to Python data pipeline

Copilot creates .copilot-tracking/research/2024-06-01-azure-blob-research.md with citations like src/pipeline/writers/file_writer.py#L22-L34.

# 2. Context isolation (critical)

/clear

# 3. Planning phase

/task-plan .copilot-tracking/research/2024-06-01-azure-blob-research.md

Copilot produces plan-azure-blob.md detailing steps, dependencies, and success criteria.

# 4. Clear context again

/clear

# 5. Implementation phase

/task-implement plan-azure-blob.md

The generated code respects verified patterns (e.g., using BlobServiceClient.from_connection_string because research documented this as the repository's preferred style).

# 6. Clear context once more

/clear

# 7. Review phase

/task-review plan-azure-blob.md implementation/

The review outputs a mismatch table, runs validation tools like terraform validate or pytest, and writes review-azure-blob.log.

Automated rpi-agent Shortcut

For trusted patterns, the single-command variant executes the same four phases internally:

/rpi Add Azure Blob Storage integration to Python data pipeline

The agent displays hand-off buttons between phases and outputs the identical artifact set without manual /clear operations.

Key Source Files

Understanding the implementation requires examining these specific files in microsoft/hve-core:

• docs/rpi/why-rpi.md — Contains the quality comparison table and counter-intuitive insights about context isolation (lines 50-52)
• docs/rpi/task-researcher.md — Defines the research artifact format and citation requirements (lines 41-53)
• docs/rpi/task-planner.md — Specifies how the plan contract transforms research into executable steps
• docs/rpi/task-implementor.md — Describes verbatim execution constraints
• docs/rpi/task-reviewer.md — Lists validation steps and hand-off expectations
• .github/agents/hve-core/rpi-agent.agent.md — Defines the autonomous orchestration of sub-agents

Summary

• The four-phase RPI workflow separates discovery, planning, coding, and validation into discrete, context-isolated steps.
• Specialized agents (Researcher, Planner, Implementor, Reviewer) prevent creative drift by restricting each phase to a single objective.
• Evidence-backed artifacts stored in .copilot-tracking/ provide traceability through exact file citations (e.g., L22-L34) rather than opaque AI reasoning.
• Context isolation via /clear commands stops hallucinations from propagating between phases.
• Strict and automated variants both maintain the four-phase discipline, allowing teams to choose manual oversight or speed based on risk tolerance.

Frequently Asked Questions

What does RPI stand for in the four-phase workflow?

RPI stands for Research, Plan, Implement, and Review. According to the microsoft/hve-core documentation in docs/rpi/why-rpi.md, this sequence forces the AI to switch modes between information gathering, architectural design, code execution, and quality validation rather than attempting all simultaneously.

How does context isolation prevent errors in AI-generated code?

The /clear command resets the AI's context between phases, ensuring that assumptions or hallucinations from the Research phase cannot influence the Plan or Implement phases. As documented in docs/rpi/why-rpi.md (lines 50-52), this isolation guarantees that only verified knowledge from the previous phase's artifact carries forward, eliminating contamination that would otherwise let errors propagate downstream.

Where are the research artifacts stored in the repository?

Research artifacts are stored under .copilot-tracking/research/ as markdown files containing exact citations to source code locations. The Task Researcher agent creates these documents with specific line references (e.g., variables.tf#L47) that serve as traceable evidence for subsequent phases, as specified in docs/rpi/task-researcher.md (lines 41-53).

When should I use strict RPI versus the rpi-agent?

Use strict RPI (manual /clear hand-offs) for high-risk changes, unfamiliar codebases, or complex architectural work where human verification at each boundary provides safety, as recommended in docs/rpi/why-rpi.md (lines 38-46). Use rpi-agent for simple, well-understood changes where speed matters, as the autonomous agent maintains the same four-phase discipline while automating the hand-offs internally (lines 54-62).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}