From c02d6e9f9435a4ee7926f132d848e9125137edb4 Mon Sep 17 00:00:00 2001 From: Matt Mo <28805779+supmo668@users.noreply.github.com> Date: Tue, 31 Mar 2026 14:12:23 -0700 Subject: [PATCH] feat: add PRP workflow commands adapted from PRPs-agentic-eng (#848) * feat: add PRP workflow commands adapted from PRPs-agentic-eng Add 5 new PRP workflow commands and extend 2 existing commands: New commands: - prp-prd.md: Interactive PRD generator with 8 phases - prp-plan.md: Deep implementation planning with codebase analysis - prp-implement.md: Plan executor with rigorous validation loops - prp-commit.md: Quick commit with natural language file targeting - prp-pr.md: GitHub PR creation from current branch Extended commands: - code-review.md: Added GitHub PR review mode alongside local review - plan.md: Added cross-reference to /prp-plan for deeper planning Adapted from PRPs-agentic-eng by Wirasm. Sub-agents remapped to inline Claude instructions. ECC conventions applied throughout (YAML frontmatter, Phase headings, tables, no XML tags). Artifacts stored in .claude/PRPs/{prds,plans,reports,reviews}/. * fix: address PR #848 review feedback - Remove external URLs from all 6 command files (keep attribution text) - Quote $ARGUMENTS in prp-implement.md to handle paths with spaces - Fix empty git add expansion in prp-commit.md (use xargs -r) - Rewrite sub-agent language in prp-prd.md as direct instructions - Fix code-review.md: add full-file fetch for PR reviews, replace || fallback chains with project-type detection, use proper GitHub API for inline review comments - Fix nested backticks in prp-plan.md Plan Template (use 4-backtick fence) - Clarify $ARGUMENTS parsing in prp-pr.md for base branch + flags - Fix fragile integration test pattern in prp-implement.md (proper PID tracking, wait-for-ready loop, clean shutdown) * fix: address second-pass review feedback on PR #848 - Add required 'side' field to GitHub review comments API call (code-review.md) - Replace GNU-only xargs -r with portable alternative (prp-commit.md) - Add failure check after server readiness timeout (prp-implement.md) - Fix unsafe word-splitting in file-fetch loop using read -r (code-review.md) - Make git reset pathspec tolerant of zero matches (prp-commit.md) - Quote PRD file path in cat command (prp-plan.md) - Fix plan filename placeholder inconsistency (prp-plan.md) - Add PR template directory scan before fixed-path fallbacks (prp-pr.md) --- commands/code-review.md | 269 +++++++++++++++++++- commands/plan.md | 2 + commands/prp-commit.md | 112 +++++++++ commands/prp-implement.md | 385 +++++++++++++++++++++++++++++ commands/prp-plan.md | 502 ++++++++++++++++++++++++++++++++++++++ commands/prp-pr.md | 184 ++++++++++++++ commands/prp-prd.md | 447 +++++++++++++++++++++++++++++++++ 7 files changed, 1891 insertions(+), 10 deletions(-) create mode 100644 commands/prp-commit.md create mode 100644 commands/prp-implement.md create mode 100644 commands/prp-plan.md create mode 100644 commands/prp-pr.md create mode 100644 commands/prp-prd.md diff --git a/commands/code-review.md b/commands/code-review.md index 6df0792f..e68d8e7e 100644 --- a/commands/code-review.md +++ b/commands/code-review.md @@ -1,10 +1,41 @@ +--- +description: Code review — local uncommitted changes or GitHub PR (pass PR number/URL for PR mode) +argument-hint: [pr-number | pr-url | blank for local review] +--- + # Code Review -Comprehensive security and quality review of uncommitted changes: +> PR review mode adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series. -1. Get changed files: git diff --name-only HEAD +**Input**: $ARGUMENTS -2. For each changed file, check for: +--- + +## Mode Selection + +If `$ARGUMENTS` contains a PR number, PR URL, or `--pr`: +→ Jump to **PR Review Mode** below. + +Otherwise: +→ Use **Local Review Mode**. + +--- + +## Local Review Mode + +Comprehensive security and quality review of uncommitted changes. + +### Phase 1 — GATHER + +```bash +git diff --name-only HEAD +``` + +If no changed files, stop: "Nothing to review." + +### Phase 2 — REVIEW + +Read each changed file in full. Check for: **Security Issues (CRITICAL):** - Hardcoded credentials, API keys, tokens @@ -29,12 +60,230 @@ Comprehensive security and quality review of uncommitted changes: - Missing tests for new code - Accessibility issues (a11y) -3. Generate report with: - - Severity: CRITICAL, HIGH, MEDIUM, LOW - - File location and line numbers - - Issue description - - Suggested fix +### Phase 3 — REPORT -4. Block commit if CRITICAL or HIGH issues found +Generate report with: +- Severity: CRITICAL, HIGH, MEDIUM, LOW +- File location and line numbers +- Issue description +- Suggested fix -Never approve code with security vulnerabilities! +Block commit if CRITICAL or HIGH issues found. +Never approve code with security vulnerabilities. + +--- + +## PR Review Mode + +Comprehensive GitHub PR review — fetches diff, reads full files, runs validation, posts review. + +### Phase 1 — FETCH + +Parse input to determine PR: + +| Input | Action | +|---|---| +| Number (e.g. `42`) | Use as PR number | +| URL (`github.com/.../pull/42`) | Extract PR number | +| Branch name | Find PR via `gh pr list --head ` | + +```bash +gh pr view --json number,title,body,author,baseRefName,headRefName,changedFiles,additions,deletions +gh pr diff +``` + +If PR not found, stop with error. Store PR metadata for later phases. + +### Phase 2 — CONTEXT + +Build review context: + +1. **Project rules** — Read `CLAUDE.md`, `.claude/docs/`, and any contributing guidelines +2. **PRP artifacts** — Check `.claude/PRPs/reports/` and `.claude/PRPs/plans/` for implementation context related to this PR +3. **PR intent** — Parse PR description for goals, linked issues, test plans +4. **Changed files** — List all modified files and categorize by type (source, test, config, docs) + +### Phase 3 — REVIEW + +Read each changed file **in full** (not just the diff hunks — you need surrounding context). + +For PR reviews, fetch the full file contents at the PR head revision: +```bash +gh pr diff --name-only | while IFS= read -r file; do + gh api "repos/{owner}/{repo}/contents/$file?ref=" --jq '.content' | base64 -d +done +``` + +Apply the review checklist across 7 categories: + +| Category | What to Check | +|---|---| +| **Correctness** | Logic errors, off-by-ones, null handling, edge cases, race conditions | +| **Type Safety** | Type mismatches, unsafe casts, `any` usage, missing generics | +| **Pattern Compliance** | Matches project conventions (naming, file structure, error handling, imports) | +| **Security** | Injection, auth gaps, secret exposure, SSRF, path traversal, XSS | +| **Performance** | N+1 queries, missing indexes, unbounded loops, memory leaks, large payloads | +| **Completeness** | Missing tests, missing error handling, incomplete migrations, missing docs | +| **Maintainability** | Dead code, magic numbers, deep nesting, unclear naming, missing types | + +Assign severity to each finding: + +| Severity | Meaning | Action | +|---|---|---| +| **CRITICAL** | Security vulnerability or data loss risk | Must fix before merge | +| **HIGH** | Bug or logic error likely to cause issues | Should fix before merge | +| **MEDIUM** | Code quality issue or missing best practice | Fix recommended | +| **LOW** | Style nit or minor suggestion | Optional | + +### Phase 4 — VALIDATE + +Run available validation commands: + +Detect the project type from config files (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.), then run the appropriate commands: + +**Node.js / TypeScript** (has `package.json`): +```bash +npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null # Type check +npm run lint # Lint +npm test # Tests +npm run build # Build +``` + +**Rust** (has `Cargo.toml`): +```bash +cargo clippy -- -D warnings # Lint +cargo test # Tests +cargo build # Build +``` + +**Go** (has `go.mod`): +```bash +go vet ./... # Lint +go test ./... # Tests +go build ./... # Build +``` + +**Python** (has `pyproject.toml` / `setup.py`): +```bash +pytest # Tests +``` + +Run only the commands that apply to the detected project type. Record pass/fail for each. + +### Phase 5 — DECIDE + +Form recommendation based on findings: + +| Condition | Decision | +|---|---| +| Zero CRITICAL/HIGH issues, validation passes | **APPROVE** | +| Only MEDIUM/LOW issues, validation passes | **APPROVE** with comments | +| Any HIGH issues or validation failures | **REQUEST CHANGES** | +| Any CRITICAL issues | **BLOCK** — must fix before merge | + +Special cases: +- Draft PR → Always use **COMMENT** (not approve/block) +- Only docs/config changes → Lighter review, focus on correctness +- Explicit `--approve` or `--request-changes` flag → Override decision (but still report all findings) + +### Phase 6 — REPORT + +Create review artifact at `.claude/PRPs/reviews/pr--review.md`: + +```markdown +# PR Review: # — + +**Reviewed**: <date> +**Author**: <author> +**Branch**: <head> → <base> +**Decision**: APPROVE | REQUEST CHANGES | BLOCK + +## Summary +<1-2 sentence overall assessment> + +## Findings + +### CRITICAL +<findings or "None"> + +### HIGH +<findings or "None"> + +### MEDIUM +<findings or "None"> + +### LOW +<findings or "None"> + +## Validation Results + +| Check | Result | +|---|---| +| Type check | ✅ Pass / ❌ Fail / ⏭️ Skipped | +| Lint | ✅ / ❌ / ⏭️ | +| Tests | ✅ / ❌ / ⏭️ | +| Build | ✅ / ❌ / ⏭️ | + +## Files Reviewed +<list of files with change type: Added/Modified/Deleted> +``` + +### Phase 7 — PUBLISH + +Post the review to GitHub: + +```bash +# If APPROVE +gh pr review <NUMBER> --approve --body "<summary of review>" + +# If REQUEST CHANGES +gh pr review <NUMBER> --request-changes --body "<summary with required fixes>" + +# If COMMENT only (draft PR or informational) +gh pr review <NUMBER> --comment --body "<summary>" +``` + +For inline comments on specific lines, use the GitHub review comments API: +```bash +gh api "repos/{owner}/{repo}/pulls/<NUMBER>/comments" \ + -f body="<comment>" \ + -f path="<file>" \ + -F line=<line-number> \ + -f side="RIGHT" \ + -f commit_id="$(gh pr view <NUMBER> --json headRefOid --jq .headRefOid)" +``` + +Alternatively, post a single review with multiple inline comments at once: +```bash +gh api "repos/{owner}/{repo}/pulls/<NUMBER>/reviews" \ + -f event="COMMENT" \ + -f body="<overall summary>" \ + --input comments.json # [{"path": "file", "line": N, "body": "comment"}, ...] +``` + +### Phase 8 — OUTPUT + +Report to user: + +``` +PR #<NUMBER>: <TITLE> +Decision: <APPROVE|REQUEST_CHANGES|BLOCK> + +Issues: <critical_count> critical, <high_count> high, <medium_count> medium, <low_count> low +Validation: <pass_count>/<total_count> checks passed + +Artifacts: + Review: .claude/PRPs/reviews/pr-<NUMBER>-review.md + GitHub: <PR URL> + +Next steps: + - <contextual suggestions based on decision> +``` + +--- + +## Edge Cases + +- **No `gh` CLI**: Fall back to local-only review (read the diff, skip GitHub publish). Warn user. +- **Diverged branches**: Suggest `git fetch origin && git rebase origin/<base>` before review. +- **Large PRs (>50 files)**: Warn about review scope. Focus on source changes first, then tests, then config/docs. diff --git a/commands/plan.md b/commands/plan.md index 198ea5a4..76090291 100644 --- a/commands/plan.md +++ b/commands/plan.md @@ -107,6 +107,8 @@ After planning: - Use `/build-fix` if build errors occur - Use `/code-review` to review completed implementation +> **Need deeper planning?** Use `/prp-plan` for artifact-producing planning with PRD integration, codebase analysis, and pattern extraction. Use `/prp-implement` to execute those plans with rigorous validation loops. + ## Related Agents This command invokes the `planner` agent provided by ECC. diff --git a/commands/prp-commit.md b/commands/prp-commit.md new file mode 100644 index 00000000..5a9c0763 --- /dev/null +++ b/commands/prp-commit.md @@ -0,0 +1,112 @@ +--- +description: Quick commit with natural language file targeting — describe what to commit in plain English +argument-hint: [target description] (blank = all changes) +--- + +# Smart Commit + +> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series. + +**Input**: $ARGUMENTS + +--- + +## Phase 1 — ASSESS + +```bash +git status --short +``` + +If output is empty → stop: "Nothing to commit." + +Show the user a summary of what's changed (added, modified, deleted, untracked). + +--- + +## Phase 2 — INTERPRET & STAGE + +Interpret `$ARGUMENTS` to determine what to stage: + +| Input | Interpretation | Git Command | +|---|---|---| +| *(blank / empty)* | Stage everything | `git add -A` | +| `staged` | Use whatever is already staged | *(no git add)* | +| `*.ts` or `*.py` etc. | Stage matching glob | `git add '*.ts'` | +| `except tests` | Stage all, then unstage tests | `git add -A && git reset -- '**/*.test.*' '**/*.spec.*' '**/test_*' 2>/dev/null \|\| true` | +| `only new files` | Stage untracked files only | `git ls-files --others --exclude-standard \| grep . && git ls-files --others --exclude-standard \| xargs git add` | +| `the auth changes` | Interpret from status/diff — find auth-related files | `git add <matched files>` | +| Specific filenames | Stage those files | `git add <files>` | + +For natural language inputs (like "the auth changes"), cross-reference the `git status` output and `git diff` to identify relevant files. Show the user which files you're staging and why. + +```bash +git add <determined files> +``` + +After staging, verify: +```bash +git diff --cached --stat +``` + +If nothing staged, stop: "No files matched your description." + +--- + +## Phase 3 — COMMIT + +Craft a single-line commit message in imperative mood: + +``` +{type}: {description} +``` + +Types: +- `feat` — New feature or capability +- `fix` — Bug fix +- `refactor` — Code restructuring without behavior change +- `docs` — Documentation changes +- `test` — Adding or updating tests +- `chore` — Build, config, dependencies +- `perf` — Performance improvement +- `ci` — CI/CD changes + +Rules: +- Imperative mood ("add feature" not "added feature") +- Lowercase after the type prefix +- No period at the end +- Under 72 characters +- Describe WHAT changed, not HOW + +```bash +git commit -m "{type}: {description}" +``` + +--- + +## Phase 4 — OUTPUT + +Report to user: + +``` +Committed: {hash_short} +Message: {type}: {description} +Files: {count} file(s) changed + +Next steps: + - git push → push to remote + - /prp-pr → create a pull request + - /code-review → review before pushing +``` + +--- + +## Examples + +| You say | What happens | +|---|---| +| `/prp-commit` | Stages all, auto-generates message | +| `/prp-commit staged` | Commits only what's already staged | +| `/prp-commit *.ts` | Stages all TypeScript files, commits | +| `/prp-commit except tests` | Stages everything except test files | +| `/prp-commit the database migration` | Finds DB migration files from status, stages them | +| `/prp-commit only new files` | Stages untracked files only | diff --git a/commands/prp-implement.md b/commands/prp-implement.md new file mode 100644 index 00000000..67777c66 --- /dev/null +++ b/commands/prp-implement.md @@ -0,0 +1,385 @@ +--- +description: Execute an implementation plan with rigorous validation loops +argument-hint: <path/to/plan.md> +--- + +> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series. + +# PRP Implement + +Execute a plan file step-by-step with continuous validation. Every change is verified immediately — never accumulate broken state. + +**Core Philosophy**: Validation loops catch mistakes early. Run checks after every change. Fix issues immediately. + +**Golden Rule**: If a validation fails, fix it before moving on. Never accumulate broken state. + +--- + +## Phase 0 — DETECT + +### Package Manager Detection + +| File Exists | Package Manager | Runner | +|---|---|---| +| `bun.lockb` | bun | `bun run` | +| `pnpm-lock.yaml` | pnpm | `pnpm run` | +| `yarn.lock` | yarn | `yarn` | +| `package-lock.json` | npm | `npm run` | +| `pyproject.toml` or `requirements.txt` | uv / pip | `uv run` or `python -m` | +| `Cargo.toml` | cargo | `cargo` | +| `go.mod` | go | `go` | + +### Validation Scripts + +Check `package.json` (or equivalent) for available scripts: + +```bash +# For Node.js projects +cat package.json | grep -A 20 '"scripts"' +``` + +Note available commands for: type-check, lint, test, build. + +--- + +## Phase 1 — LOAD + +Read the plan file: + +```bash +cat "$ARGUMENTS" +``` + +Extract these sections from the plan: +- **Summary** — What is being built +- **Patterns to Mirror** — Code conventions to follow +- **Files to Change** — What to create or modify +- **Step-by-Step Tasks** — Implementation sequence +- **Validation Commands** — How to verify correctness +- **Acceptance Criteria** — Definition of done + +If the file doesn't exist or isn't a valid plan: +``` +Error: Plan file not found or invalid. +Run /prp-plan <feature-description> to create a plan first. +``` + +**CHECKPOINT**: Plan loaded. All sections identified. Tasks extracted. + +--- + +## Phase 2 — PREPARE + +### Git State + +```bash +git branch --show-current +git status --porcelain +``` + +### Branch Decision + +| Current State | Action | +|---|---| +| On feature branch | Use current branch | +| On main, clean working tree | Create feature branch: `git checkout -b feat/{plan-name}` | +| On main, dirty working tree | **STOP** — Ask user to stash or commit first | +| In a git worktree for this feature | Use the worktree | + +### Sync Remote + +```bash +git pull --rebase origin $(git branch --show-current) 2>/dev/null || true +``` + +**CHECKPOINT**: On correct branch. Working tree ready. Remote synced. + +--- + +## Phase 3 — EXECUTE + +Process each task from the plan sequentially. + +### Per-Task Loop + +For each task in **Step-by-Step Tasks**: + +1. **Read MIRROR reference** — Open the pattern file referenced in the task's MIRROR field. Understand the convention before writing code. + +2. **Implement** — Write the code following the pattern exactly. Apply GOTCHA warnings. Use specified IMPORTS. + +3. **Validate immediately** — After EVERY file change: + ```bash + # Run type-check (adjust command per project) + [type-check command from Phase 0] + ``` + If type-check fails → fix the error before moving to the next file. + +4. **Track progress** — Log: `✅ Task N: [task name] — complete` + +### Handling Deviations + +If implementation must deviate from the plan: +- Note **WHAT** changed +- Note **WHY** it changed +- Continue with the corrected approach +- These deviations will be captured in the report + +**CHECKPOINT**: All tasks executed. Deviations logged. + +--- + +## Phase 4 — VALIDATE + +Run all validation levels from the plan. Fix issues at each level before proceeding. + +### Level 1: Static Analysis + +```bash +# Type checking — zero errors required +[project type-check command] + +# Linting — fix automatically where possible +[project lint command] +[project lint-fix command] +``` + +If lint errors remain after auto-fix, fix manually. + +### Level 2: Unit Tests + +Write tests for every new function (as specified in the plan's Testing Strategy). + +```bash +[project test command for affected area] +``` + +- Every function needs at least one test +- Cover edge cases listed in the plan +- If a test fails → fix the implementation (not the test, unless the test is wrong) + +### Level 3: Build Check + +```bash +[project build command] +``` + +Build must succeed with zero errors. + +### Level 4: Integration Testing (if applicable) + +```bash +# Start server, run tests, stop server +[project dev server command] & +SERVER_PID=$! + +# Wait for server to be ready (adjust port as needed) +SERVER_READY=0 +for i in $(seq 1 30); do + if curl -sf http://localhost:PORT/health >/dev/null 2>&1; then + SERVER_READY=1 + break + fi + sleep 1 +done + +if [ "$SERVER_READY" -ne 1 ]; then + kill "$SERVER_PID" 2>/dev/null || true + echo "ERROR: Server failed to start within 30s" >&2 + exit 1 +fi + +[integration test command] +TEST_EXIT=$? + +kill "$SERVER_PID" 2>/dev/null || true +wait "$SERVER_PID" 2>/dev/null || true + +exit "$TEST_EXIT" +``` + +### Level 5: Edge Case Testing + +Run through edge cases from the plan's Testing Strategy checklist. + +**CHECKPOINT**: All 5 validation levels pass. Zero errors. + +--- + +## Phase 5 — REPORT + +### Create Implementation Report + +```bash +mkdir -p .claude/PRPs/reports +``` + +Write report to `.claude/PRPs/reports/{plan-name}-report.md`: + +```markdown +# Implementation Report: [Feature Name] + +## Summary +[What was implemented] + +## Assessment vs Reality + +| Metric | Predicted (Plan) | Actual | +|---|---|---| +| Complexity | [from plan] | [actual] | +| Confidence | [from plan] | [actual] | +| Files Changed | [from plan] | [actual count] | + +## Tasks Completed + +| # | Task | Status | Notes | +|---|---|---|---| +| 1 | [task name] | ✅ Complete | | +| 2 | [task name] | ✅ Complete | Deviated — [reason] | + +## Validation Results + +| Level | Status | Notes | +|---|---|---| +| Static Analysis | ✅ Pass | | +| Unit Tests | ✅ Pass | N tests written | +| Build | ✅ Pass | | +| Integration | ✅ Pass | or N/A | +| Edge Cases | ✅ Pass | | + +## Files Changed + +| File | Action | Lines | +|---|---|---| +| `path/to/file` | CREATED | +N | +| `path/to/file` | UPDATED | +N / -M | + +## Deviations from Plan +[List any deviations with WHAT and WHY, or "None"] + +## Issues Encountered +[List any problems and how they were resolved, or "None"] + +## Tests Written + +| Test File | Tests | Coverage | +|---|---|---| +| `path/to/test` | N tests | [area covered] | + +## Next Steps +- [ ] Code review via `/code-review` +- [ ] Create PR via `/prp-pr` +``` + +### Update PRD (if applicable) + +If this implementation was for a PRD phase: +1. Update the phase status from `in-progress` to `complete` +2. Add report path as reference + +### Archive Plan + +```bash +mkdir -p .claude/PRPs/plans/completed +mv "$ARGUMENTS" .claude/PRPs/plans/completed/ +``` + +**CHECKPOINT**: Report created. PRD updated. Plan archived. + +--- + +## Phase 6 — OUTPUT + +Report to user: + +``` +## Implementation Complete + +- **Plan**: [plan file path] → archived to completed/ +- **Branch**: [current branch name] +- **Status**: ✅ All tasks complete + +### Validation Summary + +| Check | Status | +|---|---| +| Type Check | ✅ | +| Lint | ✅ | +| Tests | ✅ (N written) | +| Build | ✅ | +| Integration | ✅ or N/A | + +### Files Changed +- [N] files created, [M] files updated + +### Deviations +[Summary or "None — implemented exactly as planned"] + +### Artifacts +- Report: `.claude/PRPs/reports/{name}-report.md` +- Archived Plan: `.claude/PRPs/plans/completed/{name}.plan.md` + +### PRD Progress (if applicable) +| Phase | Status | +|---|---| +| Phase 1 | ✅ Complete | +| Phase 2 | ⏳ Next | +| ... | ... | + +> Next step: Run `/prp-pr` to create a pull request, or `/code-review` to review changes first. +``` + +--- + +## Handling Failures + +### Type Check Fails +1. Read the error message carefully +2. Fix the type error in the source file +3. Re-run type-check +4. Continue only when clean + +### Tests Fail +1. Identify whether the bug is in the implementation or the test +2. Fix the root cause (usually the implementation) +3. Re-run tests +4. Continue only when green + +### Lint Fails +1. Run auto-fix first +2. If errors remain, fix manually +3. Re-run lint +4. Continue only when clean + +### Build Fails +1. Usually a type or import issue — check error message +2. Fix the offending file +3. Re-run build +4. Continue only when successful + +### Integration Test Fails +1. Check server started correctly +2. Verify endpoint/route exists +3. Check request format matches expected +4. Fix and re-run + +--- + +## Success Criteria + +- **TASKS_COMPLETE**: All tasks from the plan executed +- **TYPES_PASS**: Zero type errors +- **LINT_PASS**: Zero lint errors +- **TESTS_PASS**: All tests green, new tests written +- **BUILD_PASS**: Build succeeds +- **REPORT_CREATED**: Implementation report saved +- **PLAN_ARCHIVED**: Plan moved to `completed/` + +--- + +## Next Steps + +- Run `/code-review` to review changes before committing +- Run `/prp-commit` to commit with a descriptive message +- Run `/prp-pr` to create a pull request +- Run `/prp-plan <next-phase>` if the PRD has more phases diff --git a/commands/prp-plan.md b/commands/prp-plan.md new file mode 100644 index 00000000..7d7e06c4 --- /dev/null +++ b/commands/prp-plan.md @@ -0,0 +1,502 @@ +--- +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 user experience] │ +│ Show the improved flow, │ +│ what changes for the user │ +└─────────────────────────────┘ +``` + +### Interaction Changes + +| Touchpoint | Before | After | Notes | +|---|---|---|---| +| ... | ... | ... | ... | + +If the feature is purely backend/internal with no UX change, note: "Internal change — no user-facing UX transformation." + +--- + +## Phase 5 — ARCHITECT + +### Strategic Design + +Define the implementation approach: + +- **Approach**: High-level strategy (e.g., "Add new service layer following existing repository pattern") +- **Alternatives Considered**: What other approaches were evaluated and why they were rejected +- **Scope**: Concrete boundaries of what WILL be built +- **NOT Building**: Explicit list of what is OUT OF SCOPE (prevents scope creep during implementation) + +--- + +## Phase 6 — GENERATE + +Write the full plan document using the template below. Save to `.claude/PRPs/plans/{kebab-case-feature-name}.plan.md`. + +Create the directory if it doesn't exist: +```bash +mkdir -p .claude/PRPs/plans +``` + +### Plan Template + +````markdown +# Plan: [Feature Name] + +## Summary +[2-3 sentence overview] + +## User Story +As a [user], I want [capability], so that [benefit]. + +## Problem → Solution +[Current state] → [Desired state] + +## Metadata +- **Complexity**: [Small | Medium | Large | XL] +- **Source PRD**: [path or "N/A"] +- **PRD Phase**: [phase name or "N/A"] +- **Estimated Files**: [count] + +--- + +## UX Design + +### Before +[ASCII diagram or "N/A — internal change"] + +### After +[ASCII diagram or "N/A — internal change"] + +### Interaction Changes +| Touchpoint | Before | After | Notes | +|---|---|---|---| + +--- + +## Mandatory Reading + +Files that MUST be read before implementing: + +| Priority | File | Lines | Why | +|---|---|---|---| +| P0 (critical) | `path/to/file` | 1-50 | Core pattern to follow | +| P1 (important) | `path/to/file` | 10-30 | Related types | +| P2 (reference) | `path/to/file` | all | Similar implementation | + +## External Documentation + +| Topic | Source | Key Takeaway | +|---|---|---| +| ... | ... | ... | + +--- + +## Patterns to Mirror + +Code patterns discovered in the codebase. Follow these exactly. + +### NAMING_CONVENTION +// SOURCE: [file:lines] +[actual code snippet showing the naming pattern] + +### ERROR_HANDLING +// SOURCE: [file:lines] +[actual code snippet showing error handling] + +### LOGGING_PATTERN +// SOURCE: [file:lines] +[actual code snippet showing logging] + +### REPOSITORY_PATTERN +// SOURCE: [file:lines] +[actual code snippet showing data access] + +### SERVICE_PATTERN +// SOURCE: [file:lines] +[actual code snippet showing service layer] + +### TEST_STRUCTURE +// SOURCE: [file:lines] +[actual code snippet showing test setup] + +--- + +## Files to Change + +| File | Action | Justification | +|---|---|---| +| `path/to/file.ts` | CREATE | New service for feature | +| `path/to/existing.ts` | UPDATE | Add new method | + +## NOT Building + +- [Explicit item 1 that is out of scope] +- [Explicit item 2 that is out of scope] + +--- + +## Step-by-Step Tasks + +### Task 1: [Name] +- **ACTION**: [What to do] +- **IMPLEMENT**: [Specific code/logic to write] +- **MIRROR**: [Pattern from Patterns to Mirror section to follow] +- **IMPORTS**: [Required imports] +- **GOTCHA**: [Known pitfall to avoid] +- **VALIDATE**: [How to verify this task is correct] + +### Task 2: [Name] +- **ACTION**: ... +- **IMPLEMENT**: ... +- **MIRROR**: ... +- **IMPORTS**: ... +- **GOTCHA**: ... +- **VALIDATE**: ... + +[Continue for all tasks...] + +--- + +## Testing Strategy + +### Unit Tests + +| Test | Input | Expected Output | Edge Case? | +|---|---|---|---| +| ... | ... | ... | ... | + +### Edge Cases Checklist +- [ ] Empty input +- [ ] Maximum size input +- [ ] Invalid types +- [ ] Concurrent access +- [ ] Network failure (if applicable) +- [ ] Permission denied + +--- + +## Validation Commands + +### Static Analysis +```bash +# Run type checker +[project-specific type check command] +``` +EXPECT: Zero type errors + +### Unit Tests +```bash +# Run tests for affected area +[project-specific test command] +``` +EXPECT: All tests pass + +### Full Test Suite +```bash +# Run complete test suite +[project-specific full test command] +``` +EXPECT: No regressions + +### Database Validation (if applicable) +```bash +# Verify schema/migrations +[project-specific db command] +``` +EXPECT: Schema up to date + +### Browser Validation (if applicable) +```bash +# Start dev server and verify +[project-specific dev server command] +``` +EXPECT: Feature works as designed + +### Manual Validation +- [ ] [Step-by-step manual verification checklist] + +--- + +## Acceptance Criteria +- [ ] All tasks completed +- [ ] All validation commands pass +- [ ] Tests written and passing +- [ ] No type errors +- [ ] No lint errors +- [ ] Matches UX design (if applicable) + +## Completion Checklist +- [ ] Code follows discovered patterns +- [ ] Error handling matches codebase style +- [ ] Logging follows codebase conventions +- [ ] Tests follow test patterns +- [ ] No hardcoded values +- [ ] Documentation updated (if needed) +- [ ] No unnecessary scope additions +- [ ] Self-contained — no questions needed during implementation + +## Risks +| Risk | Likelihood | Impact | Mitigation | +|---|---|---|---| +| ... | ... | ... | ... | + +## Notes +[Any additional context, decisions, or observations] +``` + +--- + +## Output + +### Save the Plan + +Write the generated plan to: +``` +.claude/PRPs/plans/{kebab-case-feature-name}.plan.md +``` + +### Update PRD (if input was a PRD) + +If this plan was generated from a PRD phase: +1. Update the phase status from `pending` to `in-progress` +2. Add the plan file path as a reference in the phase + +### Report to User + +``` +## Plan Created + +- **File**: .claude/PRPs/plans/{kebab-case-feature-name}.plan.md +- **Source PRD**: [path or "N/A"] +- **Phase**: [phase name or "standalone"] +- **Complexity**: [level] +- **Scope**: [N files, M tasks] +- **Key Patterns**: [top 3 discovered patterns] +- **External Research**: [topics researched or "none needed"] +- **Risks**: [top risk or "none identified"] +- **Confidence Score**: [1-10] — likelihood of single-pass implementation + +> Next step: Run `/prp-implement .claude/PRPs/plans/{name}.plan.md` to execute this plan. +``` + +--- + +## Verification + +Before finalizing, verify the plan against these checklists: + +### Context Completeness +- [ ] All relevant files discovered and documented +- [ ] Naming conventions captured with examples +- [ ] Error handling patterns documented +- [ ] Test patterns identified +- [ ] Dependencies listed + +### Implementation Readiness +- [ ] Every task has ACTION, IMPLEMENT, MIRROR, and VALIDATE +- [ ] No task requires additional codebase searching +- [ ] Import paths are specified +- [ ] GOTCHAs documented where applicable + +### Pattern Faithfulness +- [ ] Code snippets are actual codebase examples (not invented) +- [ ] SOURCE references point to real files and line numbers +- [ ] Patterns cover naming, errors, logging, data access, and tests +- [ ] New code will be indistinguishable from existing code + +### Validation Coverage +- [ ] Static analysis commands specified +- [ ] Test commands specified +- [ ] Build verification included + +### UX Clarity +- [ ] Before/after states documented (or marked N/A) +- [ ] Interaction changes listed +- [ ] Edge cases for UX identified + +### No Prior Knowledge Test +A developer unfamiliar with this codebase should be able to implement the feature using ONLY this plan, without searching the codebase or asking questions. If not, add the missing context. + +--- + +## Next Steps + +- Run `/prp-implement <plan-path>` to execute this plan +- Run `/plan` for quick conversational planning without artifacts +- Run `/prp-prd` to create a PRD first if scope is unclear +```` diff --git a/commands/prp-pr.md b/commands/prp-pr.md new file mode 100644 index 00000000..41fe455d --- /dev/null +++ b/commands/prp-pr.md @@ -0,0 +1,184 @@ +--- +description: Create a GitHub PR from current branch with unpushed commits — discovers templates, analyzes changes, pushes +argument-hint: [base-branch] (default: main) +--- + +# Create Pull Request + +> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series. + +**Input**: `$ARGUMENTS` — optional, may contain a base branch name and/or flags (e.g., `--draft`). + +**Parse `$ARGUMENTS`**: +- Extract any recognized flags (`--draft`) +- Treat remaining non-flag text as the base branch name +- Default base branch to `main` if none specified + +--- + +## Phase 1 — VALIDATE + +Check preconditions: + +```bash +git branch --show-current +git status --short +git log origin/<base>..HEAD --oneline +``` + +| Check | Condition | Action if Failed | +|---|---|---| +| Not on base branch | Current branch ≠ base | Stop: "Switch to a feature branch first." | +| Clean working directory | No uncommitted changes | Warn: "You have uncommitted changes. Commit or stash first. Use `/prp-commit` to commit." | +| Has commits ahead | `git log origin/<base>..HEAD` not empty | Stop: "No commits ahead of `<base>`. Nothing to PR." | +| No existing PR | `gh pr list --head <branch> --json number` is empty | Stop: "PR already exists: #<number>. Use `gh pr view <number> --web` to open it." | + +If all checks pass, proceed. + +--- + +## Phase 2 — DISCOVER + +### PR Template + +Search for PR template in order: + +1. `.github/PULL_REQUEST_TEMPLATE/` directory — if exists, list files and let user choose (or use `default.md`) +2. `.github/PULL_REQUEST_TEMPLATE.md` +3. `.github/pull_request_template.md` +4. `docs/pull_request_template.md` + +If found, read it and use its structure for the PR body. + +### Commit Analysis + +```bash +git log origin/<base>..HEAD --format="%h %s" --reverse +``` + +Analyze commits to determine: +- **PR title**: Use conventional commit format with type prefix — `feat: ...`, `fix: ...`, etc. + - If multiple types, use the dominant one + - If single commit, use its message as-is +- **Change summary**: Group commits by type/area + +### File Analysis + +```bash +git diff origin/<base>..HEAD --stat +git diff origin/<base>..HEAD --name-only +``` + +Categorize changed files: source, tests, docs, config, migrations. + +### PRP Artifacts + +Check for related PRP artifacts: +- `.claude/PRPs/reports/` — Implementation reports +- `.claude/PRPs/plans/` — Plans that were executed +- `.claude/PRPs/prds/` — Related PRDs + +Reference these in the PR body if they exist. + +--- + +## Phase 3 — PUSH + +```bash +git push -u origin HEAD +``` + +If push fails due to divergence: +```bash +git fetch origin +git rebase origin/<base> +git push -u origin HEAD +``` + +If rebase conflicts occur, stop and inform the user. + +--- + +## Phase 4 — CREATE + +### With Template + +If a PR template was found in Phase 2, fill in each section using the commit and file analysis. Preserve all template sections — leave sections as "N/A" if not applicable rather than removing them. + +### Without Template + +Use this default format: + +```markdown +## Summary + +<1-2 sentence description of what this PR does and why> + +## Changes + +<bulleted list of changes grouped by area> + +## Files Changed + +<table or list of changed files with change type: Added/Modified/Deleted> + +## Testing + +<description of how changes were tested, or "Needs testing"> + +## Related Issues + +<linked issues with Closes/Fixes/Relates to #N, or "None"> +``` + +### Create the PR + +```bash +gh pr create \ + --title "<PR title>" \ + --base <base-branch> \ + --body "<PR body>" + # Add --draft if the --draft flag was parsed from $ARGUMENTS +``` + +--- + +## Phase 5 — VERIFY + +```bash +gh pr view --json number,url,title,state,baseRefName,headRefName,additions,deletions,changedFiles +gh pr checks --json name,status,conclusion 2>/dev/null || true +``` + +--- + +## Phase 6 — OUTPUT + +Report to user: + +``` +PR #<number>: <title> +URL: <url> +Branch: <head> → <base> +Changes: +<additions> -<deletions> across <changedFiles> files + +CI Checks: <status summary or "pending" or "none configured"> + +Artifacts referenced: + - <any PRP reports/plans linked in PR body> + +Next steps: + - gh pr view <number> --web → open in browser + - /code-review <number> → review the PR + - gh pr merge <number> → merge when ready +``` + +--- + +## Edge Cases + +- **No `gh` CLI**: Stop with: "GitHub CLI (`gh`) is required. Install: https://cli.github.com/" +- **Not authenticated**: Stop with: "Run `gh auth login` first." +- **Force push needed**: If remote has diverged and rebase was done, use `git push --force-with-lease` (never `--force`). +- **Multiple PR templates**: If `.github/PULL_REQUEST_TEMPLATE/` has multiple files, list them and ask user to choose. +- **Large PR (>20 files)**: Warn about PR size. Suggest splitting if changes are logically separable. diff --git a/commands/prp-prd.md b/commands/prp-prd.md new file mode 100644 index 00000000..969fdc3a --- /dev/null +++ b/commands/prp-prd.md @@ -0,0 +1,447 @@ +--- +description: Interactive PRD generator - problem-first, hypothesis-driven product spec with back-and-forth questioning +argument-hint: [feature/product idea] (blank = start with questions) +--- + +# Product Requirements Document Generator + +> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series. + +**Input**: $ARGUMENTS + +--- + +## Your Role + +You are a sharp product manager who: +- Starts with PROBLEMS, not solutions +- Demands evidence before building +- Thinks in hypotheses, not specs +- Asks clarifying questions before assuming +- Acknowledges uncertainty honestly + +**Anti-pattern**: Don't fill sections with fluff. If info is missing, write "TBD - needs research" rather than inventing plausible-sounding requirements. + +--- + +## Process Overview + +``` +QUESTION SET 1 → GROUNDING → QUESTION SET 2 → RESEARCH → QUESTION SET 3 → GENERATE +``` + +Each question set builds on previous answers. Grounding phases validate assumptions. + +--- + +## Phase 1: INITIATE - Core Problem + +**If no input provided**, ask: + +> **What do you want to build?** +> Describe the product, feature, or capability in a few sentences. + +**If input provided**, confirm understanding by restating: + +> I understand you want to build: {restated understanding} +> Is this correct, or should I adjust my understanding? + +**GATE**: Wait for user response before proceeding. + +--- + +## Phase 2: FOUNDATION - Problem Discovery + +Ask these questions (present all at once, user can answer together): + +> **Foundation Questions:** +> +> 1. **Who** has this problem? Be specific - not just "users" but what type of person/role? +> +> 2. **What** problem are they facing? Describe the observable pain, not the assumed need. +> +> 3. **Why** can't they solve it today? What alternatives exist and why do they fail? +> +> 4. **Why now?** What changed that makes this worth building? +> +> 5. **How** will you know if you solved it? What would success look like? + +**GATE**: Wait for user responses before proceeding. + +--- + +## Phase 3: GROUNDING - Market & Context Research + +After foundation answers, conduct research: + +**Research market context:** + +1. Find similar products/features in the market +2. Identify how competitors solve this problem +3. Note common patterns and anti-patterns +4. Check for recent trends or changes in this space + +Compile findings with direct links, key insights, and any gaps in available information. + +**If a codebase exists, explore it in parallel:** + +1. Find existing functionality relevant to the product/feature idea +2. Identify patterns that could be leveraged +3. Note technical constraints or opportunities + +Record file locations, code patterns, and conventions observed. + +**Summarize findings to user:** + +> **What I found:** +> - {Market insight 1} +> - {Competitor approach} +> - {Relevant pattern from codebase, if applicable} +> +> Does this change or refine your thinking? + +**GATE**: Brief pause for user input (can be "continue" or adjustments). + +--- + +## Phase 4: DEEP DIVE - Vision & Users + +Based on foundation + research, ask: + +> **Vision & Users:** +> +> 1. **Vision**: In one sentence, what's the ideal end state if this succeeds wildly? +> +> 2. **Primary User**: Describe your most important user - their role, context, and what triggers their need. +> +> 3. **Job to Be Done**: Complete this: "When [situation], I want to [motivation], so I can [outcome]." +> +> 4. **Non-Users**: Who is explicitly NOT the target? Who should we ignore? +> +> 5. **Constraints**: What limitations exist? (time, budget, technical, regulatory) + +**GATE**: Wait for user responses before proceeding. + +--- + +## Phase 5: GROUNDING - Technical Feasibility + +**If a codebase exists, perform two parallel investigations:** + +Investigation 1 — Explore feasibility: +1. Identify existing infrastructure that can be leveraged +2. Find similar patterns already implemented +3. Map integration points and dependencies +4. Locate relevant configuration and type definitions + +Record file locations, code patterns, and conventions observed. + +Investigation 2 — Analyze constraints: +1. Trace how existing related features are implemented end-to-end +2. Map data flow through potential integration points +3. Identify architectural patterns and boundaries +4. Estimate complexity based on similar features + +Document what exists with precise file:line references. No suggestions. + +**If no codebase, research technical approaches:** + +1. Find technical approaches others have used +2. Identify common implementation patterns +3. Note known technical challenges and pitfalls + +Compile findings with citations and gap analysis. + +**Summarize to user:** + +> **Technical Context:** +> - Feasibility: {HIGH/MEDIUM/LOW} because {reason} +> - Can leverage: {existing patterns/infrastructure} +> - Key technical risk: {main concern} +> +> Any technical constraints I should know about? + +**GATE**: Brief pause for user input. + +--- + +## Phase 6: DECISIONS - Scope & Approach + +Ask final clarifying questions: + +> **Scope & Approach:** +> +> 1. **MVP Definition**: What's the absolute minimum to test if this works? +> +> 2. **Must Have vs Nice to Have**: What 2-3 things MUST be in v1? What can wait? +> +> 3. **Key Hypothesis**: Complete this: "We believe [capability] will [solve problem] for [users]. We'll know we're right when [measurable outcome]." +> +> 4. **Out of Scope**: What are you explicitly NOT building (even if users ask)? +> +> 5. **Open Questions**: What uncertainties could change the approach? + +**GATE**: Wait for user responses before generating. + +--- + +## Phase 7: GENERATE - Write PRD + +**Output path**: `.claude/PRPs/prds/{kebab-case-name}.prd.md` + +Create directory if needed: `mkdir -p .claude/PRPs/prds` + +### PRD Template + +```markdown +# {Product/Feature Name} + +## Problem Statement + +{2-3 sentences: Who has what problem, and what's the cost of not solving it?} + +## Evidence + +- {User quote, data point, or observation that proves this problem exists} +- {Another piece of evidence} +- {If none: "Assumption - needs validation through [method]"} + +## Proposed Solution + +{One paragraph: What we're building and why this approach over alternatives} + +## Key Hypothesis + +We believe {capability} will {solve problem} for {users}. +We'll know we're right when {measurable outcome}. + +## What We're NOT Building + +- {Out of scope item 1} - {why} +- {Out of scope item 2} - {why} + +## Success Metrics + +| Metric | Target | How Measured | +|--------|--------|--------------| +| {Primary metric} | {Specific number} | {Method} | +| {Secondary metric} | {Specific number} | {Method} | + +## Open Questions + +- [ ] {Unresolved question 1} +- [ ] {Unresolved question 2} + +--- + +## Users & Context + +**Primary User** +- **Who**: {Specific description} +- **Current behavior**: {What they do today} +- **Trigger**: {What moment triggers the need} +- **Success state**: {What "done" looks like} + +**Job to Be Done** +When {situation}, I want to {motivation}, so I can {outcome}. + +**Non-Users** +{Who this is NOT for and why} + +--- + +## Solution Detail + +### Core Capabilities (MoSCoW) + +| Priority | Capability | Rationale | +|----------|------------|-----------| +| Must | {Feature} | {Why essential} | +| Must | {Feature} | {Why essential} | +| Should | {Feature} | {Why important but not blocking} | +| Could | {Feature} | {Nice to have} | +| Won't | {Feature} | {Explicitly deferred and why} | + +### MVP Scope + +{What's the minimum to validate the hypothesis} + +### User Flow + +{Critical path - shortest journey to value} + +--- + +## Technical Approach + +**Feasibility**: {HIGH/MEDIUM/LOW} + +**Architecture Notes** +- {Key technical decision and why} +- {Dependency or integration point} + +**Technical Risks** + +| Risk | Likelihood | Mitigation | +|------|------------|------------| +| {Risk} | {H/M/L} | {How to handle} | + +--- + +## Implementation Phases + +<!-- + STATUS: pending | in-progress | complete + PARALLEL: phases that can run concurrently (e.g., "with 3" or "-") + DEPENDS: phases that must complete first (e.g., "1, 2" or "-") + PRP: link to generated plan file once created +--> + +| # | Phase | Description | Status | Parallel | Depends | PRP Plan | +|---|-------|-------------|--------|----------|---------|----------| +| 1 | {Phase name} | {What this phase delivers} | pending | - | - | - | +| 2 | {Phase name} | {What this phase delivers} | pending | - | 1 | - | +| 3 | {Phase name} | {What this phase delivers} | pending | with 4 | 2 | - | +| 4 | {Phase name} | {What this phase delivers} | pending | with 3 | 2 | - | +| 5 | {Phase name} | {What this phase delivers} | pending | - | 3, 4 | - | + +### Phase Details + +**Phase 1: {Name}** +- **Goal**: {What we're trying to achieve} +- **Scope**: {Bounded deliverables} +- **Success signal**: {How we know it's done} + +**Phase 2: {Name}** +- **Goal**: {What we're trying to achieve} +- **Scope**: {Bounded deliverables} +- **Success signal**: {How we know it's done} + +{Continue for each phase...} + +### Parallelism Notes + +{Explain which phases can run in parallel and why} + +--- + +## Decisions Log + +| Decision | Choice | Alternatives | Rationale | +|----------|--------|--------------|-----------| +| {Decision} | {Choice} | {Options considered} | {Why this one} | + +--- + +## Research Summary + +**Market Context** +{Key findings from market research} + +**Technical Context** +{Key findings from technical exploration} + +--- + +*Generated: {timestamp}* +*Status: DRAFT - needs validation* +``` + +--- + +## Phase 8: OUTPUT - Summary + +After generating, report: + +```markdown +## PRD Created + +**File**: `.claude/PRPs/prds/{name}.prd.md` + +### Summary + +**Problem**: {One line} +**Solution**: {One line} +**Key Metric**: {Primary success metric} + +### Validation Status + +| Section | Status | +|---------|--------| +| Problem Statement | {Validated/Assumption} | +| User Research | {Done/Needed} | +| Technical Feasibility | {Assessed/TBD} | +| Success Metrics | {Defined/Needs refinement} | + +### Open Questions ({count}) + +{List the open questions that need answers} + +### Recommended Next Step + +{One of: user research, technical spike, prototype, stakeholder review, etc.} + +### Implementation Phases + +| # | Phase | Status | Can Parallel | +|---|-------|--------|--------------| +{Table of phases from PRD} + +### To Start Implementation + +Run: `/prp-plan .claude/PRPs/prds/{name}.prd.md` + +This will automatically select the next pending phase and create an implementation plan. +``` + +--- + +## Question Flow Summary + +``` +┌─────────────────────────────────────────────────────────┐ +│ INITIATE: "What do you want to build?" │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ FOUNDATION: Who, What, Why, Why now, How to measure │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ GROUNDING: Market research, competitor analysis │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ DEEP DIVE: Vision, Primary user, JTBD, Constraints │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ GROUNDING: Technical feasibility, codebase exploration │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ DECISIONS: MVP, Must-haves, Hypothesis, Out of scope │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ GENERATE: Write PRD to .claude/PRPs/prds/ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## Integration with ECC + +After PRD generation: +- Use `/prp-plan` to create implementation plans from PRD phases +- Use `/plan` for simpler planning without PRD structure +- Use `/save-session` to preserve PRD context across sessions + +## Success Criteria + +- **PROBLEM_VALIDATED**: Problem is specific and evidenced (or marked as assumption) +- **USER_DEFINED**: Primary user is concrete, not generic +- **HYPOTHESIS_CLEAR**: Testable hypothesis with measurable outcome +- **SCOPE_BOUNDED**: Clear must-haves and explicit out-of-scope +- **QUESTIONS_ACKNOWLEDGED**: Uncertainties are listed, not hidden +- **ACTIONABLE**: A skeptic could understand why this is worth building