Unify open question handling and align PRD/design workflows

design/guidelines.md

@@ -40,7 +40,7 @@
 - Follow the section guidance (`templates/section-guidance.md`) for content standards.
 - Design-scoped goals are **implementation constraints**, not product outcomes. They complement — not duplicate — the PRD's goals.
 - Acceptance criteria must be **behavioral outcomes** (what the system does, testable from outside), not activities or implementation specifications. Implementation details belong in Implementation Guidance.
-- Open questions must track outcomes as decisions are made.
+- Open questions must have owners and impact statements.
 
 ## Escalation
 

design/skills/draft.md

@@ -87,30 +87,51 @@ document states the current position as if it was always the intent.
 
 Fill in the metadata header:
 - **Author(s):** The feature owner (ask if not known).
-- **Status:** Draft
 - **Jira:** Link to the source Feature issue
+- **PRD:** `[prd.md](prd.md)` — relative link to the co-located PRD
 - **Date:** Today's date
 
 **Mermaid diagrams:** Use them where they add clarity — especially for
 architecture (section 4.1) and data flow. Any Mermaid diagram type is
 allowed; choose the one that best communicates the concept. Always follow
 a diagram with a paragraph explaining what it illustrates.
 
-### Step 5: Populate the Review Notes Appendix
+### Step 5: Resolve Outstanding Items
 
-After writing all numbered sections, populate the Appendix: Review Notes:
+Before the design document can be saved, the author must validate every
+assumption and outstanding item. Collect the following from the document:
 
-1. **Assumptions:** Collect every `[Assumption: ...]` marker from the
-   document. List each with a section reference so reviewers can find the
-   context.
-2. **Items Needing Resolution:** List open questions from the Open Questions
-   section that don't yet have outcomes, plus any areas where confidence is
-   lower (e.g., scalability estimates, security analysis).
+1. Every `[Assumption: ...]` marker
+2. Every "To be determined" item
+3. Every open question in the Open Questions section that lacks an owner
+   or impact
 
-These items make assumptions and unresolved items visible to reviewers —
-not just the author. The same items should also appear in your conversation
-output (the "Present to User" step), but the appendix is what persists
-into the review.
+If there are no items across all three categories, skip to Step 6.
+
+Present the items to the user in conversation:
+
+1. **Assumptions:** List each with its section reference and the
+   assumption text.
+2. **TBD markers:** List any "To be determined" items with their section
+   references.
+3. **Incomplete open questions:** List any open questions missing an owner
+   or impact field.
+
+Ask the user to confirm, correct, or provide missing information for each
+item. Then apply the resolutions:
+
+- **Confirmed assumptions:** Rewrite the statement in its final form and
+  remove the `[Assumption: ...]` marker.
+- **Corrected assumptions:** Rewrite with the corrected information and
+  remove the marker.
+- **Resolved TBDs:** Replace the "To be determined" text with the
+  provided content.
+- **Items the user cannot resolve now:** Leave TBD markers or open
+  questions in place — these are genuine gaps, not drafting artifacts.
+
+After this step, the document should contain no `[Assumption: ...]`
+markers. Any remaining TBD markers or open questions represent real
+unknowns, not unvalidated AI judgment calls.
 
 ### Step 6: Verify Coverage
 
@@ -157,11 +178,10 @@ source material and design document:
    Open Questions — these are unresolved issues that may affect design
    decisions. Also check for any remaining TBD markers in the PRD, which
    represent genuine unknowns that may affect design choices. Import
-   relevant items into the design's Review Notes appendix or Open
-   Questions section.
+   relevant items into the design's Open Questions section.
 
-If this step discovers new gaps, assumptions, or open questions, update
-the Review Notes appendix (Step 5) to include them.
+If this step discovers new gaps, assumptions, or open questions, return
+to Step 5 to resolve them with the user.
 
 ### Step 7: Self-Review
 
@@ -174,13 +194,13 @@ Before presenting the design document, verify:
 - [ ] API changes include validation rules and concrete examples where helpful
 - [ ] Data model changes show field names, types, and constraints
 - [ ] Alternatives Considered includes at least one alternative for each non-trivial decision
-- [ ] Open Questions are numbered, clearly stated, and limited to design scope (no process-level actions)
+- [ ] Open Questions use numbered subsections, are clearly stated, include Owner and Impact fields, and are limited to design scope (no process-level actions)
 - [ ] No narration of editorial history — decisions are stated in final form, not as changes from a prior position
 - [ ] No vague language ("appropriate", "efficient", "standard" without specifics)
 - [ ] No scope reduction language ("v2", "simplified", "placeholder", "future enhancement")
 - [ ] Locked decisions from PRD clarification are respected
 - [ ] Terminology matches the PRD and codebase conventions
-- [ ] Assumptions are flagged inline and collected in the Review Notes appendix
+- [ ] No unresolved `[Assumption: ...]` markers remain in the document
 - [ ] The document is concise — no redundant paragraphs, no unnecessary repetition
 
 ### Step 8: Write Artifact
@@ -191,14 +211,10 @@ Save the design document to `.artifacts/design/{issue-number}/03-design.md`.
 
 Show the user the complete design document and highlight:
 - Key architectural decisions and their rationale
-- Any assumptions flagged
 - Open questions that need resolution
 - Areas where multiple approaches were viable and why you chose the one you did
-- Sections where confidence is lower (e.g., scalability estimates, security analysis)
-
-These items should mirror what's in the Review Notes appendix — the
-conversation output is for the author's immediate attention, the appendix
-is for all reviewers.
+- Sections where confidence is lower — suggest the user capture these as
+  open questions or TBD markers if they warrant reviewer attention
 
 ## Output
 

design/skills/publish.md

@@ -152,6 +152,12 @@ git -C "{docs_repo_path}" commit -m "Add design document for {issue-number}: {ti
 git -C "{docs_repo_path}" push -u origin design/{issue-number}
 ```
 
+Read the design document and identify specific areas that warrant reviewer
+attention:
+- Open questions from Section 8 (list each by title)
+- Sections with remaining TBD markers
+- Key architectural decisions that have significant trade-offs
+
 Prepare the PR description and save it to
 `.artifacts/design/{issue-number}/07-pr-description.md`:
 
@@ -165,14 +171,12 @@ Prepare the PR description and save it to
 {2-3 sentence summary of the design approach}
 
 ### Requesting Review On
-- Architecture and component design
-- Data model and API changes
-- Scalability, performance, and failure handling assessment
-- Open questions that need resolution
+{Populate from the design document. If there are open questions, TBD
+markers, or significant trade-offs, list each as a bullet. If none
+exist, write "General review — no specific items flagged."}
 
 ### How to Review
 - Comment inline on specific sections
-- Use the Open Questions section (Section 8) to flag new concerns
 - Approve when the design accurately reflects a viable implementation approach
 ```
 

design/skills/respond.md

@@ -70,6 +70,7 @@ Group comments into categories:
 | **Scope question** | Draft a reply; may need `/revise` |
 | **New requirement** | Flag for user decision — update design or defer |
 | **Approval / positive** | Acknowledge |
+| **Open question resolution** | Resolve the open question (see Step 4) |
 | **Out of scope** | Draft a reply explaining why |
 
 ### Step 3: Propose Responses
@@ -85,21 +86,52 @@ Present each comment with a proposed response:
 **Category:** Design alternative
 **Proposed response:** {your suggested reply}
 **Design change needed:** Yes — update Section 4.1 architecture
+
+### Comment 2 — {reviewer} on Open Questions (question 8.2)
+> {quoted comment text}
+
+**Category:** Open question resolution
+**Proposed resolution:** {synthesized answer from reviewer discussion}
+**Design change needed:** Yes — incorporate into Section {N}, remove open question 8.2
 ```
 
 Wait for the user to approve, modify, or reject each response.
 
 ### Step 4: Apply Approved Changes
 
-#### Design document changes
-
-For comments that require design doc changes:
-
-**Check locked decisions:** Before applying any change, read the "Locked
+**Check locked decisions:** Before applying any design document change —
+whether a direct edit or an open question resolution — read the "Locked
 Decisions" section of `.artifacts/prd/{issue-number}/02-clarifications.md`
 (if it exists). If a requested change contradicts a locked decision, flag
 the conflict rather than applying the change.
 
+#### Resolving open questions
+
+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 subsection 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
+   disagree and no consensus is apparent, present the competing positions
+   to the user and ask them to decide rather than fabricating a
+   compromise that nobody advocated.
+3. Determine the appropriate target section based on the **Impact** field
+   of the open question — e.g., an architecture decision updates §4.1,
+   a data model constraint updates §4.2, a security requirement updates
+   §4.5.
+4. Present the proposed resolution to the user: show which open question
+   is being resolved, the synthesized answer, where it will be placed in
+   the design document, and the proposed text. The user may approve,
+   correct, or rewrite the synthesis.
+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 the Open Questions section.
+7. If the Open Questions section is now empty, remove the entire section
+   (heading and introductory text) from the design document.
+
 **Update the local artifact:** Update
 `.artifacts/design/{issue-number}/03-design.md`.
 

design/templates/design.md

@@ -3,8 +3,8 @@
 | Field       | Value                                 |
 |-------------|---------------------------------------|
 | Author(s)   | {user}                                |
-| Status      | Draft                                 |
 | Jira        | [{issue-key}]({issue-url})            |
+| PRD         | [prd.md](prd.md)                      |
 | Date        | {today}                               |
 
 # 1. Overview
@@ -109,20 +109,13 @@ Note any:
 - Version compatibility considerations
 
 # 8. Open Questions
+<!-- Optional: omit if no open questions remain after drafting -->
 
-{Numbered list. Track outcomes as decisions are made — preserve the original
-question alongside the resolution.}
+Questions for reviewers to resolve during PR review. Once answered, the
+resolution will be incorporated into the relevant section above and the
+entry removed.
 
-1. **{Question}**
+## 8.1 {Clear, answerable question directed at reviewers}
 
-   Outcome: {Resolution, or "Open"}
-
-# Appendix: Review Notes
-
-## Assumptions
-
-- [{Section reference}] {Assumption made and rationale}
-
-## Items Needing Resolution
-
-- [{Section reference}] {Item that needs reviewer attention}
+- **Owner:** {person or team who should answer}
+- **Impact:** {which section or decision this answer affects}

design/templates/section-guidance.md

@@ -29,8 +29,8 @@ These apply across all sections:
 ### Metadata Header
 
 - **Author(s):** The feature owner.
-- **Status:** One of Draft, In Review, Final.
 - **Jira:** Link to the Feature issue.
+- **PRD:** Relative link to the PRD (`prd.md`) — co-located in the same docs repo directory.
 - **Date:** Date of last significant update.
 
 ### 1. Overview
@@ -128,15 +128,9 @@ This is the core section. All subsections (4.1–4.8) are required. If a subsect
 
 ### 8. Open Questions
 
-- Number each question.
-- Track outcomes alongside original questions — do not delete resolved questions.
-- Format: question text, then "Outcome:" with resolution or "Open".
+- Each open question gets its own numbered subsection with **Owner** (person or team who should answer) and **Impact** (which section or decision the answer affects).
+- **Frame as clear, answerable questions.** Write "Should the backup archive include a file manifest, or is a SHA256 checksum sufficient?" not "To be determined — archive validation approach."
+- Open questions are things that could not be resolved during drafting and need broader stakeholder input via PR review.
+- **Transient by design.** When an open question is resolved during PR review (`/respond`), the answer is incorporated into the appropriate section of the design document (e.g., an architecture decision updates §4.1, a security constraint updates §4.5) and the entry is removed from this section. By the time the design PR is approved, this section should be empty and removed.
 - **Design scope only.** This section contains technical design questions and risks. Process-level actions (e.g., "update Jira ticket text," "schedule a meeting to discuss") belong in the PR description or review discussion, not in the design document.
-- Open questions with significant design impact should be resolved before the document moves to "Final" status.
-
-## Appendix: Review Notes
-
-- This appendix collects items that reviewers should pay attention to. It makes assumptions and unresolved items visible to all reviewers, not just the author.
-- **Assumptions:** List every assumption flagged during drafting with `[Assumption: ...]` markers. Include the section reference so reviewers can find the context. These are judgment calls the AI made where the source material (PRD, codebase) was ambiguous — reviewers should confirm or correct them.
-- **Items Needing Resolution:** List open questions from Section 8 that don't yet have outcomes, plus any areas where confidence is lower (e.g., scalability estimates, security analysis). Cross-reference the section so reviewers can navigate directly.
-- Populate this appendix during `/draft`. The items listed here should match those presented in the conversation output (the "Present to User" step of draft.md) — the conversation output is ephemeral, the appendix persists into review.
+- This section is **optional**. If no open questions remain after drafting, omit it entirely.

prd/guidelines.md

@@ -31,7 +31,7 @@
 - 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 written as **testable assertions**, not activities.
+- Acceptance criteria must be **behavioral outcomes** (what the system does, testable from outside), not activities or implementation specifications.
 - Requirements must be testable.
 - Open questions must have owners and impact statements.
 

prd/skills/respond.md

@@ -110,12 +110,19 @@ Wait for the user to approve, modify, or reject each response.
 
 ### Step 4: Apply Approved Changes
 
+**Check locked decisions:** Before applying any PRD change — whether a
+direct edit or an open question resolution — read the "Locked Decisions"
+section of `.artifacts/prd/{issue-number}/02-clarifications.md` (if it
+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.
+
 #### Resolving open questions
 
 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 (8.1, 8.2, ...) the discussion relates to.
+1. Identify which open question subsection 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
@@ -137,16 +144,6 @@ synthesize the discussion into a proposed resolution:
 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)
-
-For comments that require PRD changes:
-
-**Check locked decisions:** Before applying any PRD change, read the
-"Locked Decisions" section of `.artifacts/prd/{issue-number}/02-clarifications.md`
-(if it 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.
-
 **Update the local artifact:** Update `.artifacts/prd/{issue-number}/03-prd.md`
 in the source repo.
 

prd/templates/section-guidance.md

@@ -102,7 +102,7 @@ This file is read during the `/draft` phase. It is not included in the final out
 
 ## 8. Open Questions
 
-- 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).
+- Each open question gets its own numbered subsection 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.