Prd

Important: Do NOT start implementing. Just create the PRD.

Step 1: Clarifying Questions

Ask only critical questions where the initial prompt is ambiguous. Focus on:

• Problem/Goal: What problem does this solve?
• Core Functionality: What are the key actions?
• Scope/Boundaries: What should it NOT do?
• Success Criteria: How do we know it's done?

Format Questions Like This:

1. What is the primary goal of this feature?
   1.1. Improve user experience
   1.2. Add new functionality
   1.3. Fix existing issues
   1.4. Other: [please specify]

2. What is the scope?
   2.1. Minimal viable version
   2.2. Full-featured implementation
   2.3. Just the backend/API
   2.4. Just the UI

3. What are the key constraints?
   3.1. Must integrate with existing code
   3.2. Greenfield implementation
   3.3. Performance critical
   3.4. Security critical

This lets users respond with "1.1, 2.2, 3.1" for quick iteration.

Step 2: PRD Structure

Generate the PRD with these sections:

1. Overview

Brief description of the feature and the problem it solves.

2. Goals

Specific, measurable objectives (bullet list).

3. User Stories

Each story needs:

• Title: Short descriptive name
• Description: "As a [user], I want [feature] so that [benefit]"
• Acceptance Criteria: Verifiable checklist of what "done" means

Each story should be small enough to implement in one focused session.

Format:

### US-001: [Title]
**Description:** As a [user], I want [feature] so that [benefit].

**Acceptance Criteria:**
- [ ] Specific verifiable criterion
- [ ] Another criterion
- [ ] Tests pass

Important:

• Acceptance criteria must be verifiable, not vague
• "Works correctly" is bad
• "Button shows confirmation dialog before deleting" is good

4. Functional Requirements

Numbered list of specific functionalities:

• "FR-1: The system must allow users to..."
• "FR-2: When a user clicks X, the system must..."

Be explicit and unambiguous.

5. Non-Goals (Out of Scope)

What this feature will NOT include. Critical for managing scope.

6. Technical Considerations

• Known constraints or dependencies
• Integration points with existing systems
• Performance requirements

7. Success Criteria

How will success be measured? What does "done" look like?

8. Open Questions

Remaining questions or areas needing clarification.

Story-Sizing Discipline (Ralph Method)

Critical Rule: Each user story must be completable in the first 60% of a context window (one loop iteration).

The 60% Rule

Stories should complete using roughly 60% of a subagent's context window:

• 20% - Context loading (checkpoint, attention, patterns, plan files)
• 60% - Actual work (implementation, testing, state updates)
• 20% - Buffer (errors, unexpected complexity, cleanup)

This ensures stories never hit context limits and have room for error recovery.

Right-Sized Stories (GOOD - fit in 60%)

• Adding a database column with migration (~30 lines of code)
• Creating a single UI component (~50 lines)
• Implementing one API endpoint with tests (~80 lines)
• Adding a filter dropdown to a list (~40 lines)
• Writing tests for one module (~60 lines)

Too Large - Must Split (BAD - would exceed 60%)

• "Build entire dashboard" → Split into individual widgets (5-10 stories)
• "Implement authentication system" → Split into US-001: Register, US-002: Login, US-003: Logout, US-004: Sessions (4 stories)
• "Refactor entire API" → Split by endpoint or module (10+ stories)

The 2-3 Sentence Rule

If you cannot describe the change in 2-3 sentences, it is too big.

This is a quick heuristic. If you need a paragraph to explain it, split it.

Estimating 60% of Context

For Sonnet 4.5 (~200K context window):

• Target ~120K tokens for story completion
• Roughly 400-600 lines of code read + written
• Or 2-3 files modified with tests

If a story would require:

• Reading >10 files
• Writing >200 lines
• Touching >5 files
• Multiple complex algorithms

→ It's too big. Split it.

Mandatory Acceptance Criteria

Every story MUST include at minimum:

• Typecheck passes (for TypeScript/typed projects)
• Tests pass (if tests exist for this area)
• Verify in browser (for UI changes)

Writing for Implementation

The PRD reader may be an AI agent executing via /loop. Therefore:

• Be explicit and unambiguous
• Avoid jargon or explain it
• Provide enough detail to understand purpose and core logic
• Number requirements for easy reference
• Use concrete examples where helpful
• Include file paths when known

Output

• Format: Markdown (.md)
• Location: .planning/[task-slug]/
• Filename: prd.md

After creating the PRD, also create/update task_plan.md in the same directory with phases derived from the user stories.

State Block (Machine-Parseable Progress)

After the user stories section, add a state block for progress tracking:

<!-- STATE