Writing Prd

Writing PRD

Produces a single authoritative document that serves two audiences simultaneously: human product/engineering stakeholders AND downstream AI coding agents. The spec must be parseable by both. Every section has a purpose.

Philosophy: The Agentic PRD

A traditional PRD is prose designed for humans to interpret. An Agentic PRD adds a machine-executable layer: structured acceptance criteria with predicates and examples that agents can consume without interpretation drift.

Structure: human context → machine spec → AI-specific requirements.

Input

Load and read:

• knowledge/prototype-brief.md (primary input — must be approved, DRAFT marker removed)
• ../ideation-phase/knowledge/vision.md (north star context — if accessible)
• knowledge/nfr.md (if already exists from eliciting-nfr)

If prototype-brief.md is missing or still marked DRAFT, stop and tell the user.

Output

Write to knowledge/prd.md. Mark as DRAFT until human approves.

PRD Template

# PRD — [feature/product name]
_Status: DRAFT — awaiting human approval_
_Phase: Requirements_
_Date: [date]_
_Version: 1.0.0_



## 1. Executive Summary
One paragraph. For humans who won't read further.
What is being built, for whom, and what outcome it produces.
Success criterion in one sentence.



## 2. Product Context

### Problem Statement
[Single sentence from problem-frame.md]

### Target Persona
- **Primary**: [name, role, key frustration, technical literacy]
- **Scenario**: [the specific moment when this product is used]

### Success Metrics
| Metric | Baseline | Target | Measurement method |
|--|-|--|-|
| [HEART/AARRR metric] | [now] | [goal] | [how measured] |

### Explicitly Out of Scope
- [Item] — reason: [why excluded, not just what]



## 3. Functional Requirements

### Epics

#### Epic [E-01]: [verb-noun name]
_Hypothesis: [from prototype-brief.md — copied verbatim]_

##### Story [E-01-S-01]: [verb-noun name]

**Human-readable**:
As a [persona], I want [capability] so that [value delivered].

**Machine-executable acceptance criteria**:
```json
{
  "story_id": "E-01-S-01",
  "acceptance": [
    {
      "type": "predicate",
      "id": "AC-01",
      "expr": "[logical condition in plain English — one truth condition per entry]",
      "given": "[precondition]",
      "when": "[action]",
      "then": "[outcome]"
    }
  ],
  "invariants": [
    {
      "type": "invariant",
      "id": "INV-01",
      "expr": "[condition that must always hold — e.g. response_time < 2000ms]"
    }
  ],
  "examples": [
    { "input": "[example input]", "expected": "[expected output or behaviour]" },
    { "input": "[edge case]", "expected": "[expected output or behaviour]" },
    { "input": "[failure case]", "expected": "[graceful failure behaviour]" }
  ]
}

Dependencies: [story IDs this story depends on, or NONE] Estimated size: XS / S / M / L / XL Shippable independently: YES / NO — if NO, explain why and propose a split

4. Non-Functional Requirements

See knowledge/nfr.md for full detail. Summary below.

Performance

AI-Specific NFRs

Security

• [Auth requirement]
• [Data sensitivity classification and handling rule]

Compliance

• [Any regulatory constraints — GDPR, HIPAA, etc.]

5. AI Component Specifications

For each AI component identified in prototype-brief.md

Component: [name]

6. Three-Tier Boundaries

Explicit constraints for AI agents implementing this spec.

Always do:

• [Non-negotiable behaviour — e.g. "Always validate user input before LLM submission"]

Ask first (do not proceed autonomously):

• [Decision requiring human confirmation — e.g. "Before deleting any user data"]

Never do:

• [Hard prohibition — e.g. "Never expose raw LLM outputs without filtering"]

7. Open Questions

8. Glossary

Define domain terms used in acceptance criteria. Agents need unambiguous vocabulary.

• [term]: [precise definition]

Human approval required. Remove DRAFT and change status to READY before Architecture Phase.

## Writing Guidelines

- Each acceptance criterion must be **singular** — one truth condition per entry.
  Bad: "The system saves the record AND sends a confirmation email."
  Good: Two separate criteria.

- Examples must include at least one **failure/edge case** per story.
  Agents use examples as few-shot context. Missing edge cases cause silent failures.

- The Three-Tier Boundaries section is **mandatory for any story involving an AI component**.
  Agents implementing the spec use it as a behavioural contract.

- Do not pad the PRD. Every section that has no content should be omitted, not filled with
  placeholder text. Downstream agents treat all content as signal.

## References

See `references/prd-examples.md` for worked examples including AI-native feature specs.


## When to Use
Follow standard when to use documentation.

## Prerequisites
Follow standard prerequisites documentation.

## Process
Follow standard process documentation.

## Best Practices
Follow standard best practices documentation.