RPI Methodology: Research → Plan → Implement

A structured approach for working effectively on large, complex codebases with AI assistance.

The Problem

AI coding tools have a paradox:

• Excel at greenfield - New projects, fresh codebases
• Struggle with brownfield - Production systems, 100k+ LOC codebases

The root cause: context degradation. As conversations grow, AI loses coherence and makes increasingly poor decisions. Stanford research shows AI tools often create negative net productivity due to rework cycles.

Core Insight

"The contents of your context window are the ONLY lever you have to affect the quality of your output."

Context quality optimizes for (in order):

1. Correctness - Most critical
2. Completeness - All relevant information
3. Size minimization - Less noise
4. Trajectory clarity - Clear direction

Solution: Frequent Intentional Compaction

Design workflows around context management, maintaining 40-60% utilization through strategic human review points.

The RPI Framework

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  RESEARCH   │────▶│   PLANNING  │────▶│ IMPLEMENT   │
│             │     │             │     │             │
│ • Understand│     │ • Precise   │     │ • Execute   │
│   codebase  │     │   steps     │     │   phases    │
│ • Map files │     │ • File list │     │ • Verify    │
│ • Hypotheses│     │ • Test plan │     │ • Compact   │
└─────────────┘     └─────────────┘     └─────────────┘
      │                   │                   │
      ▼                   ▼                   ▼
  [Document]          [Document]          [Updated Doc]
      │                   │                   │
      └───────── Human Review Points ─────────┘

Phase 1: Research

Purpose: Understand the codebase as it exists today.

Key principles:

• Document, don't critique
• Find WHERE files live, HOW code works
• Use subagents for exploration (preserves main context)
• Output structured findings

Research outputs:

• Files involved with brief purposes
• Architecture overview
• Key patterns and conventions
• Potential approaches with tradeoffs
• Testing strategy

Template: See examples/research-template.md

Phase 2: Planning

Purpose: Create a detailed, verifiable implementation plan.

Key principles:

• No open questions in final plan
• Separate automated vs manual verification
• Break into phases with clear exit criteria
• Get human buy-in at each step

Planning outputs:

• Current state analysis
• Desired end state (with verification method)
• What we're NOT doing (explicit scope)
• Phased implementation with success criteria
• Rollback plan

Template: See examples/plan-template.md

Phase 3: Implementation

Purpose: Execute the approved plan with verification.

Key principles:

• Implement ONE phase at a time
• Run automated verification after each phase
• Pause for manual verification between phases
• Update plan document as phases complete
• Compact context when approaching 60% utilization

Human Leverage Hierarchy

Where human attention multiplies impact:

Phase	Error Multiplier	Human Focus
Research	1 mistake → 1000s of bad lines	HIGH
Planning	1 mistake → 100s of bad lines	HIGH
Implementation	1 mistake → isolated issue	Lower

Key insight: Review research and plans, not code details.

When to Use RPI

Use full RPI for:

• Features touching 5+ files
• Unfamiliar codebases
• Complex refactoring
• Bug fixes with unclear root cause
• Any task where you're uncertain about approach

Skip to planning for:

• Well-understood changes
• Small features in familiar code
• Clear bug with known fix

Skip to implementation for:

• Single-file changes
• Trivial fixes
• Previously planned work

Compaction Checkpoints

Compact context when:

• Transitioning between phases
• Context approaches 60% capacity
• Switching to a different task area
• Before complex multi-file operations

Compaction preserves:

• Document artifacts (RESEARCH.md, PLAN.md)
• Key decisions and rationale
• Current phase and progress
• Critical file references

Proven Results

• BAML Bug Fix: Novice Rust dev, no prior exposure to 300k LOC codebase → merged PR in 1 hour
• BAML Feature: 35k LOC in 7 hours by 2 engineers - work estimated at 3-5 senior engineer days

Quick Start

For any complex task, begin with:

I need to [task description].

Before implementing, let's follow the RPI methodology:

1. **Research Phase**: Help me understand the relevant parts of this codebase.
   - What files are involved?
   - How does the current implementation work?
   - What patterns should I follow?

2. **Planning Phase**: Once we understand the codebase, create a detailed plan.
   - Break into verifiable phases
   - Include success criteria for each phase

3. **Implementation Phase**: Execute the plan phase by phase.
   - Verify each phase before proceeding
   - Compact context between major phases

Anti-Patterns to Avoid

1. Diving into code without research - Leads to incorrect assumptions
2. Planning without verifiable phases - Creates ambiguous success criteria
3. Implementing everything at once - Causes context bloat and errors
4. Skipping human review points - Multiplies early mistakes
5. Letting context exceed 60% - Degrades output quality

Additional Resources

Reference Files

For detailed workflow guidance and patterns:

• references/workflow-details.md - Comprehensive phase-by-phase instructions

Example Files

Working templates in examples/:

• examples/research-template.md - Research document structure
• examples/plan-template.md - Implementation plan structure