Add Assumptions section to PRD template

prd/GUIDE.md

@@ -52,15 +52,16 @@ The workflow tracks exit criteria and tells you when it thinks clarification is
 
 **Command:** `/prd:draft`
 
-The workflow generates a PRD following a structured template with seven sections:
+The workflow generates a PRD following a structured template with eight sections:
 
 1. **Problem Statement** — why this work is needed and who's affected
 2. **Goals and Non-Goals** — measurable outcomes, what's explicitly out of scope, optional success metrics
 3. **Requirements** — functional requirements (FR-1, FR-2, ...) and non-functional requirements (NFR-1, NFR-2, ...) under a single section
 4. **Acceptance Criteria** — testable assertions defining "done"
-5. **Dependencies** — teams or systems this depends on (optional, omitted if none)
-6. **Risks** — product risks with owners and mitigations (optional, omitted if none)
-7. **Open Questions** — unresolved questions for reviewers to decide during PR review (optional, see below)
+5. **Assumptions** — statements believed true but not yet verified (optional, omitted if none)
+6. **Dependencies** — teams or systems this depends on (optional, omitted if none)
+7. **Risks** — product risks with owners and mitigations (optional, omitted if none)
+8. **Open Questions** — unresolved questions for reviewers to decide during PR review (optional, see below)
 
 Every requirement gets a stable ID (FR-1, NFR-1) and a source marker indicating where it came from: `[Jira: EDM-2324]`, `[Clarify: R1.Q3]`, or `[User]`.
 
@@ -136,7 +137,7 @@ Once you've published, the review cycle works like this:
    - **Factual correction** — update the PRD, acknowledge in reply
    - **Scope question** — reply explaining scope; may trigger a revision
    - **New requirement** — flagged for your decision
-   - **Open question resolution** — a reviewer answered one of your Section 7 questions
+   - **Open question resolution** — a reviewer answered one of your open questions
    - **Approval / positive** — acknowledge
    - **Out of scope** — explain why
 
@@ -148,25 +149,25 @@ Once you've published, the review cycle works like this:
 
 ## Open Questions as a Decision Tool
 
-Section 7 of the PRD — Open Questions — is not a dumping ground for "things we haven't figured out." It's a structured way to get specific decisions from specific people during PR review.
+The Open Questions section of the PRD is not a dumping ground for "things we haven't figured out." It's a structured way to get specific decisions from specific people during PR review.
 
 Each open question has three parts:
 - **The question itself** — clear and answerable
 - **An owner** — who should answer it (a specific person, role, or team)
 - **An impact statement** — which part of the PRD changes depending on the answer
 
 **Example:**
-> **7.1** Should port mapping support UDP in addition to TCP?
+> **8.1** Should port mapping support UDP in addition to TCP?
 > *Owner: networking team. Impact: FR-4 scope, NFR-2 performance targets.*
 
 When a reviewer answers an open question during PR review, `/prd:respond` handles the resolution:
 
-1. It identifies which Section 7 question the discussion addresses.
+1. It identifies which open question the discussion addresses.
 2. It synthesizes the review thread into a proposed answer.
 3. It determines the target section based on the question's impact field.
 4. It presents the resolution to you for approval.
 5. On approval, it incorporates the answer into the target section in final form — not as a narrative of the discussion, but as a proper requirement or constraint.
-6. It removes the resolved question from Section 7.
+6. It removes the resolved question from the Open Questions section.
 7. If all open questions are resolved, the entire section is removed.
 
 This turns PR review into a structured decision-making process. Instead of "LGTM" or vague "needs changes" comments, reviewers know exactly what you need from them.

prd/skills/draft.md

@@ -122,6 +122,11 @@ source material and PRD:
    requirement should have at least one source marker. Flag any that
    don't.
 
+5. **Assumptions coverage:** Confirm that any unverified preconditions
+   surfaced during clarification or implicit in the source material are
+   captured in the Assumptions section. If no unverified preconditions
+   exist, the section should be omitted.
+
 If this step introduces new `[Assumption: ...]` markers or TBD items,
 Step 6 will collect and resolve them.
 
@@ -132,8 +137,8 @@ and outstanding item. Collect the following from the document:
 
 1. Every `[Assumption: ...]` marker
 2. Every "To be determined" item
-3. Every risk in Section 6 that lacks an owner or mitigation
-4. Every open question in Section 7 that lacks an owner or impact
+3. Every risk in the Risks section that lacks an owner or mitigation
+4. Every open question in the Open Questions section that lacks an owner or impact
 
 If there are no items across all four categories, skip to Step 7.
 
@@ -143,9 +148,9 @@ Present the items to the user in conversation:
    document. List each with its section reference and the assumption text.
 2. **TBD markers:** List any "To be determined" items with their section
    references.
-3. **Unowned risks:** List any risks from Section 6 that lack an owner
+3. **Unowned risks:** List any risks from the Risks section that lack an owner
    or mitigation.
-4. **Unowned open questions:** List any open questions from Section 7
+4. **Unowned open questions:** List any open questions from the Open Questions section
    that lack an owner or impact.
 
 Ask the user to confirm, correct, or provide missing information for each

prd/skills/publish.md

@@ -164,11 +164,11 @@ Prepare the PR description and save it to `.artifacts/prd/{issue-number}/04-pr-d
 - Requirements completeness and accuracy
 - Scope (goals and non-goals)
 - Acceptance criteria clarity
-- Open questions (Section 7) that need resolution
+- Open questions that need resolution
 
 ### How to Review
 - Comment inline on specific sections
-- Review the open questions in Section 7 — these need your input
+- Review the open questions — these need your input
 - Approve when the PRD accurately reflects the agreed requirements
 ```
 

prd/skills/respond.md

@@ -96,12 +96,12 @@ Present each comment with a proposed response:
 **Proposed response:** {your suggested reply}
 **PRD change needed:** Yes — update Section 3.1, requirement 3
 
-### Comment 3 — {reviewer} on Section 7 (open question 7.2)
+### Comment 3 — {reviewer} on Open Questions (question 8.2)
 > {quoted comment text, possibly spanning multiple replies in a thread}
 
 **Category:** Open question resolution
 **Proposed resolution:** {synthesized answer from the discussion}
-**PRD change needed:** Yes — incorporate into Section {N}, remove open question 7.2
+**PRD change needed:** Yes — incorporate into Section {N}, remove open question 8.2
 
 ...
 ```
@@ -112,10 +112,10 @@ Wait for the user to approve, modify, or reject each response.
 
 #### Resolving open questions
 
-When reviewer comments relate to an open question from Section 7,
+When reviewer comments relate to an open question from the Open Questions section,
 synthesize the discussion into a proposed resolution:
 
-1. Identify which open question (7.1, 7.2, ...) the discussion relates to.
+1. Identify which open question (8.1, 8.2, ...) the discussion relates to.
 2. Read the full thread — there may be multiple reviewers with differing
    views. Synthesize the discussion into a single proposed resolution.
    Do not assume a single comment is the final answer. If reviewers
@@ -133,8 +133,8 @@ synthesize the discussion into a proposed resolution:
 5. After user approval, incorporate the answer into the target section,
    writing it in final form as if it was always the intent (do not
    narrate the resolution).
-6. Remove the resolved entry from Section 7.
-7. If Section 7 is now empty, remove the entire section (heading and
+6. Remove the resolved entry from the Open Questions section.
+7. If the Open Questions section is now empty, remove the entire section (heading and
    introductory text) from the PRD.
 
 #### PRD changes (other than open question resolutions)
@@ -268,11 +268,11 @@ Write or update `.artifacts/prd/{issue-number}/05-review-responses.md`:
 - **Response:** {what was replied}
 - **PRD change:** {Yes/No — description if yes}
 
-### Open question 7.2 resolved — {reviewer} thread on Section 7
+### Open question 8.2 resolved — {reviewer} thread on Open Questions
 - **Comment:** {summary of discussion thread}
 - **Category:** Open question resolution
 - **Response:** {what was replied}
-- **PRD change:** Yes — resolved open question 7.2, incorporated into Section 3.2 as NFR-3
+- **PRD change:** Yes — resolved open question 8.2, incorporated into Section 3.2 as NFR-3
 ```
 
 ### Step 6: Report to User

prd/skills/revise.md

@@ -146,7 +146,7 @@ Summarize what changed:
 - Section 2.3: Removed "UDP support" from non-goals
 
 ### Consistency Updates
-- Section 7: Added open question about UDP performance testing
+- Open Questions: Added open question about UDP performance testing
 ```
 
 ## Output

prd/templates/prd.md

@@ -41,25 +41,30 @@
 
 - [ ] {Concrete, verifiable condition that defines "done."}
 
-## 5. Dependencies
+## 5. Assumptions
+<!-- Optional: omit if no unverified assumptions underpin the requirements -->
+
+- {Statement believed to be true but not yet verified. If wrong, it may invalidate requirements or change the solution approach.}
+
+## 6. Dependencies
 <!-- Optional: omit if source material identifies no external dependencies -->
 
 - {Teams, systems, or work that must coordinate with this effort.}
 
-## 6. Risks
+## 7. Risks
 <!-- Optional: omit if no product risks were identified -->
 
-### 6.1 {Risk description}
+### 7.1 {Risk description}
 
 - **Owner:** {person or team}
 - **Mitigation:** {strategy, if known}
 
-## 7. Open Questions
+## 8. Open Questions
 <!-- Optional: omit if no open questions remain after clarification -->
 
 Questions for reviewers to resolve during PR review. Once answered, the resolution will be incorporated into the relevant section above and the entry removed.
 
-### 7.1 {Clear, answerable question directed at reviewers}
+### 8.1 {Clear, answerable question directed at reviewers}
 
 - **Owner:** {person or team who should answer}
 - **Impact:** {which section or decision this answer affects}

prd/templates/section-guidance.md

@@ -77,26 +77,35 @@ This file is read during the `/draft` phase. It is not included in the final out
 - 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."
 - Cover the primary use cases. Edge cases belong in a test plan, not here.
 
-## 5. Dependencies
+## 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.
+- 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.
+
+## 6. Dependencies
 
 - This section is **optional**. If the source material identifies no external dependencies, omit this section rather than writing "None."
 - List teams, services, APIs, or external systems that this work depends on or that depend on this work.
 - Include ordering constraints: "API changes must land before agent changes."
 
-## 6. Risks
+## 7. Risks
 
-- Each risk gets its own numbered subsection (6.1, 6.2, ...) with **Owner** and **Mitigation** fields.
+- Each risk gets its own numbered subsection (7.1, 7.2, ...) with **Owner** and **Mitigation** fields.
 - Risks describe what could go wrong and the mitigation strategy, if known. If no mitigation is known yet, write "To be determined."
 - Risks are permanent — they stay in the document even after the PRD is approved, unless the risk no longer applies.
 - **Product scope only.** Process-level risks (e.g., "schedule might slip") belong in project management tools, not the PRD.
 - This section is **optional**. If no product risks were identified during drafting or clarification, omit it.
 
-## 7. Open Questions
+## 8. Open Questions
 
-- Each open question gets its own numbered subsection (7.1, 7.2, ...) with **Owner** (person or team who should answer) and **Impact** (which section or decision the answer affects).
+- Each open question gets its own numbered subsection (8.1, 8.2, ...) with **Owner** (person or team who should answer) and **Impact** (which section or decision the answer affects).
 - **Frame as clear, answerable questions.** Write "Should tenants be able to configure scan sources, or is this fixed at install time?" not "To be determined — how much tenants configure versus fixed at install." The reader should know exactly what they're being asked.
 - Open questions are things that could not be resolved during the clarify phase and need broader stakeholder input via PR review.
 - Questions resolved during clarification should **not** appear here — they are already incorporated into the PRD body via locked decisions.
-- **Transient by design.** When an open question is resolved during PR review (`/prd respond`), the answer is incorporated into the appropriate section of the PRD (e.g., a scope decision becomes a non-goal, a constraint goes into NFRs) and the entry is removed from Section 7. By the time the PRD is approved, this section should be empty and removed.
+- **Transient by design.** When an open question is resolved during PR review (`/prd respond`), the answer is incorporated into the appropriate section of the PRD (e.g., a scope decision becomes a non-goal, a constraint goes into NFRs) and the entry is removed from this section. By the time the PRD is approved, this section should be empty and removed.
 - **Product scope only.** Process-level questions (e.g., "when should we update the Jira text?") belong in PR discussion, not in the PRD.
 - This section is **optional**. If no open questions remain after clarification, omit it entirely.