diff --git a/prd/GUIDE.md b/prd/GUIDE.md index b1ab054..841f046 100644 --- a/prd/GUIDE.md +++ b/prd/GUIDE.md @@ -8,6 +8,8 @@ This guide explains how to drive the workflow. For the command reference and art These principles shaped every phase of the workflow. Understanding them will help you predict how the workflow behaves and why. +**User-facing focus.** A PRD describes what users need to be able to do and experience — capabilities and outcomes, not design or implementation. If a requirement describes specific API fields, references where in the code something will happen, or describes something a user wouldn't observe, it belongs in a design document or enhancement proposal, not the PRD. The workflow enforces this boundary at every phase. + **Fidelity to source material.** Every requirement in the PRD traces back to a Jira issue, a clarification you gave, or a direct instruction. The workflow does not invent requirements or fill gaps with assumptions. **User agency.** The PRD represents *your* understanding of the problem, not the AI's interpretation. The workflow never auto-advances between phases — you decide when to move on, go back, or skip ahead. diff --git a/prd/SKILL.md b/prd/SKILL.md index 844fa95..b155e11 100644 --- a/prd/SKILL.md +++ b/prd/SKILL.md @@ -1,6 +1,6 @@ --- name: prd -version: 0.2.0 +version: 0.3.0 description: >- Requirements-to-PRD workflow that ingests requirements from Jira, clarifies ambiguities through iterative Q&A, drafts a Product Requirements Document, diff --git a/prd/guidelines.md b/prd/guidelines.md index d0e7398..343cde2 100644 --- a/prd/guidelines.md +++ b/prd/guidelines.md @@ -17,6 +17,7 @@ - No modifying Jira issues. This workflow is read-only with respect to Jira. - No committing to `main` directly. Use feature branches for `/publish`. - **No scope reduction.** Never silently simplify, defer to "v2", use "placeholder", or say "future enhancement" to reduce scope. If scope won't fit, flag it explicitly and propose a split — don't reduce. +- **No design details.** PRDs describe what users need to do and experience, not how the system is built. Do not include specific API fields, internal system architecture, code-level implementation details, or anything the user wouldn't be able to observe. If it describes how something works rather than what a user can do, it belongs in a design document or enhancement proposal, not the PRD. - Locked decisions from `/clarify` are binding. No phase may contradict a locked decision without explicit user override. - **No personal names in generated content.** Replace references to individuals from Jira tickets, comments, or other source material with role-based descriptions (e.g., "the security reviewer noted…", "the reporter described…"). When the person's role is unknown, use a generic attribution ("a reviewer noted…", "feedback identified…") or drop the attribution and state the finding directly. Author metadata fields are exempt — they identify the document author, not referenced individuals. @@ -32,7 +33,8 @@ - Follow the PRD template structure (`templates/prd.md`). Do not invent new sections without user approval. Sections the section guidance marks as optional may be omitted when the source material provides no relevant content. - Follow the section guidance (`templates/section-guidance.md`) for content standards in each section. - Goals must be measurable outcomes, not activities. -- Acceptance criteria must be **behavioral outcomes** (what the system does, testable from outside), not activities or implementation specifications. +- Acceptance criteria must be **user-observable behavioral outcomes**, not activities, implementation specifications, or internal system states. +- Requirements must mention the UI and CLI alongside the API where applicable — not default to API-only. - Requirements must be testable. - Open questions must have owners and impact statements. diff --git a/prd/skills/clarify.md b/prd/skills/clarify.md index 1a61583..482e43d 100644 --- a/prd/skills/clarify.md +++ b/prd/skills/clarify.md @@ -42,14 +42,24 @@ Analyze the requirements against these categories: |----------|-----------------| | **Scope** | Are boundaries clear? What's in vs. out? | | **Users/Personas** | Who are the target users? Are roles defined? | -| **Functional gaps** | Are there features mentioned but not specified? | -| **Acceptance criteria** | Does each requirement have a way to verify it? | -| **Edge cases** | What happens at boundaries? Error states? | -| **Constraints** | Performance, security, compatibility requirements stated? | +| **User capabilities** | Are there capabilities mentioned but not fully described from the user's perspective? | +| **Acceptance criteria** | Does each requirement have a way to verify it from the user's perspective? | +| **Edge cases** | What does the user experience at boundaries? Error states? | +| **User-observable qualities** | Are responsiveness, reliability, security, accessibility expectations clear? | | **Dependencies** | Are external dependencies identified? | | **Contradictions** | Do any requirements conflict with each other? | | **Assumptions** | What's implied but not stated? | +**Stay user-facing.** Questions should focus on what users need to do and +experience, not on implementation choices. If the source material contains +design details (API fields, internal architecture), ask about the user +capability they support — not about the design itself. Design decisions +are resolved in design documents, not during PRD clarification. + +**Cover all interfaces.** When the source material describes a capability +only in terms of the API, ask whether a UI or CLI also exposes it before +adding them. When multiple interfaces exist, list UI and CLI first. + For each gap found, note: - What's missing or unclear - Why it matters (how it affects the PRD) diff --git a/prd/skills/draft.md b/prd/skills/draft.md index 930c856..f7f438c 100644 --- a/prd/skills/draft.md +++ b/prd/skills/draft.md @@ -5,15 +5,19 @@ description: Generate the PRD from clarified requirements using the template and # Draft PRD Skill -You are a technical writer specializing in product requirements documents. +You are writing from a Product Manager's perspective. Your job is to synthesize the ingested requirements and clarification -answers into a structured PRD that follows the project template. +answers into a structured PRD that describes user-facing capabilities +and outcomes. ## Your Role Read the source material, apply the template structure, follow the section -guidance, and produce a PRD that accurately represents the agreed-upon -requirements. Every statement must be traceable to the source material. +guidance, and produce a PRD that accurately represents what users need to +be able to do and experience. Every statement must be traceable to the +source material. Keep the focus on user stories and capabilities — design +details (API fields, internal architecture, code-level mechanisms) belong +in design documents, not the PRD. ## Critical Rules @@ -68,9 +72,10 @@ Generate the PRD following the template structure. For each section: 1. Read the section guidance for that section 2. Draw content from the source material -3. Apply the quality standards (measurable goals, testable requirements, verifiable acceptance criteria) -4. Tag each requirement with its source marker(s) (`[Jira: EDM-2324]`, `[Clarify: R1.Q3]`, or `[User]`), following the consolidation guidance in the section guidance General Rules -5. Flag any assumptions or judgment calls with an inline note: `[Assumption: ...]` +3. Apply the quality standards (measurable goals, testable requirements, user-verifiable acceptance criteria) +4. If source material includes design details (API fields, internal architecture, code-level mechanisms), elevate them to the user-facing capability they support rather than transcribing the design detail into the PRD. Constraints that users directly encounter (input validation rules, length limits, allowed values, format restrictions) are user-facing requirements, not design details — preserve them. +5. Tag each requirement with its source marker(s) (`[Jira: EDM-2324]`, `[Clarify: R1.Q3]`, or `[User]`), following the consolidation guidance in the section guidance General Rules +6. Flag any assumptions or judgment calls with an inline note: `[Assumption: ...]` **Incorporating clarifications:** When a clarification changed the scope or corrected an assumption from the source material, write the @@ -183,6 +188,8 @@ Before presenting the PRD, verify: - [ ] All locked decisions from clarification are reflected - [ ] Success Metrics table is populated when the source material provides quantifiable targets (omit the subsection otherwise) - [ ] No narration of editorial history — requirements are stated in final form, not as changes from a prior position +- [ ] No design details — no specific API fields, internal architecture, code locations, or non-user-observable behavior. Every requirement describes something a user can do, see, or experience. +- [ ] Requirements mention UI and CLI alongside the API where applicable — not API-only - [ ] No vague language ("appropriate", "efficient", "standard" without specifics) - [ ] No scope reduction language ("v2", "simplified", "placeholder", "future enhancement") - [ ] The document is concise — no unnecessary repetition or filler diff --git a/prd/skills/respond.md b/prd/skills/respond.md index 7d402b7..8720825 100644 --- a/prd/skills/respond.md +++ b/prd/skills/respond.md @@ -117,6 +117,12 @@ exists). If a requested change contradicts a locked decision, flag the conflict to the user rather than applying the change — locked decisions are binding and cannot be overridden without explicit user approval. +**Check for design details:** If a reviewer comment or proposed change +introduces design details (specific API fields, internal architecture, +code-level mechanisms, or non-user-observable behavior), flag them and +elevate to user-facing capabilities per the "No design details" hard +limit in `../guidelines.md`. Do not incorporate design details into the PRD. + #### Resolving open questions When reviewer comments relate to an open question from the Open Questions section, diff --git a/prd/skills/revise.md b/prd/skills/revise.md index cc5bba3..20eec01 100644 --- a/prd/skills/revise.md +++ b/prd/skills/revise.md @@ -56,6 +56,7 @@ After applying changes, verify: - If dependencies changed, are risks updated? - Do any changes contradict a locked decision in `02-clarifications.md`? If so, flag the conflict to the user — locked decisions are binding and cannot be overridden without explicit user approval. - If requirements were removed or simplified, verify this was explicitly requested by the user. Flag any silent scope reduction. +- If any revision introduces design details (specific API fields, internal architecture, code-level mechanisms, or non-user-observable behavior), flag them and elevate to user-facing capabilities per the "No design details" hard limit in `../guidelines.md`. - If any `[Assumption: ...]` markers were introduced during this revision, resolve them with the user before saving — the published PRD should contain no assumption markers. ### Step 5: Update Artifact diff --git a/prd/templates/prd.md b/prd/templates/prd.md index ad2ba7a..aa18f9c 100644 --- a/prd/templates/prd.md +++ b/prd/templates/prd.md @@ -31,15 +31,15 @@ ### 3.1 Functional Requirements -- **FR-1:** {What the system must do. Each requirement should be testable.} [source] +- **FR-1:** {What the user must be able to do or experience. Each requirement should be testable from the user's perspective.} [source] ### 3.2 Non-Functional Requirements -- **NFR-1:** {Performance, scalability, security, compatibility constraints.} [source] +- **NFR-1:** {User-observable quality attributes: responsiveness, reliability, security, accessibility, compatibility.} [source] ## 4. Acceptance Criteria -- [ ] {Concrete, verifiable condition that defines "done."} +- [ ] {Concrete, user-verifiable condition that defines "done."} ## 5. Assumptions diff --git a/prd/templates/section-guidance.md b/prd/templates/section-guidance.md index 99a9dd8..89f5043 100644 --- a/prd/templates/section-guidance.md +++ b/prd/templates/section-guidance.md @@ -22,7 +22,9 @@ This file is read during the `/draft` phase. It is not included in the final out - Do not invent features, constraints, or details not supported by the ingested requirements or clarification responses. - If information for a section is genuinely unavailable after clarification, write "To be determined — [what's needed]" rather than fabricating content. - **Formatting restraint.** Use bold sparingly for genuine emphasis — terms the reader must not miss or that distinguish this requirement from a similar one. When every noun phrase is bold, nothing stands out and the document becomes harder to scan. -- **Diagrams.** When a visual clarifies architecture, data flow, or component relationships in any section, use Mermaid diagrams. Only include a diagram when it adds clarity that prose alone cannot. +- **User-facing focus.** PRDs are written from a Product Manager's perspective. Every requirement should describe something a user can do, see, or experience. Signs that a requirement has strayed into design: it describes specific API fields, it references where in the code something will happen, or it describes something the user wouldn't be able to observe. Those details belong in design documents or enhancement proposals, not the PRD. +- **Cover all user interfaces.** Requirements should mention whichever interfaces actually expose the capability (UI, CLI, API). When the source material only mentions the API, ask during clarification whether a UI or CLI also exists before adding them. When multiple interfaces exist, list UI and CLI first. +- **Diagrams.** When a visual clarifies user flows, interaction sequences, or system boundaries in any section, use Mermaid diagrams. Only include a diagram when it adds clarity that prose alone cannot. - Use only `flowchart` or `sequenceDiagram` types (these render reliably on GitHub). - Keep diagrams simple: labeled nodes, clear edge labels, no styling directives (`style`, `classDef`, color codes). - Always introduce a diagram with a sentence explaining what it shows and why it's relevant. @@ -58,7 +60,8 @@ This file is read during the `/draft` phase. It is not included in the final out ### 3.1 Functional Requirements - **Assign a stable ID** to each requirement (FR-1, FR-2, ...). These IDs are referenced by acceptance criteria, design documents, and task breakdowns. -- Each requirement should be **testable**. If you can't describe how to verify it, it isn't specific enough. +- Each requirement should describe a **user-facing capability** — what a user can do, see, or experience. If a requirement describes an API field, internal data structure, or code-level mechanism, elevate it to the user behavior it enables. For example, "the API accepts a `protocol` field" is design; "Users can specify whether a port mapping uses TCP or UDP" is a requirement. +- Each requirement should be **testable**. If you can't describe how to verify it from a user's perspective, it isn't specific enough. - Use "must" for mandatory requirements, "should" for important but negotiable, "may" for optional. - Group related requirements under subheadings if the list exceeds 8 items. - Trace each requirement back to the source (e.g., "From Jira acceptance criteria," "Per clarification Q3"). @@ -67,21 +70,21 @@ This file is read during the `/draft` phase. It is not included in the final out - **Assign a stable ID** to each requirement (NFR-1, NFR-2, ...). These IDs are referenced by design documents and task breakdowns. - Include only constraints that are stated or clearly implied by the source material. -- Common categories: performance, scalability, security, compatibility, availability, observability. -- Be concrete: "API response time under 200ms at p95" not "the system should be fast." +- Frame NFRs as **user-observable qualities**: responsiveness, reliability, scalability, security, accessibility, compatibility, observability. For example, "Users experience page load times under 2 seconds" not "the system should be fast." When the API is the user's interface, API-level targets like "Users receive API responses within 200ms at p95" are valid user-observable NFRs. +- Be concrete about user impact: "Users can complete a deployment in under 30 seconds" not "the system should be fast." ## 4. Acceptance Criteria - These define **done**. They drive the testing strategy. - Write as checkboxes — each should be independently verifiable. -- Acceptance criteria are the bridge between requirements and implementation. If a requirement says "must support port mappings," the acceptance criterion says "A user can specify port mappings in the format host:container and the system correctly exposes the mapped ports." +- Acceptance criteria describe what a user can verify. If a requirement says "must support port mappings," the acceptance criterion says "A user can specify port mappings in the format host:container and the system correctly exposes the mapped ports." Do not include criteria that require inspecting internal state or database records. When the API is the user's interface, API responses and status codes are valid user-observable evidence. - Cover the primary use cases. Edge cases belong in a test plan, not here. ## 5. Assumptions - This section is **optional**. If the requirements rest on no unverified assumptions, omit this section rather than writing "None." - An assumption is a statement the PRD treats as true but that has not been confirmed. If it turns out to be false, one or more requirements may need to change. -- Good assumptions surface hidden preconditions. These may be technical ("The existing auth service supports OIDC," "Operators have cluster-admin privileges," "The upstream API is stable and versioned") or scope-related ("This feature assumes no UX/UI changes are needed," "Only validation and documentation work is required"). Scope assumptions often represent the reasoning behind release planning — if they turn out to be false, the work may need to be re-scoped or re-prioritized. +- Good assumptions surface hidden preconditions. These may be about the environment ("Users have cluster-admin privileges," "The upstream service is stable and versioned") or scope-related ("This feature assumes no UX/UI changes are needed," "Only validation and documentation work is required"). Scope assumptions often represent the reasoning behind release planning — if they turn out to be false, the work may need to be re-scoped or re-prioritized. - Do not list things that are verifiable right now — verify them and state them as requirements or constraints instead. - Assumptions are valuable specifically because they invite challenge. Reviewers should be able to look at this list and say "that one isn't true" before implementation begins. - **Not the same as `[Assumption: ...]` markers.** Inline `[Assumption: ...]` markers flag AI judgment calls during drafting — they are transient artifacts resolved with the user in Step 6 and never appear in the final document. This section captures product-level preconditions that the user has acknowledged but that remain unverified.