/prp-plan

description: Create comprehensive feature implementation plan with codebase analysis and pattern extraction
argument-hint: <feature description | path/to/prd.md>

> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.

PRP Plan

Create a detailed, self-contained implementation plan that captures all codebase patterns, conventions, and context needed to implement a feature in a single pass.

**Core Philosophy**: A great plan contains everything needed to implement without asking further questions. Every pattern, every convention, every gotcha — captured once, referenced throughout.

**Golden Rule**: If you would need to search the codebase during implementation, capture that knowledge NOW in the plan.

---

Phase 0 — DETECT

Determine input type from `$ARGUMENTS`:

| Input Pattern | Detection | Action | |---|---|---| | Path ending in `.prd.md` | File path to PRD | Parse PRD, find next pending phase | | Path to `.md` with "Implementation Phases" | PRD-like document | Parse phases, find next pending | | Path to any other file | Reference file | Read file for context, treat as free-form | | Free-form text | Feature description | Proceed directly to Phase 1 | | Empty / blank | No input | Ask user what feature to plan |

PRD Parsing (when input is a PRD)

1. Read the PRD file with `cat "$PRD_PATH"` 2. Parse the **Implementation Phases** section 3. Find phases by status:

• Look for `pending` phases
• Check dependency chains (a phase may depend on prior phases being `complete`)
• Select the **next eligible pending phase**

4. Extract from the selected phase:

• Phase name and description
• Acceptance criteria
• Dependencies on prior phases
• Any scope notes or constraints

5. Use the phase description as the feature to plan

If no pending phases remain, report that all phases are complete.

---

Phase 1 — PARSE

Extract and clarify the feature requirements.

Feature Understanding

From the input (PRD phase or free-form description), identify:

• **What** is being built (concrete deliverable)
• **Why** it matters (user value)
• **Who** uses it (target user/system)
• **Where** it fits (which part of the codebase)

User Story

Format as:

As a [type of user],
I want [capability],
So that [benefit].

Complexity Assessment

| Level | Indicators | Typical Scope | |---|---|---| | **Small** | Single file, isolated change, no new dependencies | 1-3 files, <100 lines | | **Medium** | Multiple files, follows existing patterns, minor new concepts | 3-10 files, 100-500 lines | | **Large** | Cross-cutting concerns, new patterns, external integrations | 10+ files, 500+ lines | | **XL** | Architectural changes, new subsystems, migration needed | 20+ files, consider splitting |

Ambiguity Gate

If any of these are unclear, **STOP and ask the user** before proceeding:

• The core deliverable is vague
• Success criteria are undefined
• There are multiple valid interpretations
• Technical approach has major unknowns

Do NOT guess. Ask. A plan built on assumptions fails during implementation.

---

Phase 2 — EXPLORE

Gather deep codebase intelligence. Search the codebase directly for each category below.

Codebase Search (8 Categories)

For each category, search using grep, find, and file reading:

1. **Similar Implementations** — Find existing features that resemble the planned one. Look for analogous patterns, endpoints, components, or modules.

2. **Naming Conventions** — Identify how files, functions, variables, classes, and exports are named in the relevant area of the codebase.

3. **Error Handling** — Find how errors are caught, propagated, logged, and returned to users in similar code paths.

4. **Logging Patterns** — Identify what gets logged, at what level, and in what format.

5. **Type Definitions** — Find relevant types, interfaces, schemas, and how they're organized.

6. **Test Patterns** — Find how similar features are tested. Note test file locations, naming, setup/teardown patterns, and assertion styles.

7. **Configuration** — Find relevant config files, environment variables, and feature flags.

8. **Dependencies** — Identify packages, imports, and internal modules used by similar features.

Codebase Analysis (5 Traces)

Read relevant files to trace:

1. **Entry Points** — How does a request/action enter the system and reach the area you're modifying? 2. **Data Flow** — How does data move through the relevant code paths? 3. **State Changes** — What state is modified and where? 4. **Contracts** — What interfaces, APIs, or protocols must be honored? 5. **Patterns** — What architectural patterns are used (repository, service, controller, etc.)?

Unified Discovery Table

Compile findings into a single reference:

| Category | File:Lines | Pattern | Key Snippet | |---|---|---|---| | Naming | `src/services/userService.ts:1-5` | camelCase services, PascalCase types | `export class UserService` | | Error | `src/middleware/errorHandler.ts:10-25` | Custom AppError class | `throw new AppError(...)` | | ... | ... | ... | ... |

---

Phase 3 — RESEARCH

If the feature involves external libraries, APIs, or unfamiliar technology:

1. Search the web for official documentation 2. Find usage examples and best practices 3. Identify version-specific gotchas

Format each finding as:

KEY_INSIGHT: [what you learned]
APPLIES_TO: [which part of the plan this affects]
GOTCHA: [any warnings or version-specific issues]

If the feature uses only well-understood internal patterns, skip this phase and note: "No external research needed — feature uses established internal patterns."

---

Phase 4 — DESIGN

UX Transformation (if applicable)

Document the before/after user experience:

**Before:**

┌─────────────────────────────┐
│  [Current user experience]  │
│  Show the current flow,     │
│  what the user sees/does    │
└─────────────────────────────┘

**After:**

┌─────────────────────────────┐
│  [New