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:

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

1. Extract from the selected phase:

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

1. 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

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.

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

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

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

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

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

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

1. 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: