124 added, 173 removed. Audit A to A.
---
description: "When the user types /plan or asks to create a project plan, feature PRD, or retrospective"
globs: ""
alwaysApply: false
---
# Plan — Structured Project Planning & PRD Generation
- Three planning modes with a shared research-driven Q&A engine. Each mode follows the pattern: **research -> questions -> design -> document**.
+ Three planning modes with a shared research-driven Q&A engine. Pattern across all modes: **research → questions → document → review → issues**.
- ## Mode Selection
+ ## Phase 0: Read Session Config
- Parse the user's input to determine the mode:
+ Read Session Config from CLAUDE.md. Required field: `plan-baseline-path`. If missing or absent, stop with error:
- - **`/plan new`** — Project kickoff: scaffolding, architecture decisions, initial setup
- - **`/plan feature`** — Feature PRD: requirements gathering, compact scope, implementation plan
- - **`/plan retro`** — Retrospective: data-driven analysis of recent work, learnings extraction
+ > "Error: `plan-baseline-path` is not configured in Session Config. Add it to your CLAUDE.md under `## Session Config`. Example: `plan-baseline-path: ~/Projects/projects-baseline`"
- If no mode specified, ask the user:
+ Additional fields: `plan-default-visibility`, `plan-prd-location`, `plan-retro-location`, `vcs`. Expand `~` in paths.
+ ## Phase 1: Mode Selection
+
+ Parse the argument to determine mode:
+
+ - **`new`** — Project kickoff: scaffolding, architecture decisions, initial setup
+ - **`feature`** — Feature PRD: requirements gathering, compact scope, acceptance criteria
+ - **`retro`** — Retrospective: data-driven analysis of recent work, learnings extraction
+
+ If no mode specified, ask via numbered list:
+
```
Which planning mode?
- 1. new — Project kickoff (full PRD, repo setup, issue creation)
+ 1. new (Recommended) — Project kickoff (full PRD, repo setup, issue creation)
2. feature — Feature PRD (compact scope, acceptance criteria, issues)
3. retro — Retrospective (metrics analysis, reflection, improvement actions)
```
- ## Prerequisites
-
- Read Session Config from CLAUDE.md. Required field: `plan-baseline-path`. If missing, stop with error.
-
- ## Shared Q&A Engine
+ ## Phase 2: Q&A Engine (Shared Core)
- Every question wave follows the same pattern. This is the core mechanic across all three modes.
+ Every question wave follows the same pattern. This is the core mechanic across all modes.
- ### Step 1: Pre-Question Research
+ ### 2.1 Pre-Question Research
- Before each Q&A wave, perform research **sequentially** (Cursor has no parallel agents):
+ Before each Q&A wave, perform research **sequentially** — Cursor has no parallel agents:
- 1. **Market/online context** — Search for relevant market data, best practices, competitor analysis, or technical patterns depending on the questions to be asked
- 2. **Baseline analysis** — Read projects-baseline templates, rules, and scripts at the configured `plan-baseline-path` to discover available options
- 3. **Repo context** — Analyze the current repository for existing patterns, file structure, dependencies, and conventions (skip for `/plan new` wave 1)
+ 1. **Market/online context** — Search for relevant market data, best practices, competitor analysis, or technical patterns for the upcoming questions
+ 2. **Baseline analysis** — Read projects-baseline templates, rules, and scripts at `$BASELINE_PATH` (Glob, Grep, Read)
+ 3. **Repo context** — Analyze current repository for patterns, file structure, dependencies, conventions (skip for `/plan new` wave 1)
- ### Step 2: Question Presentation
+ ### 2.2 Question Presentation
- Synthesize research into **5 questions per wave**. Present with options:
+ Synthesize research into **5 questions per wave**. Present as numbered Markdown lists — Cursor has no AskUserQuestion:
- **Option 1 is ALWAYS the recommendation**, marked with `(Recommended)`
- - Each option includes Pros/Cons drawn from the research
+ - Include Pros/Cons drawn from the research for each option
- Include an "Other" option when custom input makes sense
Example:
```
## Architecture (Wave 1, Q1)
Which project archetype fits best?
1. nextjs-saas (Recommended) — Pro: Full SaaS stack with auth, payments. Con: Heavier setup.
2. express-service — Pro: Lightweight API. Con: No frontend.
3. docker-service — Pro: Maximum flexibility. Con: More manual setup.
4. Other — Describe your preferred archetype.
```
- ### Step 3: Adaptive Depth
+ ### 2.3 Adaptive Depth
- After each wave, assess whether to continue:
- - **Answers are clear** — proceed to document generation
- - **Answers reveal complexity** — add another wave with targeted follow-ups
- - **User aborts early** — proceed with answers gathered so far
+ Starting wave counts: `new` → 3 waves minimum, `feature` → 1 wave minimum, `retro` → 1 wave minimum. Maximum 5 waves across all modes.
- Maximum waves per mode: `/plan new` starts with 3 (max 5), `/plan feature` starts with 1 (max 5), `/plan retro` starts with 1 (max 5).
+ After each wave:
+ - **Answers clear** → proceed to document generation
+ - **Complexity revealed** → add targeted follow-up wave
+ - **User aborts** → proceed with answers gathered
- ### Step 4: Answer Tracking
+ ### 2.4 Answer Tracking
After each wave, output a recap:
```
## Answers So Far (Wave N/M)
1. Archetype: nextjs-saas
2. Visibility: internal
3. Audience: B2B customers
- ...
```
---
## Mode: new — Project Kickoff
- ### Wave 1 — Core Decisions (5 questions)
+ **Wave 1** — Core Decisions: archetype (read `$BASELINE_PATH/templates/`), visibility, target audience, core problem, GitLab group.
- **Research first:**
- - List available project archetypes from `$BASELINE_PATH/templates/`
- - Search for market context related to the project idea
- - Check ecosystem (`~/Projects/`) for conflicts and reuse opportunities
+ **Wave 2** — Technical Details (per chosen archetype): tech stack decisions, design style, external integrations, performance requirements, security requirements.
- **Questions:**
- 1. Project archetype (from baseline templates)
- 2. Visibility (internal / private / public-OSS)
- 3. Target audience
- 4. Core problem being solved
- 5. GitLab group
+ **Wave 3** — Business & Scope: MVP appetite (1w/2w/6w), success criteria (SMART), known risks, post-launch plan, ecosystem dependencies.
- ### Wave 2 — Technical Details (5 questions, dynamic per archetype)
+ Document: 8-section full PRD. Save to `{plan-prd-location}/YYYY-MM-DD-{project-name}.md`.
- **Research first:**
- - Read archetype config from `$BASELINE_PATH/templates/{archetype}/`
- - Search for best practices with the chosen tech stack
- - Check ecosystem for shared patterns
+ After PRD approval: run `$BASELINE_PATH/scripts/setup-project.sh`, verify repo, populate CLAUDE.md, commit PRD.
- **Questions:**
- 1. Tech stack decisions (e.g., Supabase vs alternative DB)
- 2. Design style (for frontend archetypes — read `styles/` directory)
- 3. External integrations (APIs, services, payment providers)
- 4. Performance requirements
- 5. Security requirements
+ Issues: Epic (project name) + sub-issues per MVP feature from PRD Section 4 (Solution & Scope).
- ### Wave 3 — Business & Scope (5 questions)
+ ---
- **Research first:**
- - Analyze archetype failure modes and risks
- - Check ecosystem dependency compatibility
- - Research success benchmarks for comparable products
+ ## Mode: feature — Feature PRD
- **Questions:**
- 1. MVP scope (Shape Up appetite: 1 week / 2 weeks / 6 weeks)
- 2. Success criteria (SMART format — Claude proposes draft, user refines)
- 3. Known risks and mitigations
- 4. Post-launch plan (monitoring, rollback, feedback)
- 5. Ecosystem dependencies
+ **Wave 1** — Feature Core: what to build, why now, who uses it, scope + explicit exclusions, dependencies.
- ### Document Generation
+ **Wave 2** (conditional — only if Wave 1 reveals multiple subsystems or unclear integration): architecture decisions, integration points, data model changes, edge cases, performance impact.
- 1. Read PRD template (8-section full PRD)
- 2. Fill ALL sections — no TBD or placeholder content:
- - Executive Summary, Problem & Context, Target Audience
- - Solution & Scope (drives issue creation), Success Criteria
- - Technical Architecture, Risks & Dependencies, Post-Launch Plan
- 3. Save to `{plan-prd-location}/YYYY-MM-DD-{project-name}.md`
+ Document: 5-section compact PRD. Save to `{plan-prd-location}/YYYY-MM-DD-{feature-slug}.md`.
- ### PRD Review
+ Issues: Epic (feature name) + sub-issues per acceptance criterion group.
- Dispatch a self-review checking 6 criteria:
- 1. **Completeness** — all sections filled
- 2. **Consistency** — no internal contradictions
- 3. **Clarity** — implementable by a developer from this document alone
- 4. **Scope** — focused on one project
- 5. **YAGNI** — no unrequested features
- 6. **SMART metrics** — success criteria are measurable
+ ---
- Max 3 revision iterations. Then present to user for approval.
+ ## Mode: retro — Retrospective
- ### Repo Setup (after PRD approval)
+ **Phase 1 (automatic, no user input):** Read `.orchestrator/metrics/sessions.jsonl`, run git log analysis, query open issues, compare last 5 vs prior 5 sessions.
- 1. Run `$BASELINE_PATH/scripts/setup-project.sh` with mapped choices
- 2. Verify repo creation via `glab repo view`
- 3. Adjust visibility if needed
- 4. Populate CLAUDE.md with Session Config
- 5. Commit PRD to the new repo
+ **Wave 1** — What went well / what didn't: highlights, blockers with root causes, carryover items, process assessment, data anomalies.
- ### Issue Creation
+ **Wave 2** (conditional — if Wave 1 reveals significant blockers or process issues): improvement actions, priority ranking, ownership, baseline changes, Session Config adjustments.
- - **Epic**: project name + brief description
- - **Sub-issues**: one per MVP feature from PRD Section 4 (Solution & Scope)
- - Auto-prioritize: dependencies (critical/high), core MVP (high), nice-to-haves (medium/low)
- - Present to user for confirmation before creating
- - Create via VCS CLI with dependency links
+ Artifacts: retro doc → `{plan-retro-location}/YYYY-MM-DD-retro.md`. Improvement issues + learnings update (`.orchestrator/metrics/learnings.jsonl`).
---
- ## Mode: feature — Feature PRD
+ ## Phase 3: Document Generation
- ### Wave 1 — Feature Core (5 questions)
+ Read the appropriate template from the skill directory:
+ - `new` → `prd-full-template.md` (8 sections)
+ - `feature` → `prd-feature-template.md` (5 sections)
+ - `retro` → `retro-template.md`
- **Research first:**
- - Analyze codebase for related patterns (Glob, Grep)
- - Check VCS for related open issues and recent MRs/PRs
- - Search for best practices for this feature type
+ Fill ALL sections — no TBD or placeholder content. If a section cannot be filled from gathered data, make a best-effort recommendation and mark it `<!-- REVIEW: inferred from research, confirm with stakeholders -->`.
- **Questions:**
- 1. What to build (open-ended, Claude suggests structure)
- 2. Why now (business driver, user feedback, technical necessity)
- 3. Who uses it (existing personas or new audience)
- 4. Scope (MVP appetite + explicit exclusions — push for "what is NOT in this feature")
- 5. Dependencies (on existing issues, features, other repos)
+ Save the document, creating the target directory (`mkdir -p`) if needed.
- ### Wave 2 — Technical Deep Dive (conditional)
+ ## Phase 4: PRD Review (skip for retro)
- > Only trigger if Wave 1 reveals: multiple subsystems affected, unclear integration points, significant architectural decisions, or user explicitly requests deeper analysis.
+ Dispatch a sequential self-review (read `prd-reviewer-prompt.md` from skill directory). Reviewer checks 6 criteria:
+ 1. **Completeness** — all sections filled
+ 2. **Consistency** — no internal contradictions
+ 3. **Clarity** — implementable by a developer from this document alone
+ 4. **Scope** — focused on one project/feature
+ 5. **YAGNI** — no unrequested features
+ 6. **SMART metrics** — success criteria are measurable
- **Research first:** Deep-read affected source files, trace call paths, check test patterns, research technical approaches.
+ If any criterion fails, revise and re-review. Maximum **3 iterations**. After 3 rounds with remaining issues, present to user as numbered list:
- **Questions:**
- 1. Architecture decisions (2-3 approaches with trade-offs)
- 2. Integration points (API changes, new endpoints)
- 3. Data model changes (DB migrations, schema changes)
- 4. Edge cases (error handling, backwards compatibility)
- 5. Performance impact (query complexity, caching needs)
+ ```
+ The PRD reviewer flagged these remaining issues:
+ [list]
- ### Document Generation
+ 1. Accept as-is (Recommended) — issues are minor, proceed
+ 2. Manual edit — I'll edit the PRD myself before continuing
+ 3. Re-run review — try one more revision round
+ ```
- 1. Read compact PRD template (5 sections)
- 2. Fill all sections:
- - Problem & Motivation (from Q1 + Q2)
- - Solution & Scope (from Q4, explicit In-Scope / Out-of-Scope)
- - Acceptance Criteria (Given/When/Then scenarios from answers)
- - Technical Notes (from Wave 2 or Wave 1 research)
- - Risks & Dependencies (from Q5 + edge cases)
- 3. Save to `{plan-prd-location}/YYYY-MM-DD-{feature-slug}.md`
+ Then present the saved PRD path and ask for final approval:
- ### PRD Review & Issue Creation
+ ```
+ PRD saved to [path]. Ready for your review.
- - Same review process as `/plan new` (6 criteria, max 3 iterations)
- - **Epic**: feature name + one-line purpose
- - **Sub-issues**: one per acceptance criterion group (not per individual scenario)
- - Auto-prioritize: dependencies first, core happy-path (high), edge cases (medium/low)
- - Present to user, create via VCS CLI
+ 1. Approve PRD (Recommended) — proceed to issue creation
+ 2. Request changes — describe what to change
+ ```
- ---
+ ## Phase 5: Issue Creation
- ## Mode: retro — Data-Driven Retrospective
+ ### Auto-Prioritize
- ### Phase 1: Data Collection (Automatic, No User Input)
+ Score each issue by three factors:
+ 1. **Technical dependencies** (highest weight) — blocking issues get `priority:critical` or `priority:high`. DB schema before API, API before frontend.
+ 2. **Business value** (medium weight) — core MVP = `priority:high`, nice-to-haves = `priority:medium/low`.
+ 3. **Risk** (tiebreaker) — unknowns or external dependencies bump priority up one level.
- Gather all data before asking questions:
+ Labels: `priority:<level>`, `type:feature/enhancement/chore`, `status:ready`, `area:<inferred>`. For `new`: add `appetite:<1w|2w|6w>`.
- 1. **Session metrics** — Read `.orchestrator/metrics/sessions.jsonl`:
- - Total sessions, average duration, type distribution
- - Average completion rate, carryover rate
- - Agent success rate, spiral rate
- 2. **Git analysis**:
- ```bash
- git log --oneline -50
- git log --format="%H" --since="2 weeks ago" | xargs -I{} git diff-tree --no-commit-id --name-only -r {} | sort | uniq -c | sort -rn | head -20
- ```
- Record: commit frequency, top 20 change hotspots
- 3. **Open issues** — Query VCS CLI for overdue, blocked, and stale issues
- 4. **Trend analysis** — Compare last 5 sessions vs sessions 6-10 (if available)
+ ### User Confirmation (numbered list)
- Present a data summary dashboard before proceeding.
+ ```
+ Proposed issue structure:
- ### Wave 1 — What Went Well / What Didn't (5 questions)
+ Epic: [title]
- **Research first:**
- - Read session memory files for accomplishments and frustrations
- - Analyze git log patterns (large commits, hotfixes, reverts)
- - Categorize open issues by theme
+ | # | Sub-Issue | Priority | Labels | Blocked By |
+ |---|-----------|----------|--------|------------|
- **Questions:**
- 1. Highlights — Top 3 data-backed successes (confirm/reorder/add own)
- 2. Blockers — Top 3 data-backed problems with root causes
- 3. Carryover — Unfinished issues from recent sessions (still relevant? cancel? reprioritize?)
- 4. Process — Session structure assessment based on observed patterns
- 5. Surprises — Open-ended, present data anomalies as starters
+ Total: [N] issues.
- ### Wave 2 — Improvements (conditional)
+ 1. Create all issues (Recommended)
+ 2. Adjust priorities
+ 3. Remove issues
+ 4. Cancel
+ ```
- > Only trigger if Wave 1 reveals: significant blockers, process issues, or user requests actions.
+ ### Issue Creation
- **Questions:**
- 1. Improvement actions — 3-5 concrete improvements with expected impact and effort
- 2. Priority — Rank selected improvements
- 3. Ownership — When to tackle each (next session / spread / assign)
- 4. Baseline changes — Propose template/script/rule changes if recurring issues (3+ sessions)
- 5. Session Config changes — Propose config adjustments if warranted
+ - **GitLab**: `glab issue create --title "[Plan] <title>" --label "<labels>" --description "<body>"`
+ - **GitHub**: `gh issue create --title "[Plan] <title>" --label "<labels>" --body "<body>"`
+ - 1s pause between creations. Set dependency links after all issues are created (GitLab: `glab api` blocking relations).
- ### Artifacts
+ ### Final Report
- 1. **Retro document** — Save to `{plan-retro-location}/YYYY-MM-DD-retro.md`
- 2. **Improvement issues** — One VCS issue per agreed improvement
- 3. **Update learnings** — Append to `.orchestrator/metrics/learnings.jsonl` (confidence 0.5 for new, +0.15 confirm, -0.2 contradict)
- 4. **Baseline updates** — Only if user explicitly confirms
+ ```
+ ## Plan Complete
- ---
+ ### Document
+ - [PRD/Retro] saved to: [path]
+ ### Issues Created
+ | # | Title | Priority | Labels | Blocks |
+ |---|-------|----------|--------|--------|
+
+ ### Dependencies
+ [Dependency graph: #1 → #2 → #4, #3 (independent)]
+
+ ### Next Steps
+ - [Contextual: run /session feature to implement, or address improvement issues]
+ ```
+
## Critical Rules
- - **NEVER skip the Q&A phase** — even with a detailed brief, validate through structured questions. The Q&A surfaces blind spots.
+ - **NEVER skip the Q&A phase** — even with a detailed brief, validate through structured questions
- **NEVER assume baseline templates** — always read from the configured `plan-baseline-path`
- - **ALWAYS research before asking** — perform research before every Q&A wave
- - **ALWAYS mark the first option as recommended** with `(Recommended)`
+ - **ALWAYS research before asking** — sequential research before every Q&A wave
+ - **ALWAYS mark Option 1 as recommended** — with `(Recommended)` on every question
+ - **ALWAYS use numbered Markdown lists** — Cursor has no AskUserQuestion
- **ALWAYS save documents before creating issues** — the PRD/retro document is the source of truth
- - **NEVER leave PRD sections with TBD or placeholder content** — make a best-effort recommendation if data is insufficient
+ - **NEVER leave PRD sections with TBD** — make a best-effort recommendation if data is insufficient
- **NEVER create issues without user confirmation**
- **NEVER include internal paths, IPs, or infrastructure details in output documents**