--- name: prd description: Write a Product Requirements Document for an initiative. Use when an initiative has been chosen and needs a spec — the what and why — before any build or contract work begins. version: 1.1.0 owner: wawan risk: low category: planning scope: read:okf, write:planning/prd --- # prd — Write a Product Requirements Document This skill produces a PRD instance for one initiative. The PRD is the **spec** stage of the [SDLC loop](/okf/core/concepts/sdlc-loop.md): it says *what* to build and *why*, anchored to strategy, so a generator agent and the PM share one definition of the work before a contract is agreed. > **Format note:** this skill follows three-level progressive disclosure > ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is Level 2; > rare variants are pushed to Level 3 sub-files referenced by name. ## When to use vs. not - **Use** when an initiative is selected and needs a spec before build work. - **Do not use** to make the strategic case for *whether* to do the initiative — that is the `strategic-brief` skill. The PRD assumes the initiative is already chosen. - **Do not use** to define how output is judged — that is the [eval-rubric skill](/skills/eval-rubric.skill). PRD and rubric are authored together (see [eval-driven-pm](/okf/core/concepts/eval-driven-pm.md)) but are separate artifacts. ## Procedure 0a. **Existing surface? Understand it first — before grilling.** If specifying this honestly requires reading code that already exists, an [explain-surface](/skills/explain-surface.skill) pass runs on that region **first**, in a fresh context and **not by you**. Its *Open questions* section is a declared input to the grilling below: those are the things that could not be determined from the code, and they must be resolved with the PM or carried explicitly into the PRD's risks — never silently answered by assumption. Greenfield → skip. This exists because step 0b's boundary rule, on its own, gives the **agent** the understanding and the PM none. 0. **Grill before you write.** Before any authoring, interrogate the PM's intent as a dialogue — **one question at a time, a recommended answer offered with each**, no authoring until shared understanding is confirmed. Stop when the intent is **unambiguous**, not at a count — there is deliberately **no question cap** (under-specification needs unlimited digging; a redundant question is a quality bug, not a quantity bug). A batch questionnaire is **not** compliant with this step. Boundary rule, near-verbatim from AGENTS.md: *if a fact can be found by exploring the environment, look it up rather than asking — the decisions, though, are the PM's* (D12 at optimal altitude). A stated requirement that later goes unhonored in a build (the recorded "too many navigations" class) is exactly what this step exists to pin down in writing. 1. **Anchor to strategy first.** Identify the parent KR in the [OKR tree](/okf/core/concepts/okr-tree.md) — or, for maintenance work with no honest KR, the declared [health budget](/okf/core/concepts/health-anchors.md) (`health:`, D59). If the initiative has neither, stop — it is unanchored work and the structural seed of [silent drift](/okf/core/concepts/watermelon-flag.md). Resolve the anchor before writing the PRD; never force a KR link that isn't real. 2. **Start from the template.** Use [prd-template](/okf/core/templates/prd-template.md) as the scaffold. Do not invent a new structure. 3. **Write the problem before the solution.** State the user/PM problem and why it matters now. A PRD that opens with a solution has skipped the only part the agent cannot reconstruct. 4. **Make scope explicit on both sides.** In-scope *and* out-of-scope. The out-of-scope list is the primary defense against agents over-building. 5. **State success as outcomes, not output.** Success criteria describe a change in the world tied to the anchor — the parent KR, or the declared budget's purpose (D59) — not a list of artifacts produced. 6. **Pair with a rubric.** Flag that the [eval-rubric](/skills/eval-rubric.skill) must be authored before the build starts — the eval is written first. 7. **Write for durability.** The PRD (and the contract derived from it) waits while work is scheduled, so write what stays true: name **interfaces, types, and behavioral contracts — never file paths or line numbers** (they stale while work waits and mislead the builder that follows). Criteria are **behavioral, not procedural** — what must be true of the outcome, never the tool sequence (D14 applied to authoring). Acceptance criteria must be **independently verifiable**. One exception: a **prototype-derived snippet** that encodes a decision more precisely than prose may be inlined, trimmed to its decision-rich parts (the D60 promote path). 8. **Keep it at control altitude.** The PRD specs *what and why*; it does not write the application code or dictate the agent's path ([control-plane](/okf/core/concepts/control-plane.md)). ## Required content A complete PRD instance contains: - **Frontmatter** — the file opens with OKF YAML frontmatter: `type: PRD`, `title`, `timestamp` (the repo-wide convention, D63; [frontmatter-format](/okf/core/concepts/frontmatter-format.md)). - **Identity** — `initiative_id`, `product_slug`, `pm_slug`, parent `KR`. - **Problem** — who has it, why now, what it costs to leave unsolved. - **Goal & non-goals** — the change sought; explicit out-of-scope. - **Requirements** — what must be true of the solution (capabilities, constraints). - **Success criteria** — outcome-based, tied to the anchor (KR or budget purpose). - **Risks & open questions** — including anything to escalate to the PM. - **Links** — parent KR, the paired eval rubric, relevant OKF concepts. **Dual-audience rule (D58):** every link carries ONE situating sentence (what it is and why it matters here — the source-to-concept rule applied to planning artifacts), and the parent-KR line quotes the KR *text*, not just its id (health-anchored: name the budget and why the work fits its coverage). The body stays agent-optimized; the references must stand alone for a human stakeholder reading the PRD without the OKF bundle in context. ## Output and placement - PRD instances are **operational**, not OKF knowledge. They live under `/planning/prd/`, not in the bundle ([okf-governance](/okf/core/concepts/okf-governance.md)). - Filename: descriptive and slugged, e.g. `p0-prd.md`. ## Quality bar Before handing off, confirm: anchor present — parent KR (text quoted, not just the id) or `health:` (D59); problem precedes solution; out-of-scope is non-empty; success criteria are outcomes not output; every link carries its situating sentence (D58); the eval rubric is queued to be written first. ## Level 3 sub-cases - Multi-product or platform PRDs that span more than one `product_slug`: see `prd-multiproduct.md` (author on first need). - Spike / discovery work where the deliverable is a learning, not a feature, is **not a PRD case** — take the discovery lane ([D56](/okf/products/pmos/adr/d56-initiative-lanes.md)): [discovery skill](/skills/discovery.skill) + [spike-brief template](/okf/core/templates/spike-brief-template.md).