diff --git a/openspec/changes/add-interactive-proposal-qa/proposal.md b/openspec/changes/add-interactive-proposal-qa/proposal.md new file mode 100644 index 00000000..793a7c78 --- /dev/null +++ b/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. diff --git a/openspec/changes/add-interactive-proposal-qa/specs/assistant-proposal-qa/spec.md b/openspec/changes/add-interactive-proposal-qa/specs/assistant-proposal-qa/spec.md new file mode 100644 index 00000000..822f3e7d --- /dev/null +++ b/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. diff --git a/openspec/changes/add-interactive-proposal-qa/specs/cli-init/spec.md b/openspec/changes/add-interactive-proposal-qa/specs/cli-init/spec.md new file mode 100644 index 00000000..3152bf1f --- /dev/null +++ b/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`. diff --git a/openspec/changes/add-interactive-proposal-qa/specs/cli-update/spec.md b/openspec/changes/add-interactive-proposal-qa/specs/cli-update/spec.md new file mode 100644 index 00000000..ac4cbcb9 --- /dev/null +++ b/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. diff --git a/openspec/changes/add-interactive-proposal-qa/tasks.md b/openspec/changes/add-interactive-proposal-qa/tasks.md new file mode 100644 index 00000000..d98a6865 --- /dev/null +++ b/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.