Product Requirements

Product Requirements

Turn one picked work item into a durable PRD — user stories, testable acceptance criteria, and prioritization — through a guided interview. The product-management middle between product-advisor (BRD) and harness-brainstorming (spec). Authors requirements; never authors the spec.

When to Use

• When a roadmap item (or a plain feature idea) needs product-level requirements — user stories, acceptance criteria, prioritization — before design begins.
• When a non-technical author (PM/BA/client) should shape what and why through a guided interview, no code surface.
• When the downstream spec's acceptance criteria should be authored deliberately rather than fused into the proposal — the PRD feeds harness-brainstorming and, transitively, acceptance-eval.
• NOT for authoring a spec/proposal — that is harness-brainstorming's job. This skill stops at the PRD.
• NOT for the BRD / client-inception intake — that is product-advisor's job (upstream of this).
• NOT for bugs, chores, or refactors with no user-facing behavior — a PRD there is speculative ceremony (YAGNI).

Process

Iron Law

Every user story carries at least one measurable acceptance criterion, or it ships as an open, named gap — never a silent guess. The skill authors the PRD; it does not author the spec, mutate the roadmap, or claim the item.

A PRD that hides what it does not know launders assumptions into requirements. A criterion that cannot be judged is not a criterion. If a story has no measurable criterion and you did not surface it in the chase list, STOP and add it.

Argument Resolution

• item — the slug/name of the work item. From the item argument, or the roadmap row being worked, or ask. Sets the artifact directory docs/product-requirements/<item>/.
• description — a plain feature description, used when no richer input (BRD, roadmap row) exists. The skill requires nothing more than this.

Phase 1: INGEST — Gather the Richest Available Input

Load the richest input that exists, and degrade gracefully — the only hard requirement is a one-line description.

1. BRD when present: if docs/inception/<engagement>/brd.md exists and maps to this item, read its Business Objectives, Scope, and Functional Requirements as the seed.
2. Else the roadmap row: if a roadmap exists (docs/roadmap.md aggregate or docs/roadmap.d/ shard), read the row's summary for this item.
3. Else the description argument: treat it as the sole seed.
4. Strategy grounding (optional): call read_strategy({ path }) on the harness MCP server when available; capture Target problem / Who it's for to keep stories aligned. Soft-fail silently when absent, invalid, or the server is unavailable.
5. Soft-degrade, never fail: when the seed is sparse (only a title, no BRD/roadmap/strategy), proceed and record a gap ("no BRD/roadmap context; requirements elicited from description only"). Do not abort.

Phase 2: DRAFT-PRD — Synthesize the First Draft

1. Write the PRD to docs/product-requirements/<item>/prd.md with these sections, each present even if thin:
   • Context (+ a link to the source BRD when present)
   • Goal / Problem — the user-facing outcome this item delivers
   • User Stories — each As a <role>, I want <goal>, so that <benefit>, with its acceptance criteria and a MoSCoW priority
   • Prioritization summary — the MoSCoW rollup (Must / Should / Could / Won't)
   • Non-Goals — what this item explicitly does not cover
   • Open Questions (chase list) — unresolved gaps, each phrased as a question
2. Acceptance criteria are EARS by default. Each criterion follows an EARS pattern:
   • Event-driven: "When <trigger>, the system shall <response>."
   • Unwanted: "If <condition>, then the system shall not <behavior>."
   • State-driven / optional: "While <state> / Where <feature>, the system shall <response>." Render a criterion as Given-When-Then instead only when a story is behavior-heavy and reads more clearly that way. Every criterion must be testable — an EARS trigger→response or a numeric bound.
3. Prioritize every story with MoSCoW (Must / Should / Could / Won't-this-time).
4. Tag gaps against the completeness rubric (below). Every rubric miss becomes a gap { id, section, question, severity: blocker | important | nice, status: open }. Do not invent facts to fill a section — an empty-because-unknown section is a gap, not a place to guess.

PRD completeness rubric

• Every user story has ≥1 acceptance criterion, else it is a gap.
• Every acceptance criterion is measurable — an EARS trigger→response or a numeric bound — else it is a gap.
• Every user story carries a MoSCoW priority, else it is a gap.
• Non-Goals is non-empty (state the boundary explicitly), else it is a gap.
• Every story traces to the Goal / Problem (or to an explicit gap).

Phase 3: GAP-INTERVIEW — Resolve What You Can

1. Ask ONE question at a time, in plain text. Order the gap queue by severity (blocker → important → nice). Ask the highest-severity open gap first, wait for the answer, then continue. Present each gap as a scannable multiple-choice table where options exist, and state a recommendation. Do NOT route questions through emit_interaction or AskUserQuestion — the human will not see them; plain text in your reply is the only reliable channel across all clients.
2. Fold each answer back into the PRD. Update the relevant story/criterion (source: interview) and move the gap open → resolved with the captured answer.
3. Mark unresolvable gaps as chase-list questions. If the author cannot answer (only the client/stakeholder can), keep the gap open and phrase it as a question to ask them.
4. Stop when the queue is drained — every gap is either resolved or open (chase-list). Do not loop past a drained queue inventing new questions.

Phase 4: FINALIZE — Ship and Hand Off

1. Finalize docs/product-requirements/<item>/prd.md with all sections populated and the Open Questions section listing every remaining open gap as a question.
2. Stay in your lane. Do not mutate the roadmap and never write an assignee — this skill operates on one already-picked item; claiming it is harness-execution's job at execution start. If no roadmap exists, there is nothing to touch.
3. Emit the handoff to harness-brainstorming via emit_interaction (type transition, suggestedNext: harness-brainstorming). State plainly that brainstorming will consume the PRD — seeding the spec's ## User Stories and ## Success Criteria from the PRD's EARS criteria — and then author the spec. Do not author the spec here.
4. Run harness validate.

Harness Integration

• read_strategy — Phase 1: read STRATEGY.md when present to align stories; never write it.
• gather_context — Phase 1 (optional): pull existing project/business knowledge to ground the domain.
• emit_interaction — Phase 4: record the transition to harness-brainstorming. The transition is recorded, not surfaced — any human-facing question is asked in plain text.
• harness validate — Phase 4: verify artifact placement and project health.
• Boundary with adjacent skills: product-advisor WRITES the BRD (upstream); this skill READS the BRD and WRITES the PRD; harness-brainstorming READS the PRD and WRITES the spec; acceptance-eval READS the spec's criteria and JUDGES them. This skill never crosses those lines.
• Portability: no hardcoded repo layout. The only hard requirement is a feature description. BRD, roadmap, and strategy are optional richer inputs consumed when present and soft-degraded when absent.

Success Criteria

• Running the skill with only a feature description (no BRD/roadmap/strategy) produces docs/product-requirements/<item>/prd.md with all sections present, none empty.
• Every user story has ≥1 acceptance criterion; every criterion is EARS-shaped (trigger→response) or carries a numeric bound.
• Every user story carries a MoSCoW priority.
• The gap interview asked one question at a time and folded each answer back (resolved gaps moved open → resolved); every unresolved gap ships as a chase-list question.
• The skill did not modify the roadmap and did not write an assignee.
• The handoff transitions to harness-brainstorming; no spec was authored.
• harness validate passes.

Rationalizations to Reject

Gates

• No un-criterioned stories. Every user story is either covered by a measurable acceptance criterion or shipped as an open chase-list gap. A story that is neither = Iron Law violation; stop and fix.
• No guessed requirements. An unknown section is a gap, not a place to invent facts.
• No spec authoring. This skill stops at the PRD; writing a proposal.md = gate violation. Hand off to harness-brainstorming.
• No roadmap mutation and no assignment. Writing the roadmap or the assignee field = gate violation.
• No hard failure on sparse input. Absent BRD/roadmap/strategy → description-only + recorded gap. Aborting because context is thin = gate violation.

Escalation

• The author cannot answer a blocker gap: keep it open, phrase it as a chase-list question for the client/stakeholder, and note in the handoff that brainstorming inherits an open blocker.
• Scope spans multiple independent capabilities: stop and suggest splitting into multiple items (one PRD per item), rather than one bloated PRD.
• No item slug resolvable: ask for a short name; without one, the artifact directory cannot be created.
• The item is a bug/chore/refactor with no user-facing behavior: say so and recommend going straight to harness-brainstorming — a PRD adds no value.

Examples

Example: PRD for a picked roadmap item with no BRD

Context: roadmap-pilot picked "Export dashboard to PDF." No BRD exists; the roadmap row is a one-line summary.

INGEST: No BRD found; read the roadmap row summary; strategy present (aligns with the "reporting" audience). Seed = row summary + description. Recorded no gap (seed sufficient).

DRAFT-PRD: Wrote docs/product-requirements/export-dashboard-to-pdf/prd.md. 3 user stories:

• As an analyst, I want to export the current dashboard to PDF, so that I can share it offline. [Must] — "When the user clicks Export → PDF, the system shall produce a PDF of the current dashboard within 5 seconds."
• As an analyst, I want the PDF to preserve applied filters, so that it reflects what I see. [Should] — "When a filter is applied, the exported PDF shall reflect the filtered data set."
• As an admin, I want export disabled for restricted dashboards. [Could] — "If the dashboard is marked restricted, then the system shall not offer the Export → PDF action."

Tagged 2 gaps: G1 (blocker) "max PDF page count?"; G2 (nice) "landscape or portrait default?".

GAP-INTERVIEW: Q1 (G1): "Cap the export at (A) 10 pages, (B) 50 pages, (C) no cap? Recommend B." → "B." Folded into story 1's criterion. Q2 (G2) → author defers → kept open as chase-list.

FINALIZE: PRD finalized; Open Questions lists G2. No roadmap mutation, no assignee. Emitted handoff → harness-brainstorming will seed the spec's Success Criteria from these EARS criteria. harness validate — passes.