docs(changes): plan interactive proposal qa flow

openspec/changes/add-interactive-proposal-qa/proposal.md

@@ -0,0 +1,13 @@
+## Why
+A recent feature request highlighted that users struggle to scope proposals when all clarifications have to be typed manually. They want a guided interview that surfaces missing assumptions, recommends best-practice defaults, and produces a sharper brief before handing off to `/openspec/proposal`. Delivering an interactive Q&A flow keeps OpenSpec competitive with other planning assistants and shortens the loop between idea and actionable change specification.
+
+## What Changes
+- Add a dedicated `/openspec/proposal-qa` slash command that runs a structured discovery interview before drafting a change proposal.
+- Teach the agent to analyse the initial request, label what is already explicit versus ambiguous, and derive a small set of high-impact clarifying questions.
+- Require every question to include rationale, 2–4 recommended options with a default, and clear guidance on when to pick each option.
+- Capture the conversation outcome in a structured summary (problem, clarified decisions, open risks) that the user can accept or tweak before invoking `/openspec/proposal`.
+- Update onboarding (`init`/`update`) and slash command templates so the new command ships everywhere OpenSpec currently provisions proposal/apply/archive helpers.
+
+## Impact
+- Affected specs: assistant-proposal-qa (new), cli-init, cli-update, slash-commands-template (if modelled separately)
+- Affected code: `src/core/templates/slash-command-templates.ts`, `src/core/configurators/slash/*`, command scaffolding that writes `.claude/.cursor/.opencode` files, and associated tests.

openspec/changes/add-interactive-proposal-qa/specs/assistant-proposal-qa/spec.md

@@ -0,0 +1,63 @@
+# assistant-proposal-qa Specification
+
+## ADDED Requirements
+### Requirement: Interactive Proposal Q&A Command
+
+The system SHALL provide a `/openspec/proposal-qa` slash command that prepares users for `/openspec/proposal` by running a structured discovery interview.
+
+#### Scenario: Launching the proposal interview
+- **WHEN** the user runs `/openspec/proposal-qa Build a notifications digest`
+- **THEN** acknowledge the request and restate the draft problem statement
+- **AND** highlight what parts of the request are already concrete versus ambiguous (e.g., "Strong signals" and "Needs clarity")
+- **AND** outline the upcoming steps: targeted questions followed by a summary hand-off.
+
+#### Scenario: Honour non-interactive environments
+- **GIVEN** slash commands are invoked in a non-interactive environment (e.g., automation requesting defaults)
+- **WHEN** `/openspec/proposal-qa` is triggered with `--no-interactive`
+- **THEN** skip the question loop
+- **AND** produce a summary that records the request, recommended defaults, and instructions for editing manually before running `/openspec/proposal`.
+
+### Requirement: Targeted Clarifying Questions
+
+The interview SHALL adaptively surface 3–6 high-leverage questions that eliminate ambiguity in the proposal brief.
+
+#### Scenario: Ask one question at a time with rationale
+- **WHEN** the interview begins gathering answers
+- **THEN** select the next most risky/vague aspect of the feature
+- **AND** present a single question that includes:
+  - A short rationale explaining why the question matters for the proposal
+  - 2–4 recommended options formatted as a bulleted list with `**Default**` clearly marked
+  - Guidance for when to choose each option (one sentence per option)
+- **AND** wait for the user response (or `default`/`skip`) before showing another question.
+
+#### Scenario: Provide fallbacks when users defer
+- **WHEN** the user replies with `idk`, `default`, or leaves the answer empty
+- **THEN** accept the default option for that question
+- **AND** note in the transcript that the default was applied.
+
+#### Scenario: Capture bespoke answers
+- **WHEN** the user supplies an answer that does not match any recommended option
+- **THEN** accept the custom answer
+- **AND** record a short interpretation describing how it will shape the proposal.
+
+### Requirement: Synthesis and Handoff
+
+The interview SHALL produce an actionable summary that readies the agent to draft the formal change proposal.
+
+#### Scenario: Summarise discoveries before exit
+- **WHEN** the question loop completes (or is skipped)
+- **THEN** output a structured summary containing:
+  - Problem statement and scope recap
+  - Table or bullet list of decisions (question → final answer → reasoning/default flag)
+  - Noted risks, open questions, and assumptions to confirm in the proposal
+- **AND** recommend next actions: either ask for revisions, run `/openspec/proposal` with this summary, or request further research.
+
+#### Scenario: Provide reusable prompt snippet
+- **WHEN** the summary is generated
+- **THEN** include a copyable prompt block that the user can paste into `/openspec/proposal`
+- **AND** ensure the prompt references the summary decisions and flags any open items for follow-up.
+
+#### Scenario: Allow re-entry for more questions
+- **WHEN** the user indicates they want to refine further (e.g., "ask more" or "another pass")
+- **THEN** identify remaining ambiguous areas not yet questioned
+- **AND** continue with additional questions (up to the 6-question cap) before regenerating the summary.

openspec/changes/add-interactive-proposal-qa/specs/cli-init/spec.md

@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates, including the interactive proposal interview instructions.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/proposal-qa.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include guidance that the `proposal-qa` command runs the interactive discovery interview before `/openspec/proposal`.
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-proposal-qa.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include guidance that the `proposal-qa` command runs the interactive discovery interview before `/openspec/proposal`.
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-proposal-qa.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include guidance that the `proposal-qa` command runs the interactive discovery interview before `/openspec/proposal`.

openspec/changes/add-interactive-proposal-qa/specs/cli-update/spec.md

@@ -0,0 +1,18 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools, including the interactive proposal interview template, without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `proposal-qa.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure the `proposal-qa` template contains the interactive discovery instructions aligned with the latest assistant guidance.
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-proposal-qa.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure the `proposal-qa` template contains the interactive discovery instructions aligned with the latest assistant guidance.
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/commands/` contains `openspec-proposal.md`, `openspec-proposal-qa.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure the `proposal-qa` template contains the interactive discovery instructions aligned with the latest assistant guidance.

openspec/changes/add-interactive-proposal-qa/tasks.md

@@ -0,0 +1,19 @@
+## 1. Discovery & Design
+- [ ] 1.1 Audit existing slash command files (`src/core/templates/slash-command-templates.ts`, configurators, tests) to mirror tone/format.
+- [ ] 1.2 Draft conversational flow map covering request analysis, question generation heuristics, question formatting, and post-qa summary/next-steps.
+- [ ] 1.3 Validate the flow against the example repo in issue #85 to ensure parity with proven UX patterns (e.g., defaults, recommended answers).
+
+## 2. Specification Updates
+- [ ] 2.1 Add `assistant-proposal-qa` capability spec capturing requirements for analysis, questioning, summary, and hand-off UX.
+- [ ] 2.2 Update `cli-init` and `cli-update` specs so generated slash command files include the new `proposal-qa` command for all supported assistants.
+
+## 3. Implementation
+- [ ] 3.1 Extend `SlashCommandId` union, templates, and file writers to emit `/openspec/proposal-qa` with the new instructions body.
+- [ ] 3.2 Implement helper(s) that build recommended answer options from agent analysis (list of option label, description, default marker).
+- [ ] 3.3 Ensure question loop enforces 3–6 prompts, each with rationale and recommended default, and gracefully handles user-supplied alternatives.
+- [ ] 3.4 Update onboarding/update flows to write `.claude/.cursor/.opencode` command markdown for `proposal-qa` alongside existing commands.
+
+## 4. Validation & QA
+- [ ] 4.1 Add unit tests covering slash template rendering for the new command and regression tests for init/update scaffolding.
+- [ ] 4.2 Update documentation and examples (README, CHANGELOG as needed) showcasing how to use `/openspec/proposal-qa` and the resulting summary output.
+- [ ] 4.3 Run `openspec validate add-interactive-proposal-qa --strict` and full test suite (`pnpm test`) to confirm specs and tooling stay green.