# Product Requirements > Product Requirements - Skill: `intense-visions/product-requirements` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add intense-visions/product-requirements` - Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/product-requirements/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Intense-Visions (https://skillmd.com/u/intense-visions) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/intense-visions/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//`. - **`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//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//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 , I want , so that `, 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 ``, the system shall ``." - Unwanted: "If ``, then the system shall not ``." - State-driven / optional: "While `` / Where ``, the system shall ``." 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//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//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 | Rationalization | Reality | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "This story's outcome is obvious, so I can skip the acceptance criterion" | The Iron Law: every story carries a measurable criterion or a named gap. An implied criterion cannot be judged by `acceptance-eval`. | | "There's no BRD/roadmap, so I can't run" | The only hard requirement is a description. Soft-degrade to description-only and record a gap — never abort. | | "I'll write the spec while I'm here since the requirements are clear" | This skill stops at the PRD. Authoring a `proposal.md` is a gate violation — hand off to `harness-brainstorming`. | | "I'll mark the item in-progress / assign it so the pick is recorded" | This skill never mutates the roadmap or writes `assignee`. Claiming happens at execution start; assigning here makes the orchestrator skip the item. | | "Plain prose criteria are fine; EARS is ceremony" | EARS is the grammar `harness-planning`/`harness-brainstorming` consume and the shape `acceptance-eval` reads as MEASURABLE. Freeform criteria drift to un-judgable. | ## 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.