prd-planner

What this skill does

# PRD Planner

Generate structured planning documents that optimize AI-assisted development by breaking work into discrete, context-efficient conversation threads.

## Core Principles

1. **Thread Isolation** - Each task is scoped for a single conversation to minimize context carryover
2. **Reasoning Economy** - Match model capability to task complexity (don't waste high reasoning on low tasks)
3. **Self-Contained Context** - Every thread has all information needed to execute without external reference
4. **Progressive Tracking** - Checklist format enables clear progress visibility and serves as context for subsequent threads
5. **Goal-Backwards Design** - Start from the end state and work backward to determine thread sequence

## Verification

Before returning a PRD, verify that:

- every thread has a clear purpose, reference material, and deliverable
- validation is explicit enough that an implementer can prove completion
- dependencies and sequencing are clear enough to execute without replanning
- the plan stays focused on implementation quality rather than generic project-management ceremony

## Red Flags

- threads that say "implement the feature" without clear file, interface, or verification boundaries
- plans that rely on confidence instead of testable checks
- broad parallel swarms when one serial backbone with bounded sidecars would be safer
- planning output that stays conceptual when the next thread needs a decision-complete brief

## PRD Creation Process

1. **Discuss phase (if needed)** - Clarify requirements before planning (see below)
2. **Define done** - Write the end state before any threads
3. **Work backwards** - Identify dependencies from goal to starting point
4. **Analyze complexity** - Identify discrete work units and assign reasoning levels
5. **Generate the PRD** - Use the template structure from [references/prd-template.md](references/prd-template.md)
6. **Assess risk** - Document blast radius and rollback plan
7. **Validate completeness** - Ensure each thread is self-contained
8. **Optionally emit an execution manifest** - For plans with 3+ threads, dependencies, or intended subagent execution, also produce a compact manifest using [references/execution-manifest-template.json](references/execution-manifest-template.json)

---

## Discuss Phase (Pre-Planning)

Before creating threads, run a discuss phase when ANY of these are true:
- Requirements are ambiguous or came from someone other than the executor
- Multiple valid approaches exist with significant tradeoffs
- The change touches unfamiliar parts of the codebase
- Novel problem domain you haven't solved before
- High-stakes change (production data, auth, payments)

### When to Skip Discuss Phase

Skip directly to planning when:
- User says "skip discuss" or "I know what I want"
- Requirements are crystal clear with specific acceptance criteria
- Following an established pattern with no decisions to make
- Small scope (1-2 threads, single service)

### Discuss Phase Questions

Ask these to surface assumptions:

1. **Success definition**: "What does done look like? How will you know this worked?"
2. **Constraints**: "Are there approaches that are off the table? Performance/cost/timeline limits?"
3. **Stakeholders**: "Who else touches this code or cares about this change?"
4. **Risk tolerance**: "What's the worst thing that could happen? How bad would that be?"
5. **Prior art**: "Has something similar been tried before? What happened?"

### Discuss Phase Output

```markdown
## Discuss Phase Summary

**Assumptions confirmed**:
- [What the user validated]

**Assumptions made** (user didn't specify):
- [What you're assuming - flag for review]

**Risks identified**:
- [What could go wrong]

**Approach selected**:
- [Brief description of chosen direction and why]

**Open questions** (to resolve during execution):
- [What still needs answers]
```

---

## Debug-First Pattern (Thread 0)

For bugs, performance issues, or unclear problems, insert an investigation thread BEFORE implementation threads.

### When to Use Thread 0

- Bug reports without clear reproduction steps
- Performance issues without profiling data
- Errors in production logs you haven't traced
- Feature requests that might already be partially implemented
- "It's broken" without specifics

### Thread 0 Template

```markdown
### Thread 0 — Investigation — Reasoning Effort: medium-high

- **Purpose**: Gather information and document findings. DO NOT fix anything.
- **Actions**:
  - Reproduce the issue (or document why it can't be reproduced)
  - Read relevant logs, trace code paths
  - Identify root cause or narrow down candidates
  - Document what you found
- **Reference material**: [logs, error messages, user reports]
- **Deliverables**: Investigation report with:
  - Steps to reproduce (if possible)
  - Root cause (confirmed or candidates)
  - Recommended fix approach
  - Files that will need changes
- **Reasoning effort**: Medium-High (Sonnet or Opus)
- **Output feeds**: Thread 1 design decisions

**Important**: Thread 0 produces a REPORT, not code. Implementation starts in Thread 1.
```

---

## Reasoning Level Guidelines

Assign reasoning levels based on task characteristics. See [references/reasoning-levels.md](references/reasoning-levels.md) for detailed guidance.

`Reasoning effort` is the canonical planning field. Vendor model names are only hints for the environment that will execute the thread.

| Level | Characteristics | Claude Hint | OpenAI Hint |
|-------|-----------------|-------------|-------------|
| **Minimal** | Procedural, well-documented, single-file | Haiku | GPT-5.4 low |
| **Low** | Clear patterns, limited decisions, 2-3 files | Haiku or Sonnet | GPT-5.4 low |
| **Medium** | Code comprehension, refactoring, integration | Sonnet | GPT-5.4 medium |
| **Medium-High** | Architecture decisions, test orchestration, investigation | Sonnet or Opus | GPT-5.4 high |
| **High** | Novel problems, system design, complex debugging | Opus | GPT-5.4 high |

### Context Volume Tag

In addition to reasoning level, every thread should be tagged with its **context volume** -- the estimated total size of reference material the executing agent must read. This drives model selection during execution.

| Tag | Meaning | Execution Implication |
|-----|---------|----------------------|
| **Light** (under 50KB) | Reads a few focused files | Any model handles this |
| **Heavy** (50-100KB) | Reads several reference docs or upstream deliverables | Prefer larger context model |
| **Synthesis** (over 100KB or reads all upstream deliverables) | Must hold entire prior work in context to integrate | **Require largest context model or execute in orchestrator session** |

**When to apply the Synthesis tag:** A thread is a synthesis thread if it reads 4+ upstream deliverables, integrates or reconciles prior work, or is the capstone/final thread in a multi-thread plan. Always flag these explicitly -- they are the most likely to fail when delegated to a standard-context agent.

Format in the PRD: append the context tag after reasoning effort, e.g.:
- `Reasoning effort: Medium (Sonnet) | Context: Light`
- `Reasoning effort: High (Opus) | Context: Synthesis`

---

## Thread Structure Requirements

Every thread in the PRD MUST include:

1. **Thread identifier** - Numbered for tracking (e.g., "Thread 3" or "Step 15")
2. **Purpose statement** - Clear goal in one sentence
3. **Actions with inline verification** - Specific work with verify steps (see below)
4. **Reference material** - File paths to read first (use `file.py:1` format for line hints)
5. **Deliverables** - Expected outputs
6. **Reasoning effort** - Vendor-neutral level with context volume tag

### Inline Verification (New Pattern)

Instead of listing validation targets at the end, embed verification after each action:

```markdown
- **Actions**:
  - Add `platform` column to posts table
    - *Verify*: `\d posts` shows platform column with TEXT type
  - Update Post OR