Prd creation

PRD Creation Skill

Structure

Every PRD has two files:

File	Purpose	Format
[name].md	Human-readable planning, narrative, context	Markdown
[name].json	Machine-readable tracking, status, agent routing	JSON

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

Field	low	medium	high
primary_agent	Required	Required	Optional
key_files	Optional	Required	Required
delegation	—	Optional	Required
triggers	—	Optional	Required
required_gates	—	—	Required

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.

Complexity	Workflow	Required Gates
low	implementer → verifier	—
medium	scout → implementer → verifier	—
high	scout → implementer → verifier	auditor, reviewer

Agent Selection

Situation	Role
Don't know where code lives	scout (an explorer/search role)
Need external docs/APIs	researcher
Planning complex work	planner
Ready to write code	implementer
Code touches 3+ files	auditor (a cross-file consistency check)
Before user sign-off	reviewer
Run tests/builds	verifier

Trigger Rules

Trigger	When True	Required Action
multi_file	3+ files	Run auditor after implementation
external_reference	Needs external docs	Run researcher before implementation
quality_sensitive	Core/user-facing	Run reviewer before sign-off

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:

Letter	Test
Independent	Can it be built without waiting on another story? (If not, record it in depends_on.)
Negotiable	Is it a statement of need, not a locked implementation spec?
Valuable	Does it deliver observable value to a user or the business?
Estimable	Is it understood well enough to gauge complexity?
Small	Small enough to finish in one focused pass? If not, decompose (see Story Decomposition).
Testable	Can you write acceptance criteria that objectively pass or fail?

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.

Wrong	Right
Organize by behavioral template (system concept)	Organize by job role (domain concept)
Organize by code file	Organize by user workflow
Organize by technical layer	Organize by business capability

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