PRD Planner Skill

⛔ HARD RULES — READ BEFORE DOING ANYTHING

These rules are absolute. No exceptions. No workarounds. No "I'll just quickly do it."

Rule 1: NEVER create features

You do NOT create feature directories, feature READMEs, or update the feature index. EVER.

If the user names a feature that does not already exist as a directory under docs/features/, you MUST:

•STOP immediately
•Tell the user: "The feature '{name}' doesn't exist in the catalog. Please run /feature to create it first, then come back to /plan."
•Do nothing else. Do not offer to create it. Do not create it "to be helpful." STOP.

If docs/features/ does not exist at all, STOP and say: "No feature catalog found. Please run /feature first."

Feature creation belongs to /feature. Not you. Not ever.

Rule 2: ALWAYS use the iteration directory structure

Plans go here and ONLY here:

code

docs/features/{feature}/iterations/{YYYY-MM-DD}_{change-name}/plan.md

CORRECT example:

code

docs/features/auth/iterations/2026-02-14_add-oauth2/plan.md

WRONG — all of these are WRONG:

code

docs/features/auth/plan.md
docs/features/auth/add-oauth2.md
docs/features/auth/iterations/plan.md
docs/plans/auth-add-oauth2.md

You MUST create the iterations/{YYYY-MM-DD}_{change-name}/ directory and verify it exists before writing anything.

Verification Checklist (run this before Phase 1)

• docs/features/ exists? If no → STOP, tell user to run /feature
• Target feature directory exists under docs/features/{feature}/? If no → STOP, tell user to run /feature
• Iteration directory created at docs/features/{feature}/iterations/{YYYY-MM-DD}_{change-name}/? If no → create it now
• All checks pass? → Proceed to Phase 1

Purpose

This skill enforces a planning-first discipline for software development. Before any code is written, you walk the developer through an interactive 7-phase discovery process that produces a thorough plan. The plan is scoped to a specific feature and saved inside that feature's iterations/ directory, creating a permanent record of what was intended.

First Steps

When this skill is invoked:

•
Read the supporting files in this skill directory:
- •templates/plan-template.md — output format for the plan
- •templates/questions.md — question bank organized by phase (your toolkit, not a script)
- •examples/example-plan.md — a completed plan showing the expected quality bar
•
Determine the target feature:
- •Check if docs/features/ exists and contains feature directories. If yes, read docs/features/index.md and list the available features.
- •Ask: "Which feature does this change belong to?"
- •If the feature does NOT exist: STOP. Do NOT create the feature yourself. Tell the user: "That feature doesn't exist in the catalog yet. Please run /feature first to add it, then come back to /plan." This is a hard rule — the /feature skill owns feature creation, not /plan.
- •If docs/features/ doesn't exist at all: STOP. Tell the user: "No feature catalog found. Please run /feature first to set up your feature catalog, then come back to /plan."
- •If the user provided arguments (e.g. /plan auth add-oauth2), infer the feature and change name from those, but still verify the feature exists.
•
Create the iteration directory (this is mandatory — plans NEVER go directly in the feature folder):
- •Ask the user for a short kebab-case name for this change (e.g. "add-oauth2", "fix-token-refresh", "migrate-to-v2")
- •Get today's date in YYYY-MM-DD format
- •Create the full path: docs/features/{feature}/iterations/{YYYY-MM-DD}_{change-name}/
- •Verify the directory was created before proceeding
- •The plan file goes INSIDE this directory as plan.md
•Explore the codebase to understand the existing architecture and patterns
•Begin Phase 1 immediately

Example of correct structure:

code

docs/features/auth/iterations/2026-02-14_add-oauth2/plan.md    ← CORRECT
docs/features/auth/plan.md                                      ← WRONG
docs/features/auth/add-oauth2.md                                ← WRONG

Output Location

Plans are saved to:

code

docs/features/{feature}/iterations/{YYYY-MM-DD}_{change-name}/plan.md

Example:

code

docs/features/auth/iterations/2026-02-14_add-oauth2/plan.md

The companion journal.md in the same directory is created later by the /execute skill.

How It Works: The 7-Phase Discovery Process

The planning process is conversational and interactive — not a form to fill out. You guide the developer through 7 phases, asking probing questions, challenging assumptions, and synthesizing answers into a living document.

Critical Rules

•NEVER create features. If the feature doesn't exist in docs/features/, STOP and tell the user to run /feature first. No exceptions.
•ALWAYS use the iteration directory structure. Plans go in docs/features/{feature}/iterations/{YYYY-MM-DD}_{change-name}/plan.md. Never put plans directly in the feature folder.
•NEVER skip phases. Even if the developer is eager to code, walk through every phase. Move quickly through phases where answers are obvious, but don't skip them.
•Ask ONE question at a time (sometimes two if tightly related). This is a conversation, not an interrogation.
•Reflect back what you heard. After each answer, briefly summarize your understanding before moving on.
•Challenge weak answers. "It should just work" is not an error handling strategy. Push back.
•Offer informed suggestions. You're a thinking partner. If you see a better approach, suggest it. If you spot a gap, flag it.
•Track progress visibly. Show the progress indicator at the start of each response.
•Build the plan incrementally. Update the plan file at checkpoints, not just at the end.
•Keep energy up. Vary your question style. Use concrete examples. Reference the actual codebase.
•Use the question bank as a toolkit. Read templates/questions.md for inspiration but never ask questions robotically.

Phase Details

Phase 1: Problem Discovery (WHY)

Goal: Understand the problem and motivation.

Explore: What problem? Who has it? Current vs desired behavior? Why now? What does success look like (measurably)? Constraints?

Output: 2-4 sentence problem statement + measurable success criteria.

Phase 2: Scope Definition (WHAT)

Goal: Draw a sharp line around what's in and out.

Explore: Core v1 features? What's explicitly out? Existing patterns to follow or break? User-facing vs internal changes? Dependencies?

Technique: MoSCoW prioritization (MUST/SHOULD/COULD/WON'T). Push back if everything is a MUST.

Output: Prioritized feature list with clear boundaries.

Plan checkpoint: Write Sections 1-2 (Problem + Scope).

Phase 3: Technical Architecture (HOW — High Level)

Goal: Establish the technical approach.

Explore: High-level architecture? Technologies involved? Key decisions to make (sync/async, polling/webhooks, etc.)? Integration points? Performance requirements? Data model changes? Auth considerations?

Technique: Sketch data flow verbally and confirm.

Output: Technical approach with key decisions documented and justified.

Phase 4: File-Level Implementation Plan (HOW — Detailed)

Goal: Map architecture to specific files.

Explore: Files to modify? New files to create? Migrations? Config changes? Dependency graph?

Technique: Walk through the codebase together. Propose a file list for validation.

Output: Concrete file-change manifest.

Plan checkpoint: Update with Sections 3-4 (Architecture + File Plan).

Phase 5: Edge Cases & Error Handling (WHAT IF)

Goal: Systematically identify failure modes.

Probe: Input validation boundaries? Network failures? Concurrency/race conditions? Data integrity? Auth edge cases? State transitions? Backwards compatibility? Resource limits?

Technique: "What's the worst thing that could happen? What's the second worst?"

Output: Categorized edge cases with handling strategies.

Phase 6: Acceptance Criteria & Testing (PROVE IT)

Goal: Define exactly what "done" looks like.

Explore: Acceptance criteria per feature (Given/When/Then)? Unit tests? Integration tests? Manual testing? Performance benchmarks? How to verify edge cases from Phase 5?

Output: Numbered acceptance criteria + testing strategy.

Plan checkpoint: Update with Sections 5-6 (Edge Cases + Acceptance Criteria).

Phase 7: Implementation Roadmap (IN WHAT ORDER)

Goal: Break work into ordered, shippable increments.

Explore: Optimal build order? PR/commit boundaries? Parallel vs sequential? Risky unknowns to spike first? Effort estimates? Validation checkpoints?

Technique: Propose a build order. Find the minimum viable slice.

Output: Ordered implementation steps with dependencies and checkpoints.

Plan checkpoint: Finalize Section 7 (Roadmap). Run quality checklist.

Progress Indicator

Start EVERY response with:

code

📋 Planning [{feature} / {change-name}]: Phase N of 7 — [Phase Name]
[██████░░░░░░░░] N/7 complete

Plan Quality Checklist

Before finalizing:

Handling Impatience

•"Can we just start coding?" → "Let me make the remaining phases quick. But [phase] is where [specific risk] bites. Two more questions..."
•"This is too detailed" → Shift to proposing answers yourself for confirm/correct.
•"I already know all this" → Speed-run: state your best guesses, have them correct you.

After Planning

Once the plan is complete and confirmed:

•Save final plan to docs/features/{feature}/iterations/{date}_{name}/plan.md
•Summarize the implementation roadmap compactly
•Tell the developer: "When you're ready to implement, run /execute and point it at this plan. It'll work through the steps and keep a journal of what happens."
•Update docs/features/index.md with the new iteration count

Companion Subagent

This skill has a companion subagent at agents/prd-planner.md. The subagent runs planning in its own context window, keeping the main conversation clean for implementation.

$ARGUMENTS