Structured RPI Workflows

The Premature Convergence Problem

A common failure mode in AI-augmented development: jump straight from problem statement to code. "Build a login system" → AI generates 500 lines of code → you discover the architecture is wrong → start over.

This happens because code generation is seductive. The AI can produce working code very quickly. You feel momentum. But momentum in the wrong direction is worse than no momentum.

The RPI framework (Research-Plan-Implement) prevents premature convergence by imposing a three-phase state machine. Each phase has a specific goal and outputs. Phases don't overlap.

"The cost of getting the architecture wrong is 10x the cost of spending 30 minutes planning it correctly upfront."

Phase 1: Research (No Code Generation)

Goal: Understand the problem deeply. Output: A markdown document describing the problem, constraints, and existing patterns in the codebase.

What happens in Research:

• Read relevant files (tests, existing similar features, domain models)
• Understand constraints (performance requirements, regulatory, team conventions)
• Identify existing patterns (how authentication is currently done, how state is managed)
• Document findings in a markdown file

What does NOT happen:

• No code generation
• No architectural proposals
• No tool configuration

The engineer reads the research doc and makes a go/no-go decision. "Do we understand the problem well enough to design a solution?" If not, more research.

Phase 2: Plan (Design, No Implementation)

Goal: Design a solution. Output: An architectural markdown document with implementation strategy, file structure, key decision rationale.

What happens in Plan:

• Propose an architecture (given the research findings)
• Document trade-offs and key decisions
• Outline the implementation steps
• Identify risky areas

What does NOT happen:

• No code is written
• No tests are written
• No files are modified

The engineer reviews the plan. They ask questions. They propose changes. Only when the plan is approved do you move to implementation.

This is the critical gate. A wrong plan caught here costs 30 minutes to revise. The same wrong plan discovered 4 hours into implementation costs days to unwind.

Phase 3: Implement (Code, With Verification)

Goal: Execute the plan. Output: Working code with passing tests.

What happens in Implement:

• Follow the plan exactly (no ad-hoc deviations)
• Write code and tests in parallel
• Run tests constantly to catch regressions
• Commit regularly with clear messages

What does NOT happen:

• No architecture changes (those are plan-phase decisions)
• No new features beyond the plan scope
• No exploratory code (all code is plan-driven)

If during implementation you discover the plan needs revision, you escalate to the human. You don't silently deviate. This preserves the contract: plan was approved, implement must follow the plan.

The State Machine

RESEARCH --[plan approved]--> PLAN --[design approved]--> IMPLEMENT --[done]--> end
   |                            |                           |
   |--[needs more research]-----|                           |--[plan violation detected]--> PLAN
   |                            |--[revise]--> PLAN         |--[failed tests]--> IMPLEMENT
   |                            |--[reject]--> RESEARCH     |--[success]--> end

Key point: you can move backwards. If implementation reveals a plan flaw, you don't patch the code—you go back to the plan phase and revise.

Why This Works

The RPI structure prevents four common problems:

• Premature implementation: Forcing a plan phase ensures you think before coding.
• Architecture disagreement: The plan is reviewed and approved before code exists. No "I didn't realize you were thinking that way" surprises.
• Scope creep: The implementation phase follows the plan. Requests for additional features go to a new RPI cycle, not into the current one.
• Rework: By catching design mistakes in the plan phase (cheap), you avoid implementation rework (expensive).

Duration Expectations

• Simple features: Research 15 min, Plan 15 min, Implement 30 min. Total: 1 hour.
• Medium features: Research 45 min, Plan 45 min, Implement 3 hours. Total: 4.5 hours.
• Complex systems: Research 4 hours, Plan 2 hours, Implement 2 days. Total: 2.5 days.

The research and plan phases compress with experience. You learn patterns and can research/plan faster. Implementation stays expensive—rightfully so, since that's where the work happens.

Integrating with Claude Code

Claude Code supports RPI natively via plan mode:

1. Research phase: Use standard Claude Code, read files, explore patterns.
2. Plan phase: Enter plan mode (/plan). AI designs a solution, you review and approve.
3. Implement phase: Exit plan mode, execute the approved plan.

This surfaces the three-phase structure explicitly in the tool.