Prd Creation

PRD Creation Skill

Structure

Every PRD has two files:

Both files use the same story IDs (e.g., AUTH-001, PDF-002) for traceability.

JSON Story Schema

{
  "id": "PREFIX-001",
  "title": "Short descriptive title",
  "priority": "CRITICAL|HIGH|MEDIUM|LOW",
  "complexity": "low|medium|high",
  "status": "pending|in_progress|implemented|blocked",
  "depends_on": [],
  "blocked_by": null,
  "user_story": "As a [user], I want [goal] so that [benefit]",
  "acceptance_criteria": ["Specific measurable criterion"],
  "technical_notes": "Implementation hints, key files, gotchas",
  "primary_agent": "implementer",
  "key_files": ["path/to/file.js"],
  "delegation": {
    "exploration": "scout — what to explore and why",
    "implementation": "implementer — what to change",
    "verification": "verifier — how to confirm it works"
  },
  "triggers": {
    "multi_file": false,
    "external_reference": false,
    "quality_sensitive": false
  },
  "required_gates": [],
  "implementation_notes": "",
  "completed_date": null
}

Field Usage by Complexity

Complexity Determination

HIGH complexity — if ANY:

• Touches 4+ files
• Has dependencies
• Changes prompts, evaluation logic, or AI behavior
• Location of code unknown
• 4+ acceptance criteria
• Architectural decisions required

MEDIUM complexity — if:

• 2-3 files involved
• Location known but approach needs validation
• Extending existing pattern with modifications

LOW complexity — if:

• Single file change
• Exact location known
• Copy/extend existing pattern
• Text, cosmetic, or configuration changes

Default Workflows

The workflow and role names below (implementer, scout, auditor, reviewer, verifier) are role names, not agent identifiers — map each to whatever subagent type, plugin, or persona your own setup provides, or do the step inline yourself if it doesn't have a dedicated one. See "Agent Selection" below for what each role is for.

Agent Selection

Trigger Rules

Completion Checklist

Before marking implemented:

• All acceptance criteria met
• Verifier confirmed tests pass
• If multi_file: true → auditor reviewed
• If quality_sensitive: true → reviewer approved
• If required_gates specified → all gates passed
• User signed off (when applicable)
• implementation_notes has commit hash
• completed_date set

PRD Creation Workflow

1. Extract — Read source material, create requirements summary with quotes
2. Define stories — Write user stories with clear acceptance criteria
3. Assess complexity — Apply decision rules to each story
4. Assign agents — Set primary_agent or delegation based on complexity
5. Set triggers — Mark multi_file, external_reference, quality_sensitive
6. Set gates — Add required_gates for high-complexity stories
7. Create both files — Markdown for narrative, JSON for tracking

Writing Good Stories (optional guidance)

These are optional techniques a story author can reach for. They do not change the dual-file (.md + .json) schema — they improve how the user_story and acceptance_criteria fields get written. Our priority vocabulary (CRITICAL/HIGH/MEDIUM/LOW) and complexity scale stay as-is; use them, not an S/M/L sizing scale.

INVEST slicing

Slice stories vertically (a thin end-to-end slice of user value), not by technical layer. Use INVEST as the quality bar for each story:

Enrich the <role> in the user_story with a real persona when one is known (e.g. "As a returning customer" rather than "As a user").

Given/When/Then acceptance criteria

An optional shape for acceptance_criteria entries — write each as Given <context>, When <action>, Then <observable outcome>:

• Every Then must be observable — a state, output, or behavior you can point at. No "the system knows" or "it handles it."
• Give failure paths and permission-denied paths their own criteria, not just the happy path (e.g. a separate criterion for invalid input and for an unauthorized actor).
• No implementation smuggled into criteria. Acceptance criteria describe what is true, never how it's built (no function names, table names, or framework choices — those belong in technical_notes).

Aim for roughly 3–7 criteria per story; too few misses edge cases, too many signals the story should be decomposed.

Verification Pattern

Scouts can misinterpret requirements. For verification stories that gate implementation decisions:

1. Scout does initial exploration and extracts findings
2. A stronger-model reviewer validates findings against source material (quotes, code)
3. Corrections made before proceeding to implementation

This prevents building on faulty assumptions. Critical for:

• Stories that verify existing behavior before changing it
• Requirements extracted from stakeholder feedback
• Technical assessments that drive architectural decisions

Story Decomposition

Organize by what varies in the domain, not what varies in the system.

Decomposition Signals

Break a story into sub-stories when:

• Multiple independent work streams exist
• Different domain entities are involved (job roles, user types, data sources)
• Progress visibility matters (large stories hide progress)
• Parallel work is possible

Scratchpad Integration

Reference PRD stories in scratchpad.md for active work tracking:

## Active Plan

**Current PRD**: `docs/plans/[feature-name].json`

### In Progress
- PREFIX-001: Story title (implementer assigned)
- PREFIX-003: Another story (scout exploring)

### Blocked
- PREFIX-002: Blocked story (waiting on dependency)

Update scratchpad when story status changes. This provides session continuity.

PRD File Locations

PRDs should be stored in the project's planning directory:

• PRD markdown: docs/plans/[name].md
• PRD JSON: docs/plans/[name].json