diff --git a/design/guidelines.md b/design/guidelines.md index a2851f7..c25bdf4 100644 --- a/design/guidelines.md +++ b/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 diff --git a/design/skills/draft.md b/design/skills/draft.md index 55eddb1..c01031a 100644 --- a/design/skills/draft.md +++ b/design/skills/draft.md @@ -87,8 +87,8 @@ 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 @@ -96,21 +96,45 @@ 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:** Convert each unresolved + `[Assumption: ...]` into either an Open Question entry (with Owner and + Impact) or a concrete "To be determined" statement, then remove the + assumption marker. Leave the resulting TBD/open-question items 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 +181,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 +197,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 +214,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 diff --git a/design/skills/publish.md b/design/skills/publish.md index 1b9efdd..874f57c 100644 --- a/design/skills/publish.md +++ b/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 ``` diff --git a/design/skills/respond.md b/design/skills/respond.md index fd0bf94..cd0b48b 100644 --- a/design/skills/respond.md +++ b/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`. diff --git a/design/templates/design.md b/design/templates/design.md index ae0c9e1..e989221 100644 --- a/design/templates/design.md +++ b/design/templates/design.md @@ -3,8 +3,8 @@ | Field | Value | |-------------|---------------------------------------| | Author(s) | {user} | -| Status | Draft | | Jira | [{issue-key}]({issue-url}) | +| PRD | [prd.md]({prd-relative-link}) | | Date | {today} | # 1. Overview @@ -109,20 +109,13 @@ Note any: - Version compatibility considerations # 8. Open Questions + -{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} diff --git a/design/templates/section-guidance.md b/design/templates/section-guidance.md index 7dbc119..eee413c 100644 --- a/design/templates/section-guidance.md +++ b/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. diff --git a/prd/guidelines.md b/prd/guidelines.md index 74b9af0..fe88ae7 100644 --- a/prd/guidelines.md +++ b/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. diff --git a/prd/skills/respond.md b/prd/skills/respond.md index 1d03909..7d402b7 100644 --- a/prd/skills/respond.md +++ b/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. diff --git a/prd/templates/section-guidance.md b/prd/templates/section-guidance.md index bf79b0f..99a9dd8 100644 --- a/prd/templates/section-guidance.md +++ b/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.