Skip to content

docs: add comprehensive "why" documentation for RPI workflow #152

@WilliamBerryiii

Description

@WilliamBerryiii

Issue Description

Add comprehensive "why" documentation for the RPI (Research→Plan→Implement) workflow, explaining the psychology of constraints, time benefits, and when to use strict RPI vs rpi-agent.

Problem

Current RPI documentation explains WHAT the workflow is and HOW to use it, but lacks explanation of WHY the framework works. Users cannot make informed decisions about when to use RPI vs rpi-agent without understanding the underlying principles.

Deliverables

  • Create docs/rpi/why-rpi.md - comprehensive "why" document (primary)
  • Update docs/rpi/README.md - streamline "Why Use RPI?" section
  • Update README.md (root) - add problem statement teaser
  • Update docs/rpi/using-together.md - expand RPI Agent decision criteria
  • Update docs/getting-started/first-workflow.md - add motivation callout

Acceptance Criteria

  • Readers understand WHY traditional AI coding fails before learning RPI
  • Psychology of constraints is explained (why limiting AI improves output)
  • Time/quality comparisons are documented (6-8 hrs → 2-3 hrs)
  • Clear guidance on when to use strict RPI vs rpi-agent
  • All content follows repository markdown and writing style conventions

Additional Context

Research completed in .copilot-tracking/research/20260105-rpi-why-documentation-research.md with proposed content for all five files.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions