@gordon.gan/specflow 1.0.0

package/prompts/refine/brainstorm.md

@@ -0,0 +1,241 @@
+> **HARD GATE**: No implementation or scaffolding until user confirms refined artifacts.
+
+<!-- SOURCE: Superpowers brainstorming (skills/brainstorming/SKILL.md) + SpecFlow refine-phase adaptation -->
+
+# Refine-Phase Brainstorming: Attacking Deep Review
+
+> This prompt is for **ATTACKING DEEP REVIEW** of plan-phase artifacts.
+> NOT from-scratch brainstorming. The 4 artifacts (proposal, specs, design, tasks)
+> already exist and must be challenged, deepened, and possibly updated.
+
+Plan already produced first-iteration drafts. Your job in refine is to **attack those drafts**:
+surface glossed-over assumptions, propose unconsidered alternatives, explore omitted boundaries,
+and question scope — then update whichever artifacts the discussion shows are out of sync.
+
+## Entry Context
+
+Before running this brainstorming flow, you MUST have read:
+
+- `specflow/changes/<name>/proposal.md`
+- `specflow/changes/<name>/specs/**/*.md`
+- `specflow/changes/<name>/design.md`
+- `specflow/changes/<name>/tasks.md`
+- `specflow/specs/` baseline (main specs) for reference
+- `.claude/specflow/prompts/refine/update-artifacts.md` (the delegated artifact-update methodology)
+
+If any of the four change artifacts is missing, stop and tell the user to run `/specflow:plan` first.
+
+## Iteration Rules
+
+- **Minimum 2 rounds** is unconditional. Round 1 is unconditional. Round 2 is unconditional.
+  Do not ask the user "should we keep going?" before round 2 finishes — minimum 2 rounds means
+  at least 2 rounds, every time.
+- After round 2, AI performs **semantic judgment of convergence** (see Step 8). If
+  meaningful unaddressed challenges, scope concerns, or stale artifact states remain,
+  run another round. If nothing substantive remains, proceed to the final next-step
+  announcement.
+- **No upper limit.** Refine continues as long as each round produces substantive new challenges.
+- The AI MUST explicitly announce `Round N start` when a round begins and `Round N end` when
+  the round's updates and diff summary are complete, so the user always knows which round they
+  are in.
+- The user may request additional rounds at any time (even after AI judges convergence); user
+  request overrides AI convergence judgment.
+
+## The 9-Step Process (per round)
+
+Each round runs all 9 steps in order. Steps 1–2 are where the 4 challenge behaviors are
+injected; steps 3–5 carry the discussion into artifacts; steps 6–8 close the round.
+
+### Step 1 — Examine existing artifacts (inject Challenge Behavior #1)
+
+Re-read all 4 plan-phase artifacts with fresh eyes. This is not a summary exercise — look for
+what the plan *did not* say. Explicitly INJECT **Challenge Behavior #1 (challenge plan's
+assumptions)** here: list assumptions the plan glossed over and explain why each matters. Each
+round MUST produce this list of challenged assumptions, even if shorter than the previous round.
+
+### Step 2 — Ask clarifying questions (inject Challenge Behaviors #3 and #4)
+
+Ask the user clarifying questions one at a time, prefering multiple-choice where the options
+are reasonably enumerable. This is where you INJECT **Challenge Behavior #3 (explore omitted
+boundaries)** — survey edge cases, permissions, error modes, non-functional concerns absent
+from specs — and **Challenge Behavior #4 (question scope)** — ask whether the change is too
+broad, too narrow, or should be split. Clarifying questions are how you explore boundaries
+the plan omitted and how you question scope with the user directly.
+
+Keep per-message questions small (1 question per message). Batch the mental exploration but
+serialize the user-facing dialogue.
+
+### Step 3 — Propose 2-3 approaches with trade-offs (inject Challenge Behavior #2)
+
+For every non-trivial design decision surfaced by Steps 1–2 (both the ones in the existing
+`design.md` and new ones revealed by this round's challenges), INJECT **Challenge Behavior #2
+(propose new options)**: for each existing decision, propose alternative approaches not
+considered in the plan — at least 2 such alternatives per decision, each with pros/cons and
+a recommendation.
+
+The 2-3 approaches MUST include the currently-chosen option from `design.md` PLUS genuinely
+different alternatives — not cosmetic variants. If the existing choice still wins, say so
+explicitly with a rationale that references the alternatives considered.
+
+### Step 4 — Present design sections (show proposed updates)
+
+Present the design sections being proposed for update. Scale each section to its complexity:
+a few sentences for straightforward points, up to 200–300 words when a decision is nuanced.
+Show the user what would change in `design.md`, which `specs/**/*.md` files would be touched,
+and whether `proposal.md` or `tasks.md` are affected. Ask after each significant section
+whether the direction looks right.
+
+### Step 5 — Write/update artifacts (DELEGATE)
+
+DELEGATE to `.claude/specflow/prompts/refine/update-artifacts.md` for impact analysis, user
+scope choice (A/B/C), format preservation rules, per-artifact routing, and post-update
+validation.
+
+Do not re-invent the artifact update rules here — the delegated prompt owns them. Return here
+only after the delegated update-artifacts prompt reports back that files are written and
+validated.
+
+### Step 6 — Self-review (format + consistency)
+
+With fresh eyes on the just-updated artifacts:
+
+1. **Placeholder scan** — no "TBD", "TODO", or vague requirements; fix inline.
+2. **Internal consistency** — sections do not contradict each other; architecture matches
+   feature descriptions; spec scenarios match design decisions.
+3. **Format compliance** — run `specflow validate` on any updated spec file. See
+   `update-artifacts.md` "Post-update Validation" section for the expected behavior on
+   validation failure (revert + report).
+4. **Round-traceable discussion trail** — any newly resolved decision must appear in
+   `design.md` under `## Design Decisions` as a `### Decision N: <name>` block with
+   `**Options considered:**`, `**Chosen:**`, and `**Rationale:**`.
+
+Fix issues inline. Do not re-enter Step 5 unless a revert happens.
+
+### Step 7 — Request user approval for this round
+
+Present the round's diff summary (see `update-artifacts.md` "Diff Summary Format") and ask:
+
+> "Round N produced these updates. Does the direction look correct, or do you want to revisit
+> anything before I continue to Step 8 (convergence judgment)?"
+
+Wait for user acknowledgement. If the user requests revisions, loop back to Step 3 or Step 5
+as appropriate within this round.
+
+### Step 8 — Judge convergence
+
+Apply the convergence rules (see also "Convergence Criteria" section below):
+
+- **If this was Round 1**: unconditionally continue. Announce `Round 1 end` and immediately
+  start Round 2 from Step 1. The minimum-2-rounds rule is non-negotiable.
+- **If this was Round 2 or later**: perform AI semantic convergence judgment. Ask
+  yourself:
+  - "Are there still meaningful unaddressed challenges from the 4 challenge behaviors?"
+  - "Are there still open clarifying questions from Step 2?"
+  - "Are there scope concerns that have not been resolved or explicitly parked?"
+  - "Is any artifact still in a state that doesn't reflect the full discussion?"
+  - "Has the user introduced a new consideration in the latest round that has not yet
+    propagated into the artifacts?"
+- **If ANY of the above yields yes**: convergence NOT reached. Loop back to Step 1 for the
+  next round.
+- **If ALL yield no**: convergence reached. Proceed to Step 9.
+
+Remember: the user may override convergence. If after AI announces convergence the user says
+"actually, let's dig into X," that is treated as a new round — do not skip to Step 9.
+
+### Step 9 — Next-step indication (only at final convergence)
+
+Only reached when Step 8 produced "converged" AND the user did not override it.
+
+Announce clearly:
+
+> "Refine converged after N rounds. All artifacts have been updated and validated. Please
+> review the final state of proposal.md, specs/, design.md, tasks.md. Confirm that this
+> refined state is what you want — on confirmation I will mark phase as `refined` and you
+> can run `/specflow:build` next."
+
+Do NOT invoke phase transition directly from this prompt — the calling SKILL.md owns that
+handoff, which happens only after explicit user confirmation of the final refined state.
+
+## The 4 Challenge Behaviors
+
+The 4 behaviors are injected into the 9-step process above, but each round MUST produce
+explicit, substantive output for each. Do not let them be implicit. The user should be able
+to see each behavior fired in the round's output.
+
+### Behavior 1 — challenge plan's assumptions
+
+- **Rationale**: plan was a first-iteration pass; assumptions were made under incomplete
+  information and some were glossed over. Refine's job is to challenge those assumptions
+  before they harden into implementation.
+- **AI self-prompt**: "What did the plan treat as given that actually deserves interrogation?
+  What 'of course'-flavored premises are hiding in `proposal.md` or `design.md`?"
+- **Sample user-facing question**: "The plan implies that [X]. Is that actually true for this
+  user/context, or is it a plan-time shortcut?"
+- **Expected output per round**: a bulleted list titled "Plan assumptions under scrutiny"
+  with at least 1 item (generally 2-5 early rounds, trailing toward 0 as convergence nears).
+
+### Behavior 2 — propose new options
+
+- **Rationale**: plan usually picked the first-plausible option per decision. For each
+  existing design decision you should propose alternatives — alternatives are where better-fit
+  designs emerge.
+- **AI self-prompt**: "For each design decision already in `design.md`, what are the
+  alternatives the plan did not consider? For each new decision surfaced by this round's
+  challenges, what are the 2-3 approaches?"
+- **Sample user-facing question**: "The plan chose [current approach] for decision D3. I
+  also see two alternatives worth considering: [alt A] and [alt B]. Shall I walk through
+  trade-offs?"
+- **Expected output per round**: for at least one existing decision, a block showing
+  `currently chosen` + `alternative A` + `alternative B` with pros/cons for each.
+
+### Behavior 3 — explore omitted boundaries
+
+- **Rationale**: plan specs are drafted under time pressure and tend to cover happy paths
+  first. You must explore omitted boundaries — edge cases, permissions, errors,
+  non-functional concerns — because those are the most common omissions.
+- **AI self-prompt**: "What scenarios belong in the specs but are missing? What permission,
+  auth, or concurrency case isn't covered? What error/failure mode has no `#### Scenario:`?"
+- **Sample user-facing question**: "I don't see a scenario for [failure mode / concurrent
+  user / permission-denied path]. Should it be added, explicitly excluded, or deferred?"
+- **Expected output per round**: a checklist of boundary scenarios examined, each marked
+  `covered` / `missing → propose adding` / `explicitly out of scope`.
+
+### Behavior 4 — question scope
+
+- **Rationale**: plan sets scope early with incomplete information. Refine is the right
+  place to question scope — whether the change is too broad (decompose), too narrow
+  (expand), or mis-cut (split capability A from B).
+- **AI self-prompt**: "Does the change try to do too much? Too little? Are any capabilities
+  being bundled that should live in separate changes?"
+- **Sample user-facing question**: "Capability [X] and capability [Y] are being changed
+  together in this proposal. They seem to have independent rollout schedules. Should they
+  split into two changes?"
+- **Expected output per round**: a short paragraph titled "Scope check this round" with a
+  stance (scope is fine / too broad / too narrow / should split) and supporting reasoning.
+
+## Format Compliance
+
+Format compliance is fully delegated to `.claude/specflow/prompts/refine/update-artifacts.md`.
+Do not duplicate the format rules here — read that prompt during Step 5. In summary, it
+owns: per-artifact format preservation, `specflow validate` gating, revert-on-failure, and
+diff summary format.
+
+## Convergence Criteria
+
+- **At least 2 rounds** is unconditional (minimum 2 rounds). Do not short-circuit.
+- After round 2, convergence is decided by AI **semantic judgment** using the questions in
+  Step 8.
+- Convergence is a product of: no remaining unaddressed challenges across the 4 behaviors,
+  no open clarifying questions, no stale artifacts.
+- The user can extend past AI-declared convergence at any time.
+- Each round's convergence decision and its reasoning MUST be visible to the user (part of
+  the round-end announcement in Step 8).
+
+## Next Step
+
+After Step 9 announces final convergence AND the user confirms the refined state:
+the calling SKILL.md will invoke `specflow change phase <name> --set refined`, then suggest
+`/specflow:build` as the next slash command to run.
+
+This prompt itself never writes the phase transition — that is the SKILL orchestrator's job,
+and it happens only after explicit user confirmation of the refined state.

package/prompts/refine/design-output.md

@@ -0,0 +1,126 @@
+# Design Output Generation
+
+Orchestration prompt for generating `design.md` from an approved proposal and delta specs.
+
+## Overview
+
+The design document captures architectural decisions, technical approach, and risk assessment for a change. It bridges the gap between "what" (specs) and "how" (implementation plan).
+
+## Prerequisites
+
+- Approved proposal at `specflow/changes/<change-name>/proposal.md`
+- Delta specs at `specflow/changes/<change-name>/specs/`
+
+## Process
+
+### Step 1: Conflict Check Against Main Specs
+
+If `specflow/specs/` exists:
+
+1. Read all spec files in `specflow/specs/`
+2. Read all delta specs in `specflow/changes/<change-name>/specs/`
+3. Check for conflicts:
+   - Do any delta spec scenarios contradict existing main spec scenarios?
+   - Do any REMOVED items break dependencies in other specs?
+   - Do any RENAMED items have references elsewhere that need updating?
+4. Report findings:
+   - **No conflicts:** Proceed to design
+   - **Conflicts found:** List each conflict with the affected spec files and ask the user how to resolve before proceeding
+
+### Step 2: Gather Design Context
+
+Review:
+- The codebase structure (files, architecture, patterns)
+- The proposal's affected areas
+- The delta spec scenarios that need to be supported
+- Existing technical constraints
+
+### Step 3: Generate Design Document
+
+**Design document sections:**
+
+```markdown
+# Design: [Change Name]
+
+**Date:** YYYY-MM-DD
+**Proposal:** specflow/changes/<change-name>/proposal.md
+**Delta Specs:** specflow/changes/<change-name>/specs/
+
+## Context
+
+[What exists today, why it needs to change, relevant technical background]
+
+## Goals
+
+- [Goal 1 -- tied to a success criterion from the proposal]
+- [Goal 2]
+
+## Non-Goals
+
+- [Explicitly out of scope item 1]
+- [Explicitly out of scope item 2]
+
+## Design Decisions
+
+### [Decision 1: e.g., "Data Storage Approach"]
+
+**Options considered:**
+1. [Option A] -- [trade-offs]
+2. [Option B] -- [trade-offs]
+3. [Option C] -- [trade-offs]
+
+**Chosen:** [Option X]
+**Rationale:** [Why this option best serves the goals]
+
+### [Decision 2]
+...
+
+## Architecture
+
+[High-level architecture description]
+
+### Component Overview
+- [Component 1]: [responsibility]
+- [Component 2]: [responsibility]
+
+### Data Flow
+[How data moves through the system for key scenarios]
+
+### Interfaces
+[Key interfaces between components]
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] |
+| [Risk 2] | ... | ... | ... |
+
+## Spec Conflict Resolution
+[If conflicts were found in Step 1, document how each was resolved]
+
+## Open Questions
+[Any remaining questions that need answers before implementation]
+```
+
+### Step 4: Save Design Document
+
+Save to: `specflow/changes/<change-name>/design.md`
+
+Commit the design document to git.
+
+### Step 5: Present for Review
+
+> "Design document saved to `specflow/changes/<change-name>/design.md`. Please review the decisions and architecture before we proceed to implementation planning."
+
+## Principles
+
+- **Decisions must have rationale** -- "we chose X" is not a decision; "we chose X because Y" is
+- **Non-goals are as important as goals** -- explicitly state what you are NOT building
+- **Risks are not optional** -- every design has risks; listing none means you haven't thought about it
+- **Conflict resolution is mandatory** -- don't skip spec conflicts hoping they'll resolve themselves
+- **Keep it proportional** -- a simple change gets a short design; a complex change gets a thorough one
+
+## Next Step
+
+Once the design is approved, invoke specflow:build Phase A to create the implementation plan.

package/prompts/refine/spec-document-reviewer.md

@@ -0,0 +1,51 @@
+<!-- SOURCE: skills/brainstorming/spec-document-reviewer-prompt.md -->
+
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer subagent.
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Dispatch after:** Spec document is written to `specflow/changes/<change-name>/`
+
+```
+Task tool (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    You are a spec document reviewer. Verify this spec is complete and ready for planning.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+    | Scope | Focused enough for a single plan -- not covering multiple independent subsystems |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation planning.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways -- those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed plan.
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters for planning]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

package/prompts/refine/update-artifacts.md

@@ -0,0 +1,185 @@
+# Refine-Phase Artifact Update Methodology
+
+> **HARD GATE**: Every update must preserve format compatibility with `specflow validate`
+> and `specflow change archive`. A round that cannot produce a validated file set must
+> revert rather than ship half-valid artifacts.
+
+This prompt is invoked by `.claude/specflow/prompts/refine/brainstorm.md` during Step 5
+(Write/update artifacts) of each refine round. It owns impact analysis, user scope choice,
+per-artifact routing, format preservation, and post-update validation.
+
+## When to use this prompt
+
+- A refine round has surfaced a concrete update needed in one or more artifacts
+  (proposal.md, delta specs, design.md, or tasks.md).
+- brainstorm.md has completed Steps 1-4 and has a discussion trail ready to be committed
+  to files.
+- You have NOT yet written any file content in this round — update-artifacts.md owns the
+  writing phase.
+
+Do not invoke this prompt for read-only discussion. If the round's conclusion is "keep
+talking, no writes yet," skip straight to brainstorm.md Step 7 (user approval).
+
+## Routing Rules
+
+Before writing, route each piece of discussion output to the correct artifact. Use the
+table below as the default; if a topic genuinely belongs in more than one file, list all
+of them in the impact analysis.
+
+| Discussion topic                                              | Update file                   |
+|---------------------------------------------------------------|-------------------------------|
+| Scope / motivation changed (why or what-changes shifted)      | `proposal.md`                 |
+| Capability added or removed                                   | `proposal.md` + spec files    |
+| New scenario / missed edge case / error mode                  | `specs/**/*.md`               |
+| Requirement phrasing or WHEN/THEN bullet refinement           | `specs/**/*.md`               |
+| Implementation constraint / design decision emerged           | `design.md`                   |
+| Alternative option chosen over the plan's original pick       | `design.md`                   |
+| Open question that cannot be resolved in this round           | `design.md` (`## Open Questions`) |
+| Task structure implications (add/remove/reorganize groups)    | `tasks.md`                    |
+| Task ordering / dependency change                             | `tasks.md`                    |
+| Change splits into multiple changes                           | Stop; raise with user before writing anything |
+
+If the discussion implies a cascade (e.g., new capability → new spec file → new task
+group), list every affected file in the impact analysis and let the user choose scope.
+
+## Impact Analysis Template
+
+Before touching any file, present this block to the user and wait for choice:
+
+```
+Proposed update affects:
+  - <file1>: <what changes>
+  - <file2>: <what changes>
+  - <file3>: <what changes> (if applicable)
+
+This round can:
+  A) Apply all updates together
+  B) Update only primary file (<file1>), defer others to next round
+  C) Defer entirely, continue discussing
+
+Choice? [A/B/C]
+```
+
+Interpretation:
+
+- **A**: apply every listed update in this round. The diff summary at round end will show
+  all files changed.
+- **B**: apply only the primary file; the deferred files are carried into the NEXT round's
+  discussion queue (brainstorm.md's multi-round loop is what picks them up — that is the
+  entire point of having a loop).
+- **C**: write nothing this round. The discussion continues; the round still counts toward
+  the minimum-2-rounds threshold and the round-end diff summary reports "no changes this
+  round" honestly.
+
+Never proceed to writing without an explicit A/B/C choice from the user.
+
+## Format Preservation Rules
+
+Each artifact type has format contracts that `specflow validate` and `specflow change
+archive` rely on. Violating them breaks downstream automation.
+
+### `proposal.md`
+
+Must retain these top-level section headers in this order:
+
+- `## Why` — motivation paragraph(s)
+- `## What Changes` — bulleted list of changes
+- `## Capabilities` — enumeration of capabilities added/modified/removed
+- `## Impact` — affected files, specs, risks
+
+If your update adds new content, put it under the correct section; do not introduce new
+top-level sections without first asking the user.
+
+### `specs/**/*.md`
+
+Must retain:
+
+- `### Requirement:` (three hashes + "Requirement:" + colon) for every requirement header
+- `#### Scenario:` (EXACTLY four hashes + "Scenario:" + colon) for every scenario header —
+  three hashes will make `specflow validate` fail
+- `- **WHEN**` and `- **THEN**` bullet format for every scenario body (one WHEN and one
+  THEN minimum; AND bullets are allowed between them)
+- Delta marker headers `## ADDED Requirements` / `## MODIFIED Requirements` /
+  `## REMOVED Requirements` / `## RENAMED Requirements` when editing delta specs
+
+Do not rename existing requirements unless putting them under `## RENAMED Requirements`
+with explicit `FROM:` / `TO:` marker per spec format.
+
+### `design.md`
+
+Follow the archived `create-specflow-plugin` design.md style:
+
+- `## Decisions` section with each decision as `### Decision N: <name>` (or `### DN: <name>`),
+  containing:
+  - `**Options considered:**` list — at least 2 options, each with pros/cons
+  - `**Chosen:**` line identifying the selection
+  - `**Rationale:**` paragraph explaining why
+- Inline-documented, not a separate change log. The file IS the decision log.
+- `## Open Questions` section for deferred decisions (new in refine).
+- Existing `## Context`, `## Goals / Non-Goals`, `## Risks / Trade-offs` sections remain
+  in their original spots.
+
+### `tasks.md`
+
+Must stay **coarse-grained**:
+
+- Group-level headings (`## Group N: <name>`) with a short description and 3-6 tasks per
+  group are the target granularity.
+- Do NOT write 2-5 minute atomic tasks here — that precision comes from build Phase A.
+- Preserve existing ordering cues (e.g., dependency chains between groups) unless the
+  discussion explicitly reordered them.
+- Checkbox bullets (`- [ ] ...`) are fine; do not replace them with numbered lists.
+
+Coarse granularity is deliberate: refine is about direction, build Phase A is about
+execution precision.
+
+## Post-update Validation
+
+After modifying any spec file, automatically run:
+
+```bash
+specflow validate <path-to-spec>
+```
+
+Failure behavior:
+
+1. If `specflow validate` returns non-zero, **revert** the affected file to its
+   pre-edit state. Do not attempt multiple repair passes silently.
+2. Report to the user: "Format issue in `<file>`: `<validator output>`. Reverted to
+   pre-edit state. Shall we diagnose together?"
+3. Do not proceed to the next artifact write until the user decides how to fix.
+
+For non-spec artifact writes (`proposal.md`, `design.md`, `tasks.md`), validation is
+structural — confirm the required sections from "Format Preservation Rules" above are
+still present. If they are not, apply the same revert-and-report pattern.
+
+## Diff Summary Format
+
+At round end (brainstorm.md Step 7), the AI MUST emit this block so the user sees
+concretely what moved:
+
+```
+Round <N> changes:
+  - proposal.md: <summary>
+  - specs/<cap>/spec.md: <summary>
+  - design.md: added Decision <N> (<name>)
+  - tasks.md: <summary>
+```
+
+Rules for the diff summary:
+
+- Omit lines for files that were NOT modified in this round (don't write
+  "proposal.md: no change"). If nothing was modified, the block reads
+  "Round N changes: (none this round — choice C was selected)".
+- For `design.md`, name the specific Decision or Open Question added/modified.
+- For `specs/`, name the capability and whether ADDED/MODIFIED/REMOVED delta was applied.
+- Keep each summary line under 100 characters; detailed prose lives in the files.
+
+## Handoff
+
+Return control to brainstorm.md Step 6 (self-review) only after:
+
+- The user chose A/B/C.
+- Chosen files were written.
+- `specflow validate` passed (or no spec files were touched).
+- Diff summary is prepared for Step 7.