# Prd Creation

> Standard format and workflow for creating PRDs with JSON stories. Includes schema, complexity rules, agent selection, and completion checklist. Use when creating product requirements, writing user stories, or planning feature work with structured tracking.

- Skill: `cobuchan/prd-creation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cobuchan/prd-creation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cobuchan/prd-creation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: cobuchan (https://skillmd.com/u/cobuchan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cobuchan/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

```json
{
  "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 |
|--------|------|
| **I**ndependent | Can it be built without waiting on another story? (If not, record it in `depends_on`.) |
| **N**egotiable | Is it a statement of need, not a locked implementation spec? |
| **V**aluable | Does it deliver observable value to a user or the business? |
| **E**stimable | Is it understood well enough to gauge `complexity`? |
| **S**mall | Small enough to finish in one focused pass? If not, decompose (see Story Decomposition). |
| **T**estable | 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:

```markdown
## 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`