diff --git a/docs/commands.md b/docs/commands.md index fd4bb7fe1..873a2e612 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -23,6 +23,7 @@ For workflow patterns and when to use each command, see [Workflows](workflows.md | `/opsx:continue` | Create the next artifact based on dependencies | | `/opsx:ff` | Fast-forward: create all planning artifacts at once | | `/opsx:verify` | Validate implementation matches artifacts | +| `/opsx:clarify` | Resolve ambiguities in specs through interactive Q&A | | `/opsx:sync` | Merge delta specs into main specs | | `/opsx:bulk-archive` | Archive multiple changes at once | | `/opsx:onboard` | Guided tutorial through the complete workflow | @@ -383,6 +384,123 @@ AI: Verifying add-dark-mode... --- +### `/opsx:clarify` + +Clarify underspecified areas in an OpenSpec change by identifying ambiguities and resolving them through interactive Q&A. Writes answers directly back into spec artifacts. + +**Syntax:** +```text +/opsx:clarify [change-name] +``` + +**Arguments:** + +| Argument | Required | Description | +|----------|----------|-------------| +| `change-name` | No | Which change to clarify (inferred from context if not provided) | + +**What it does:** +- Scans spec artifacts for ambiguities using a structured taxonomy +- Asks up to 5 prioritized questions with AI-generated recommendations +- Captures answers and writes them to spec artifacts incrementally +- Updates relevant spec sections to resolve ambiguities +- Provides coverage summary showing resolved/deferred/outstanding items + +**Ambiguity taxonomy (10 categories):** + +| Category | What it identifies | +|----------|-------------------| +| **Functional Scope** | Vague verbs, missing input/output details, incomplete flows | +| **Data Model** | Undefined types, unclear relationships, missing validation rules | +| **UX Flow** | Missing feedback states, navigation gaps, interaction ambiguity | +| **Non-Functional** | Missing performance, security, accessibility, or reliability requirements | +| **Integration** | Undefined external systems, missing protocols, boundary error handling | +| **Edge Cases** | Empty inputs, boundary conditions, concurrent operations, failure modes | +| **Constraints** | Missing limits, quotas, resource boundaries | +| **Terminology** | Overloaded terms, undefined abbreviations, context-dependent jargon | +| **Completion Signals** | Missing acceptance criteria, success metrics, done conditions | +| **Placeholders** | TODO markers, TBD language, "to be determined" content | + +**Example:** +```text +You: /opsx:clarify + +AI: Using change: add-user-auth + + Loading specs... Found 2 specs + Scanning for ambiguities... + + Found 7 ambiguities across 4 categories. Prioritizing top 5 questions. + + ───────────────────────────────────────── + + Question 1 of 5 - *Category: Data Model* + + **What fields should the User entity include?** + + Suggestions: "email, password_hash, created_at", + "email, username, password_hash, role, created_at" + + Please provide answer: + +You: email, username, password_hash, role, created_at, updated_at + +AI: ✓ Answer recorded. Updating spec... + + ───────────────────────────────────────── + + Question 2 of 5 - *Category: Non-Functional* + + **What authentication method should be used?** + + | Option | Description | Pros/Cons | + |--------|-------------|-----------| + | JWT | Token-based auth | Stateless, scalable, requires token management | + | Session cookies | Server-side sessions | Simple, secure, requires session storage | + | OAuth (Recommended) | Delegated auth | Industry standard, best UX, more complex setup | + + Please select an option or provide custom answer: + +You: OAuth + +AI: ✓ Answer recorded. Updating spec... + + [... continues through remaining questions ...] + + ## Clarification Summary + + **Change:** add-user-auth + **Resolved:** 5/5 questions answered + + ### By Category + - Data Model: 2 resolved + - Non-Functional: 2 resolved + - Edge Cases: 1 resolved + + All ambiguities resolved! Specs are now clearer. + + **Next Steps:** + - Review updated specs to confirm + - Continue creating artifacts: `/opsx:continue` +``` + +**Tips:** +- Use after creating specs but before implementation to catch ambiguities early +- Can run multiple times as new ambiguities are discovered +- Type "skip" or "defer" to skip questions and address them later +- Type "done" or "stop" to end early with partial completion +- Answers are written incrementally (work preserved if interrupted) +- Multiple-choice questions include AI recommendations with reasoning +- Short-answer questions should be concise (≤5 words when possible) + +**When to use:** +- After `/opsx:continue` creates specs but before creating tasks +- When specs have placeholders (TODO, TBD) that need resolution +- When implementation reveals unclear requirements (pause and clarify) +- Before handing off to another developer (ensure shared understanding) + +--- + ### `/opsx:sync` **Optional command.** Merge delta specs from a change into main specs. Archive will prompt to sync if needed, so you typically don't need to run this manually. diff --git a/docs/opsx.md b/docs/opsx.md index 9607b7d06..dbd404ed5 100644 --- a/docs/opsx.md +++ b/docs/opsx.md @@ -164,6 +164,7 @@ rules: | `/opsx:ff` | Fast-forward planning artifacts (expanded workflow) | | `/opsx:apply` | Implement tasks, updating artifacts as needed | | `/opsx:verify` | Validate implementation against artifacts (expanded workflow) | +| `/opsx:clarify` | Resolve ambiguities in specs through interactive Q&A | | `/opsx:sync` | Sync delta specs to main (expanded workflow, optional) | | `/opsx:archive` | Archive when done | | `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) | diff --git a/docs/workflows.md b/docs/workflows.md index 6cfd7e063..4d4dad7bb 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -397,6 +397,52 @@ AI: Let me investigate your current setup and options... Exploration clarifies thinking before you create artifacts. +### Use `/opsx:clarify` for Ambiguous Specs + +After creating specs but before implementation, use `/opsx:clarify` to identify and resolve ambiguities: + +```text +You: /opsx:continue + (specs are created) + +You: /opsx:clarify + +AI: Using change: add-user-auth + + Loading specs... Found 2 specs + Scanning for ambiguities... + + Found 5 ambiguities across 3 categories. + + ───────────────────────────────────────── + + Question 1 of 5 - *Category: Data Model* + + **What fields should the User entity include?** + + Suggestions: "email, password_hash, created_at" + +You: email, username, password_hash, role, created_at, updated_at + +AI: ✓ Answer recorded. Updating spec... + + [... continues through questions ...] + + All ambiguities resolved! Ready to continue. + +You: /opsx:continue + +AI: Creating tasks.md based on clarified specs... +``` + +**When to use `/opsx:clarify`:** +- After `/opsx:continue` creates specs (before creating tasks) +- When specs have placeholders (TODO, TBD) that need resolution +- When implementation reveals unclear requirements (pause and clarify) +- Before handing off to another developer (ensure shared understanding) + +Clarification makes specs concrete before implementation, reducing rework. + ### Verify Before Archiving Use `/opsx:verify` to check implementation matches artifacts: @@ -440,6 +486,7 @@ For full command details and options, see [Commands](commands.md). | `/opsx:ff` | Create all planning artifacts | Expanded mode, clear scope | | `/opsx:apply` | Implement tasks | Ready to write code | | `/opsx:verify` | Validate implementation | Expanded mode, before archiving | +| `/opsx:clarify` | Resolve spec ambiguities | After specs created, before implementation | | `/opsx:sync` | Merge delta specs | Expanded mode, optional | | `/opsx:archive` | Complete the change | All work finished | | `/opsx:bulk-archive` | Archive multiple changes | Expanded mode, parallel work | diff --git a/openspec/changes/add-clarify-command/.openspec.yaml b/openspec/changes/add-clarify-command/.openspec.yaml new file mode 100644 index 000000000..44652448b --- /dev/null +++ b/openspec/changes/add-clarify-command/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-11 diff --git a/openspec/changes/add-clarify-command/design.md b/openspec/changes/add-clarify-command/design.md new file mode 100644 index 000000000..10af8b3d9 --- /dev/null +++ b/openspec/changes/add-clarify-command/design.md @@ -0,0 +1,184 @@ +## Context + +Currently, OpenSpec has skill templates that guide AI agents through various workflow steps (explore, new-change, continue-change, apply-change, etc.). These skills are TypeScript functions in `src/core/templates/skill-templates.ts` that return structured template objects consumed by AI agents. + +The clarification workflow needs to be added as a new agent skill template following the existing pattern. This is NOT a CLI command—it's an agent skill that leverages AI capabilities to scan specs, identify ambiguities, ask intelligent questions, and integrate answers back into spec artifacts. + +The existing skill templates follow a consistent structure: +- Export a `get*SkillTemplate()` function that returns a `SkillTemplate` object +- Include metadata (name, description, license, compatibility, author, version) +- Provide detailed step-by-step instructions in markdown format +- Instructions reference OpenSpec CLI commands for status checks and file operations + +## Goals / Non-Goals + +**Goals:** +- Add `openspec-clarify` skill template following the existing pattern +- Enable AI agents to systematically identify ambiguities using a 10-category taxonomy +- Support interactive Q&A with AI-generated recommendations (multiple-choice and short-answer) +- Integrate clarification answers directly into spec artifacts with proper sectioning +- Provide coverage reporting to track resolved/deferred/outstanding ambiguities +- Make the skill accessible via standard exports in `index.ts` + +**Non-Goals:** +- Creating a CLI command (explicitly rejected—this is agent-only) +- Adding new CLI subcommands or flags +- Building ambiguity detection algorithms in TypeScript (AI does this) +- Creating test infrastructure for the clarification logic itself +- Implementing markdown parsing libraries (AI agents use their file editing tools) + +## Decisions + +### Decision 1: Agent Skill Template vs CLI Command + +**Choice:** Implement as agent skill template in `skill-templates.ts` + +**Rationale:** +- Clarification requires AI reasoning (ambiguity detection, question prioritization, contextual recommendations) +- CLI commands are for deterministic operations; agent skills are for intelligent workflows +- Avoids complexity of building ambiguity scanners, question generators, and NLP logic in TypeScript +- Leverages existing AI file editing, markdown formatting, and conversational capabilities +- Consistent with OpenSpec's agent-first architecture + +**Alternatives considered:** +- CLI command with scripted questions: Too rigid, can't adapt to spec context +- Hybrid (CLI + agent): Unnecessary complexity, agent can handle entire flow + +### Decision 2: Template Structure + +**Choice:** Single inline template string in `getClarifyChangeSkillTemplate()` function + +**Rationale:** +- Consistent with existing skill templates (see `getExploreSkillTemplate()`, `getContinueChangeSkillTemplate()`) +- All skill logic is self-contained in the returned instructions string +- No need for separate files—the full skill fits in one template string +- Easy to maintain and version alongside other skills + +**Alternatives considered:** +- Separate `.ts` file for the skill: Adds file management overhead without benefits +- External markdown file: Breaks the pattern of inline templates + +### Decision 3: Naming Convention + +**Choice:** Name the skill `openspec-clarify` and function `getClarifyChangeSkillTemplate()` + +**Rationale:** +- Follows naming pattern: `openspec--` +- Function name matches skill name: `getClarifyChangeSkillTemplate` + +**Alternatives considered:** +- `openspec-clarify-skill`: Redundant since all these are skills + +### Decision 4: Ambiguity Taxonomy Categories + +**Choice:** Use 10 structured categories for scanning: +1. Functional Scope and Behavior +2. Domain and Data Model +3. Interaction and UX Flow +4. Non-Functional Quality Attributes +5. Integration and External Dependencies +6. Edge Cases and Failure Handling +7. Constraints and Tradeoffs +8. Terminology and Consistency +9. Completion Signals +10. Misc and Placeholders + +**Rationale:** +- Comprehensive coverage of common spec ambiguities +- Structured enough for systematic scanning, flexible enough for AI judgment +- Based on industry best practices (IEEE 830, RFC requirements patterns) +- Each category maps to implementable questions + +**Alternatives considered:** +- Fewer categories (5-6): Too coarse, misses important dimensions +- More categories (15+): Overwhelming, diminishing returns +- Unstructured scanning: AI might miss systematic coverage areas + +### Decision 5: Question Format and Recommendations + +**Choice:** Two question types with AI-generated recommendations: +- **Multiple-choice:** 2-5 options in a markdown table, AI recommends one with reasoning +- **Short-answer:** ≤5 word answers, AI suggests default with reasoning + +**Rationale:** +- Multiple-choice forces explicit decision points (better than open-ended) +- Short-answer keeps responses actionable and concise +- AI recommendations reduce user cognitive load (accept, override, or customize) +- Table format is readable in agent chat interfaces + +**Alternatives considered:** +- Open-ended questions only: Too vague, hard to integrate into specs +- Yes/no questions only: Too limiting for complex clarifications +- Ranking/priority questions: Harder to integrate into prose specs + +### Decision 6: Incremental Spec Integration + +**Choice:** Update spec artifact immediately after each accepted answer + +**Rationale:** +- Progressive state saves work if session is interrupted +- User sees clarifications accumulating in real-time +- Each answer independently validates and writes (fail-fast) +- Easier to debug issues with individual clarifications + +**Alternatives considered:** +- Batch updates at end: Risk losing all work if session interrupted +- Separate clarifications file: Fragments context, harder to reference during implementation + +### Decision 7: Clarifications Section Format + +**Choice:** Add `## Clarifications` section with timestamped sessions: +```markdown +## Clarifications + +### Session 2026-02-12 +- Q: -> A: +- Q: -> A: +``` + +**Rationale:** +- Timestamped sessions preserve historical context across multiple clarification runs +- Bullet format is scannable and easy to reference +- Q/A pairs show original ambiguity and resolution +- Section can grow over time without restructuring + +**Alternatives considered:** +- Inline comments in each section: Clutters existing sections, hard to find +- Separate changelog: Fragments spec, harder to maintain coherence +- No historical tracking: Loses context on why decisions were made + +## Risks / Trade-offs + +**[Risk] AI may generate irrelevant or overly-speculative questions** +→ **Mitigation:** Instructions emphasize "materially impact implementation" prioritization; user can skip/terminate early; 5-question cap limits time waste + +**[Risk] Users may over-rely on AI recommendations without critical thinking** +→ **Mitigation:** Template requires AI to show reasoning; user must explicitly accept or override; encourages custom answers with "(Custom)" option + +**[Risk] Spec artifacts may become cluttered with too many clarifications over time** +→ **Mitigation:** Timestamped sessions keep history organized; template instructs to integrate answers into appropriate sections (not just append) + +**[Risk] Ambiguity taxonomy may not cover domain-specific concerns** +→ **Mitigation:** Category 10 (Misc/Placeholders) catches outliers; AI can adapt taxonomy interpretation to context; future versions can extend categories + +**[Risk] Incremental writes may leave specs in inconsistent state if AI errors mid-session** +→ **Mitigation:** Each write is atomic; validation step at end checks consistency; user can manually fix or re-run; Git versioning allows rollback + +**[Risk] Cross-platform path handling in template** +→ **Mitigation:** Template instructs agents to use file tools (which handle paths correctly); no hardcoded paths in template instructions + +## Migration Plan + +N/A - This is a new feature with no existing users or data to migrate. + +Deployment steps: +1. Add `getClarifyChangeSkillTemplate()` function to `skill-templates.ts` +2. Export function in `index.ts` +3. Test by having an agent invoke the skill on a test change +4. Document in README or skill catalog (if applicable) + +Rollback: Simply remove the function and export if issues arise. No persistent state changes. + +## Open Questions + +None at this time—proposal clarifies scope and approach sufficiently. diff --git a/openspec/changes/add-clarify-command/proposal.md b/openspec/changes/add-clarify-command/proposal.md new file mode 100644 index 000000000..cab059705 --- /dev/null +++ b/openspec/changes/add-clarify-command/proposal.md @@ -0,0 +1,75 @@ +## Why + +Users need an interactive way to identify and resolve ambiguities in spec artifacts during the change workflow. Currently, clarification is a manual process. An agent-based clarification skill template would make it faster to produce complete, unambiguous specs that lead to better implementation outcomes by leveraging AI capabilities without CLI complexity. + +## What Changes + +- Add new `openspec-clarify` skill template to `src/core/templates/skill-templates.ts` +- The skill template will be invoked by AI agents (not via CLI) to orchestrate an interactive clarification workflow that: + - Scans spec artifacts for ambiguities using a structured taxonomy + - Asks up to 5 prioritized questions with recommendations + - Writes answers directly back into spec artifacts under a `## Clarifications` section + - Updates relevant spec sections based on clarifications +- Supports both multiple-choice questions (with recommendations) and short-answer questions +- Auto-detects current change from context when name omitted +- Provides coverage summary showing resolved/deferred/outstanding ambiguities + +## Capabilities + +### New Capabilities + +- `openspec-clarify-skill-template`: Agent skill template that provides structured instructions for the clarification workflow - change selection, status checking, spec loading, ambiguity scanning (across 10+ taxonomy categories), interactive Q&A with recommendations, and spec integration +- `ambiguity-taxonomy`: Structured coverage framework spanning functional scope, data model, UX flow, non-functional requirements, integration points, edge cases, constraints, terminology, and completion signals +- `interactive-qa-protocol`: Guidelines for question generation, prioritization, recommendation formatting (multiple-choice tables with reasoning, short-answer suggestions), answer validation, and incremental spec updates +- `spec-integration-rules`: Instructions for adding `## Clarifications` section with timestamped sessions, applying answers to appropriate spec sections, and maintaining consistency + +### Modified Capabilities + +None - this is a new agent skill template that operates independently of existing CLI commands. + +## Impact + +**New files:** +- None - skill template is added inline to existing `skill-templates.ts` + +**Modified files:** +- `src/core/templates/skill-templates.ts` - Add `getClarifyChangeSkillTemplate()` function with the full skill template content +- `src/core/templates/index.ts` - Export `getClarifyChangeSkillTemplate` for agent access +- `docs/commands.md` - Add `/opsx:clarify` command reference with syntax, examples, and usage tips (insert after `/opsx:verify` section) +- `docs/opsx.md` - Add `/opsx:clarify` to the commands table +- `docs/workflows.md` - Document when to use clarify in workflow patterns (e.g., "When specs are ambiguous during planning or implementation") + +**Dependencies:** +- None - uses existing AI agent capabilities and file I/O tools + +**User workflow:** +- Invoked by AI agents during spec refinement via `/opsx:clarify` command +- Typical flow: `openspec new change` → `openspec continue` (creates spec) → **`/opsx:clarify`** → `openspec continue` (creates tasks) → implementation +- Can be used anytime during change lifecycle when ambiguity needs resolution + +**Documentation updates:** +- Command reference in `docs/commands.md` with full syntax, examples, and usage patterns +- Workflow integration guidance in `docs/workflows.md` showing when to invoke clarify +- Command table entry in `docs/opsx.md` alongside other OPSX commands + +**Template Structure:** +```markdown +--- +name: openspec-clarify +description: Clarify underspecified areas in an OpenSpec change by asking up to 5 targeted questions and writing answers back into spec artifacts. +license: MIT +compatibility: Requires openspec CLI. +metadata: + author: openspec + version: "2.0" +--- + +[Full skill template content with 8 steps: Select change, Check status, Load specs, Scan for ambiguity using taxonomy, Generate question queue, Interactive Q&A loop with recommendations, Integrate answers into specs, Validate and report] +``` + +The template includes: +- 10-category ambiguity taxonomy (functional scope, domain/data model, UX flow, non-functional attributes, integration, edge cases, constraints, terminology, completion signals, misc/placeholders) +- Interactive question formats with AI-generated recommendations +- Incremental spec update protocol (one answer at a time) +- Coverage reporting with resolved/deferred/outstanding categories +- Early termination and quota guardrails (max 5 questions) diff --git a/openspec/changes/add-clarify-command/specs/ambiguity-taxonomy/spec.md b/openspec/changes/add-clarify-command/specs/ambiguity-taxonomy/spec.md new file mode 100644 index 000000000..a6e90a4e1 --- /dev/null +++ b/openspec/changes/add-clarify-command/specs/ambiguity-taxonomy/spec.md @@ -0,0 +1,174 @@ +## ADDED Requirements + +### Requirement: Functional scope taxonomy category +The system SHALL define functional scope as a taxonomy category covering vague verbs, missing input/output details, and incomplete flows. + +#### Scenario: Vague verb detection +- **WHEN** spec uses terms like "handle", "process", "manage" without specifics +- **THEN** these are classified as functional scope ambiguities + +#### Scenario: Missing input/output details +- **WHEN** spec describes a function without defining inputs or outputs +- **THEN** this is classified as a functional scope ambiguity + +#### Scenario: Incomplete flow detection +- **WHEN** spec describes a workflow with missing steps or transitions +- **THEN** this is classified as a functional scope ambiguity + +### Requirement: Domain and data model taxonomy category +The system SHALL define domain/data model as a taxonomy category covering undefined types, unclear relationships, and missing validation rules. + +#### Scenario: Undefined type detection +- **WHEN** spec references a type or entity without defining its structure +- **THEN** this is classified as a data model ambiguity + +#### Scenario: Unclear relationship detection +- **WHEN** spec describes entity relationships without cardinality or ownership semantics +- **THEN** this is classified as a data model ambiguity + +#### Scenario: Missing validation rules +- **WHEN** spec defines fields without constraints, formats, or validation rules +- **THEN** this is classified as a data model ambiguity + +### Requirement: UX flow taxonomy category +The system SHALL define UX flow as a taxonomy category covering missing feedback states, navigation ambiguity, and interaction gaps. + +#### Scenario: Missing feedback state detection +- **WHEN** spec describes user action without defining loading, success, or error states +- **THEN** this is classified as a UX flow ambiguity + +#### Scenario: Navigation ambiguity detection +- **WHEN** spec describes screens without defining how users navigate between them +- **THEN** this is classified as a UX flow ambiguity + +#### Scenario: Interaction gap detection +- **WHEN** spec omits details about buttons, forms, or interactive elements +- **THEN** this is classified as a UX flow ambiguity + +### Requirement: Non-functional attributes taxonomy category +The system SHALL define non-functional attributes as a taxonomy category covering performance, security, accessibility, and reliability requirements. + +#### Scenario: Missing performance criteria +- **WHEN** spec lacks response time targets, throughput limits, or latency bounds +- **THEN** this is classified as a non-functional ambiguity + +#### Scenario: Missing security requirements +- **WHEN** spec doesn't define authentication, authorization, or data protection needs +- **THEN** this is classified as a non-functional ambiguity + +#### Scenario: Missing accessibility criteria +- **WHEN** spec doesn't specify keyboard navigation, screen reader support, or WCAG compliance +- **THEN** this is classified as a non-functional ambiguity + +#### Scenario: Missing reliability requirements +- **WHEN** spec lacks error recovery, retry logic, or fallback behavior +- **THEN** this is classified as a non-functional ambiguity + +### Requirement: Integration points taxonomy category +The system SHALL define integration points as a taxonomy category covering external systems, APIs, protocols, and error handling at boundaries. + +#### Scenario: Undefined external system detection +- **WHEN** spec references external service without defining interface or contract +- **THEN** this is classified as an integration ambiguity + +#### Scenario: Missing protocol details +- **WHEN** spec describes integration without specifying REST, GraphQL, WebSocket, etc. +- **THEN** this is classified as an integration ambiguity + +#### Scenario: Missing boundary error handling +- **WHEN** spec describes integration without timeout, retry, or fallback strategy +- **THEN** this is classified as an integration ambiguity + +### Requirement: Edge cases taxonomy category +The system SHALL define edge cases as a taxonomy category covering empty inputs, boundary conditions, concurrent operations, and failure modes. + +#### Scenario: Empty input handling +- **WHEN** spec doesn't specify behavior for null, empty, or missing inputs +- **THEN** this is classified as an edge case ambiguity + +#### Scenario: Boundary condition handling +- **WHEN** spec doesn't define behavior at limits (max size, zero values, overflow) +- **THEN** this is classified as an edge case ambiguity + +#### Scenario: Concurrent operation handling +- **WHEN** spec doesn't address race conditions, locks, or simultaneous access +- **THEN** this is classified as an edge case ambiguity + +#### Scenario: Failure mode handling +- **WHEN** spec doesn't specify behavior when operations fail or abort +- **THEN** this is classified as an edge case ambiguity + +### Requirement: Constraints taxonomy category +The system SHALL define constraints as a taxonomy category covering limits, quotas, resource boundaries, and capacity planning. + +#### Scenario: Missing limit definitions +- **WHEN** spec doesn't define maximum file sizes, string lengths, or collection sizes +- **THEN** this is classified as a constraint ambiguity + +#### Scenario: Missing quota definitions +- **WHEN** spec doesn't specify rate limits, usage caps, or throttling thresholds +- **THEN** this is classified as a constraint ambiguity + +#### Scenario: Missing resource boundaries +- **WHEN** spec doesn't define memory limits, CPU budgets, or storage constraints +- **THEN** this is classified as a constraint ambiguity + +### Requirement: Terminology taxonomy category +The system SHALL define terminology as a taxonomy category covering overloaded terms, undefined abbreviations, and context-dependent language. + +#### Scenario: Overloaded term detection +- **WHEN** spec uses same word with different meanings in different contexts +- **THEN** this is classified as a terminology ambiguity + +#### Scenario: Undefined abbreviation detection +- **WHEN** spec uses acronyms or abbreviations without defining them +- **THEN** this is classified as a terminology ambiguity + +#### Scenario: Context-dependent language detection +- **WHEN** spec uses domain jargon without explanation or glossary reference +- **THEN** this is classified as a terminology ambiguity + +### Requirement: Completion signals taxonomy category +The system SHALL define completion signals as a taxonomy category covering acceptance criteria, success metrics, and done conditions. + +#### Scenario: Missing acceptance criteria +- **WHEN** spec describes feature without defining what constitutes successful completion +- **THEN** this is classified as a completion signal ambiguity + +#### Scenario: Missing success metrics +- **WHEN** spec lacks measurable outcomes or KPIs +- **THEN** this is classified as a completion signal ambiguity + +#### Scenario: Missing done conditions +- **WHEN** spec doesn't specify when work is complete or ready for review +- **THEN** this is classified as a completion signal ambiguity + +### Requirement: Miscellaneous and placeholder taxonomy category +The system SHALL define misc/placeholders as a taxonomy category covering TODO markers, TBD placeholders, and "to be determined" language. + +#### Scenario: TODO marker detection +- **WHEN** spec contains TODO, FIXME, or similar task markers +- **THEN** this is classified as a placeholder ambiguity + +#### Scenario: TBD placeholder detection +- **WHEN** spec contains "TBD", "pending", or "to be determined" language +- **THEN** this is classified as a placeholder ambiguity + +#### Scenario: Deferral language detection +- **WHEN** spec contains "will be defined later" or similar deferral language +- **THEN** this is classified as a placeholder ambiguity + +### Requirement: Taxonomy coverage reporting +The system SHALL report which taxonomy categories contain ambiguities for each spec. + +#### Scenario: Multiple categories with ambiguities +- **WHEN** a spec has issues across functional scope, data model, and edge cases +- **THEN** the report lists all three categories with counts + +#### Scenario: Single category with ambiguities +- **WHEN** a spec has issues only in the constraints category +- **THEN** the report shows that category with count and all others as clean + +#### Scenario: No ambiguities in any category +- **WHEN** a spec passes all taxonomy checks +- **THEN** the report confirms zero ambiguities across all 10 categories diff --git a/openspec/changes/add-clarify-command/specs/interactive-qa-protocol/spec.md b/openspec/changes/add-clarify-command/specs/interactive-qa-protocol/spec.md new file mode 100644 index 000000000..cf7b92496 --- /dev/null +++ b/openspec/changes/add-clarify-command/specs/interactive-qa-protocol/spec.md @@ -0,0 +1,142 @@ +## ADDED Requirements + +### Requirement: Question queue generation +The system SHALL generate a prioritized queue of up to 5 questions based on detected ambiguities. + +#### Scenario: Questions prioritized by blocking potential +- **WHEN** ambiguity scan identifies issues with varying implementation impact +- **THEN** questions are ordered with blocking issues first + +#### Scenario: Question quota enforced +- **WHEN** more than 5 ambiguities are detected +- **THEN** only the top 5 highest-priority questions are included in the queue + +#### Scenario: Fewer than quota ambiguities +- **WHEN** 3 ambiguities are detected +- **THEN** all 3 are included in the question queue + +### Requirement: Multiple-choice question formatting +The system SHALL format enumerable questions as multiple-choice with a table structure. + +#### Scenario: Table includes option descriptions +- **WHEN** a multiple-choice question is generated +- **THEN** each option includes an Option name, Description, and Pros/Cons columns + +#### Scenario: One option marked recommended +- **WHEN** a multiple-choice question is generated +- **THEN** exactly one option is marked "(Recommended)" with reasoning + +#### Scenario: Recommendation includes justification +- **WHEN** an option is marked recommended +- **THEN** the Pros/Cons column explains why it's the best choice + +### Requirement: Short-answer question formatting +The system SHALL format open-ended questions with example suggestions and guidance. + +#### Scenario: Suggestions provided for context +- **WHEN** a short-answer question is generated +- **THEN** 2-3 example answers are shown to guide user response + +#### Scenario: Guidance explains expected format +- **WHEN** a short-answer question is generated +- **THEN** instructions specify the format, length, or structure of expected answers + +### Requirement: Sequential question presentation +The system SHALL present questions one at a time and wait for user response before showing the next question. + +#### Scenario: First question presented +- **WHEN** Q&A loop begins +- **THEN** only the first question is shown with progress indicator (e.g., "Question 1 of 5") + +#### Scenario: Next question shown after answer +- **WHEN** user answers the current question +- **THEN** the next question is displayed immediately + +#### Scenario: Final question completion +- **WHEN** user answers the last question in the queue +- **THEN** the Q&A loop terminates and proceeds to integration + +### Requirement: Answer validation +The system SHALL validate user responses before accepting them. + +#### Scenario: Multiple-choice answer validation +- **WHEN** user provides an answer to a multiple-choice question +- **THEN** the system verifies it matches one of the presented options + +#### Scenario: Invalid multiple-choice answer +- **WHEN** user provides an answer that doesn't match any option +- **THEN** the system re-prompts with valid options + +#### Scenario: Short-answer format validation +- **WHEN** user provides a short-answer response +- **THEN** the system checks it meets minimum length or format requirements + +#### Scenario: Empty answer rejection +- **WHEN** user provides an empty or whitespace-only answer +- **THEN** the system re-prompts for a valid response + +### Requirement: Answer deferral support +The system SHALL allow users to skip questions for later resolution. + +#### Scenario: User defers question +- **WHEN** user responds with "skip", "defer", or "later" +- **THEN** the question is marked deferred and the next question is shown + +#### Scenario: Deferred questions tracked +- **WHEN** user defers one or more questions +- **THEN** the final report lists deferred items by category + +### Requirement: Early termination support +The system SHALL allow users to stop the Q&A loop before all questions are answered. + +#### Scenario: User requests early stop +- **WHEN** user responds with "done", "stop", or "finish" +- **THEN** the workflow proceeds to integration with answers collected so far + +#### Scenario: Partial completion reported +- **WHEN** user terminates early +- **THEN** the final report shows which questions were answered and which remain + +### Requirement: Progress indicators +The system SHALL display progress throughout the Q&A loop. + +#### Scenario: Question counter shown +- **WHEN** each question is presented +- **THEN** the header shows "Question N of M" with current and total counts + +#### Scenario: Category context provided +- **WHEN** each question is presented +- **THEN** the taxonomy category (e.g., "Functional Scope") is labeled + +### Requirement: Recommendation reasoning +The system SHALL provide clear rationale for all recommendations. + +#### Scenario: Pros and cons listed +- **WHEN** a recommended option is presented +- **THEN** the table includes specific advantages and trade-offs + +#### Scenario: Alternative options acknowledged +- **WHEN** a recommendation is made +- **THEN** the table shows why other options were not recommended + +### Requirement: Incremental answer capture +The system SHALL capture and persist each answer immediately after validation. + +#### Scenario: Answer written before next question +- **WHEN** user provides a valid answer +- **THEN** it is written to the spec before showing the next question + +#### Scenario: Answer persistence confirmed +- **WHEN** an answer is written to a spec +- **THEN** the system confirms the write succeeded before proceeding + +### Requirement: Cross-platform path handling in questions +The system SHALL use platform-independent path representations in questions and answers involving file paths. + +#### Scenario: Paths displayed with correct separators +- **WHEN** a question references a file path on Windows +- **THEN** backslashes are used in the question text + +#### Scenario: Path answers normalized +- **WHEN** user provides a path answer with mixed separators +- **THEN** it is normalized to the platform-appropriate format before persisting diff --git a/openspec/changes/add-clarify-command/specs/openspec-clarify-skill-template/spec.md b/openspec/changes/add-clarify-command/specs/openspec-clarify-skill-template/spec.md new file mode 100644 index 000000000..760cbe54b --- /dev/null +++ b/openspec/changes/add-clarify-command/specs/openspec-clarify-skill-template/spec.md @@ -0,0 +1,205 @@ +## ADDED Requirements + +### Requirement: Skill template generation +The system SHALL provide a `getClarifyChangeSkillTemplate()` function that returns a complete agent skill template for the clarification workflow. + +#### Scenario: Template accessed by agent +- **WHEN** an AI agent needs clarification instructions +- **THEN** the function returns the full skill template with metadata and step-by-step instructions + +#### Scenario: Template includes required metadata +- **WHEN** the template is generated +- **THEN** it includes name, description, license, compatibility, author, and version fields + +### Requirement: Change selection workflow +The system SHALL support auto-detection of the current change from conversation context when no change name is provided. + +#### Scenario: Change name provided explicitly +- **WHEN** agent invokes skill with a specific change name +- **THEN** the workflow uses the specified change without prompting + +#### Scenario: Change name omitted with clear context +- **WHEN** agent invokes skill without a change name and context suggests a specific change +- **THEN** the workflow infers the change from context + +#### Scenario: Change name omitted without context +- **WHEN** agent invokes skill without a change name and context is ambiguous +- **THEN** the workflow lists available changes and prompts for selection + +### Requirement: Status validation +The system SHALL verify that the change has spec artifacts before proceeding with clarification. + +#### Scenario: Change has spec artifacts +- **WHEN** status check runs on a change with completed specs +- **THEN** the workflow proceeds to ambiguity scanning + +#### Scenario: Change lacks spec artifacts +- **WHEN** status check runs on a change without specs +- **THEN** the workflow reports that specs must be created first and terminates + +### Requirement: Spec artifact loading +The system SHALL load all spec artifacts from the change directory for analysis. + +#### Scenario: Multiple spec files present +- **WHEN** specs directory contains multiple capability specs +- **THEN** all spec files are loaded and combined for ambiguity scanning + +#### Scenario: Single spec file present +- **WHEN** specs directory contains one capability spec +- **THEN** that spec is loaded for ambiguity scanning + +### Requirement: Ambiguity scanning with taxonomy +The system SHALL scan spec artifacts for ambiguities using a structured 10-category taxonomy. + +#### Scenario: Functional scope ambiguities detected +- **WHEN** specs contain vague verbs, missing input/output details, or incomplete flows +- **THEN** these are flagged under the functional scope category + +#### Scenario: Data model ambiguities detected +- **WHEN** specs reference undefined types, unclear relationships, or missing validation rules +- **THEN** these are flagged under the domain/data model category + +#### Scenario: UX flow ambiguities detected +- **WHEN** specs describe user interactions with missing feedback states or navigation +- **THEN** these are flagged under the UX flow category + +#### Scenario: Non-functional ambiguities detected +- **WHEN** specs lack performance targets, security requirements, or accessibility criteria +- **THEN** these are flagged under the non-functional attributes category + +#### Scenario: Integration ambiguities detected +- **WHEN** specs reference external systems without defining protocols or error handling +- **THEN** these are flagged under the integration points category + +#### Scenario: Edge case ambiguities detected +- **WHEN** specs don't specify behavior for empty inputs, concurrent operations, or failure modes +- **THEN** these are flagged under the edge cases category + +#### Scenario: Constraint ambiguities detected +- **WHEN** specs lack limits, quotas, or resource boundaries +- **THEN** these are flagged under the constraints category + +#### Scenario: Terminology ambiguities detected +- **WHEN** specs use overloaded terms, abbreviations without definitions, or context-dependent language +- **THEN** these are flagged under the terminology category + +#### Scenario: Completion ambiguities detected +- **WHEN** specs don't define acceptance criteria or success metrics +- **THEN** these are flagged under the completion signals category + +#### Scenario: Placeholder ambiguities detected +- **WHEN** specs contain TODO, TBD, or "to be determined" markers +- **THEN** these are flagged under the misc/placeholders category + +### Requirement: Question prioritization +The system SHALL generate up to 5 prioritized questions based on ambiguity severity and implementation impact. + +#### Scenario: More than 5 ambiguities found +- **WHEN** ambiguity scanning identifies more than 5 issues +- **THEN** the top 5 are prioritized by blocking potential and selected for Q&A + +#### Scenario: Fewer than 5 ambiguities found +- **WHEN** ambiguity scanning identifies 3 ambiguities +- **THEN** all 3 are included in the question queue + +#### Scenario: No ambiguities found +- **WHEN** ambiguity scanning finds no issues +- **THEN** the workflow reports that specs are clear and terminates successfully + +### Requirement: Question format with recommendations +The system SHALL support two question formats: multiple-choice with recommendations and short-answer with suggestions. + +#### Scenario: Multiple-choice question generation +- **WHEN** a question has enumerable options +- **THEN** it is formatted as a multiple-choice table with option, description, and pros/cons columns + +#### Scenario: Multiple-choice includes recommendation +- **WHEN** a multiple-choice question is generated +- **THEN** one option is marked as "(Recommended)" with reasoning + +#### Scenario: Short-answer question generation +- **WHEN** a question requires free-form input +- **THEN** it is formatted with example suggestions and guidance + +#### Scenario: Short-answer includes suggestions +- **WHEN** a short-answer question is generated +- **THEN** it includes 2-3 example answers for context + +### Requirement: Interactive Q&A loop +The system SHALL present questions one at a time and capture user answers incrementally. + +#### Scenario: User answers question +- **WHEN** a question is presented and user provides an answer +- **THEN** the answer is validated and the next question is shown + +#### Scenario: User defers question +- **WHEN** user responds with "skip" or "defer" +- **THEN** that question is marked deferred and the next question is shown + +#### Scenario: User requests early termination +- **WHEN** user responds with "done" or "stop" before all questions answered +- **THEN** the workflow integrates answers collected so far and terminates + +#### Scenario: All questions answered +- **WHEN** user answers all questions in the queue +- **THEN** the workflow proceeds to spec integration + +### Requirement: Incremental spec updates +The system SHALL write each answer back into the appropriate spec artifact immediately after capture. + +#### Scenario: Answer written to single spec +- **WHEN** an answer relates to one capability spec +- **THEN** it is written to that spec's Clarifications section with timestamp and category + +#### Scenario: Answer applies to multiple specs +- **WHEN** an answer relates to multiple capabilities +- **THEN** it is written to all relevant spec Clarifications sections + +#### Scenario: Clarifications section creation +- **WHEN** a spec artifact lacks a Clarifications section +- **THEN** the section is added with `## Clarifications` header before writing the answer + +#### Scenario: Clarifications section exists +- **WHEN** a spec artifact already has a Clarifications section and the current session header exists +- **THEN** the new answer is appended under that session header + +### Requirement: Spec section updates based on clarifications +The system SHALL update relevant spec sections to reflect clarified requirements. + +#### Scenario: Clarification resolves ambiguous requirement +- **WHEN** an answer clarifies a vague requirement +- **THEN** the requirement text is updated to incorporate the answer + +#### Scenario: Clarification adds missing scenario +- **WHEN** an answer defines a new edge case +- **THEN** a new scenario is added to the relevant requirement + +#### Scenario: Clarification defines terminology +- **WHEN** an answer clarifies a term +- **THEN** a glossary entry or definition is added to the spec + +### Requirement: Coverage summary reporting +The system SHALL generate a final report showing resolved, deferred, and outstanding ambiguities by category. + +#### Scenario: All ambiguities resolved +- **WHEN** all questions have been answered +- **THEN** the report shows 100% resolution rate with breakdown by category + +#### Scenario: Some ambiguities deferred +- **WHEN** user skips some questions +- **THEN** the report lists deferred items by category and suggests re-running clarify + +#### Scenario: Additional ambiguities discovered +- **WHEN** spec updates reveal new ambiguities +- **THEN** the report notes outstanding items and recommends another clarification pass + +### Requirement: Template export and access +The system SHALL export the skill template function from the templates module for agent access. + +#### Scenario: Function exported from index +- **WHEN** templates module is imported +- **THEN** `getClarifyChangeSkillTemplate` is available as a named export + +#### Scenario: Template compatible with agent systems +- **WHEN** an AI agent requests the template +- **THEN** it receives valid Markdown with frontmatter and structured instructions diff --git a/openspec/changes/add-clarify-command/specs/spec-integration-rules/spec.md b/openspec/changes/add-clarify-command/specs/spec-integration-rules/spec.md new file mode 100644 index 000000000..3a6a433fd --- /dev/null +++ b/openspec/changes/add-clarify-command/specs/spec-integration-rules/spec.md @@ -0,0 +1,142 @@ +## ADDED Requirements + +### Requirement: Clarifications section creation +The system SHALL add a `## Clarifications` section to spec artifacts that don't already have one. + +#### Scenario: New clarifications section created +- **WHEN** a spec artifact receives its first clarification answer +- **THEN** a `## Clarifications` section is added at the end of the file + +#### Scenario: Existing clarifications section preserved +- **WHEN** a spec artifact already has a `## Clarifications` section +- **THEN** new answers are appended without duplicating the section header + +### Requirement: Timestamped session tracking +The system SHALL timestamp each clarification session for audit and history tracking. + +#### Scenario: Session timestamp added +- **WHEN** the first answer of a Q&A session is written +- **THEN** a session header with ISO 8601 timestamp is added (e.g., `### Session 2026-02-12T10:30:00Z`) + +#### Scenario: Multiple sessions tracked +- **WHEN** clarify is run multiple times on the same spec +- **THEN** each session appears under a separate timestamp header + +### Requirement: Answer format in clarifications section +The system SHALL format each clarification answer with question, category, and response. + +#### Scenario: Answer includes question text +- **WHEN** an answer is written to clarifications +- **THEN** it includes the original question in bold (e.g., `**Q: What is the maximum file size?**`) + +#### Scenario: Answer includes taxonomy category +- **WHEN** an answer is written to clarifications +- **THEN** it includes the category label (e.g., `*Category: Constraints*`) + +#### Scenario: Answer includes user response +- **WHEN** an answer is written to clarifications +- **THEN** it includes the full user response in a quoted block or formatted text + +### Requirement: Spec section updates from clarifications +The system SHALL apply clarification answers to relevant spec sections and record them in the `Clarifications` section to resolve ambiguities. + +#### Scenario: Clarification updates requirement +- **WHEN** an answer clarifies a vague requirement +- **THEN** the requirement text is updated to incorporate the answer + +#### Scenario: Clarification adds new scenario +- **WHEN** an answer defines a new edge case or flow +- **THEN** a new `#### Scenario:` block is added to the appropriate requirement + +#### Scenario: Clarification adds glossary entry +- **WHEN** an answer defines terminology +- **THEN** a glossary section (or entry in existing glossary) is added with the definition + +#### Scenario: Clarification adds constraint +- **WHEN** an answer specifies a limit or quota +- **THEN** the constraint is documented in the relevant requirement or a new constraint requirement + +### Requirement: Consistency validation +The system SHALL validate that clarification answers are consistent with existing spec content. + +#### Scenario: Conflicting answer detected +- **WHEN** a clarification answer contradicts an existing requirement +- **THEN** the system warns the user and asks which to keep + +#### Scenario: Redundant answer detected +- **WHEN** a clarification answer duplicates existing spec content +- **THEN** the system notifies the user and skips the redundant addition + +### Requirement: Multi-spec answer propagation +The system SHALL write answers that apply to multiple capabilities to all relevant spec files. + +#### Scenario: Answer applies to multiple specs +- **WHEN** a clarification answer resolves ambiguity shared across capabilities +- **THEN** the answer is written to the clarifications section of all affected specs + +#### Scenario: Cross-spec consistency maintained +- **WHEN** an answer is written to multiple specs +- **THEN** the wording is identical across all files for consistency + +### Requirement: File write safety +The system SHALL preserve existing spec content when adding clarifications. + +#### Scenario: Existing content unchanged +- **WHEN** clarifications are added to a spec +- **THEN** all unrelated requirements, scenarios, and sections remain intact (only targeted clarifications may update relevant text) + +#### Scenario: File validation before write +- **WHEN** a spec is about to be modified +- **THEN** the system confirms the file path exists and is writable before proceeding + +### Requirement: Markdown formatting preservation +The system SHALL maintain proper Markdown formatting when integrating clarifications. + +#### Scenario: Header hierarchy preserved +- **WHEN** clarifications section is added +- **THEN** it uses `##` header level consistent with other top-level sections + +#### Scenario: Session headers use correct level +- **WHEN** session timestamps are added +- **THEN** they use `###` header level under the `## Clarifications` section + +#### Scenario: Question formatting uses bold +- **WHEN** questions are written in clarifications +- **THEN** they use bold Markdown (`**Q: ...**`) for visibility + +#### Scenario: Category labels use italics +- **WHEN** taxonomy categories are written +- **THEN** they use italic Markdown (`*Category: ...*`) for distinction + +### Requirement: Incremental write protocol +The system SHALL write each answer immediately after capture rather than batching writes. + +#### Scenario: Answer written before next question +- **WHEN** user provides an answer +- **THEN** it is written to the spec file(s) before the next question is shown + +### Requirement: Path handling in spec updates +The system SHALL use platform-independent path operations when reading and writing spec files. + +#### Scenario: Spec file paths resolved correctly on Windows +- **WHEN** clarifications are written to specs on Windows +- **THEN** file paths use backslashes and path.join() for correctness + +#### Scenario: Spec file paths resolved correctly on Unix +- **WHEN** clarifications are written to specs on macOS or Linux +- **THEN** file paths use forward slashes and path.join() for correctness + +### Requirement: Coverage summary generation +The system SHALL generate a final summary showing which ambiguities were resolved, deferred, or remain outstanding. + +#### Scenario: All resolved summary +- **WHEN** all questions in the queue are answered +- **THEN** the summary shows 100% resolution with breakdown by category + +#### Scenario: Partial resolution summary +- **WHEN** some questions are deferred or skipped +- **THEN** the summary lists resolved, deferred, and outstanding items by category + +#### Scenario: Recommendation for next steps +- **WHEN** deferred or outstanding ambiguities remain +- **THEN** the summary suggests running clarify again or manually updating specs diff --git a/openspec/changes/add-clarify-command/tasks.md b/openspec/changes/add-clarify-command/tasks.md new file mode 100644 index 000000000..10bdd0847 --- /dev/null +++ b/openspec/changes/add-clarify-command/tasks.md @@ -0,0 +1,45 @@ +## 1. Core Skill Template Implementation + +- [x] 1.1 Create `getClarifyChangeSkillTemplate()` function in `src/core/templates/skill-templates.ts` with complete skill template structure +- [x] 1.2 Add skill metadata (name: "openspec-clarify", description, license: MIT, compatibility, author: "openspec", version: "2.0") +- [x] 1.3 Implement Step 1 instructions: Change selection workflow with auto-detection and prompt fallback +- [x] 1.4 Implement Step 2 instructions: Status validation using `openspec status --change --json` to verify specs exist +- [x] 1.5 Implement Step 3 instructions: Spec artifact loading from `specs/**/*.md` pattern +- [x] 1.6 Implement Step 4 instructions: Ambiguity scanning with 10-category taxonomy (functional scope, data model, UX flow, non-functional, integration, edge cases, constraints, terminology, completion signals, placeholders) +- [x] 1.7 Implement Step 5 instructions: Question queue generation with prioritization (max 5 questions, prioritize by blocking potential) +- [x] 1.8 Implement Step 6 instructions: Interactive Q&A loop with multiple-choice (recommendation tables) and short-answer formats +- [x] 1.9 Implement Step 7 instructions: Incremental spec integration with `## Clarifications` section and timestamped sessions +- [x] 1.10 Implement Step 8 instructions: Coverage summary reporting with resolved/deferred/outstanding breakdown by category + +## 2. Template Export and Access + +- [x] 2.1 Export `getClarifyChangeSkillTemplate` from `src/core/templates/index.ts` +- [x] 2.2 Verify function returns valid `SkillTemplate` object with correct TypeScript types + +## 3. Documentation Updates + +- [x] 3.1 Add `/opsx:clarify` command reference to `docs/commands.md` after `/opsx:verify` section with syntax, examples, and usage tips +- [x] 3.2 Add `/opsx:clarify` entry to commands table in `docs/opsx.md` +- [x] 3.3 Document clarify usage in workflow patterns in `docs/workflows.md` (e.g., "When specs are ambiguous during planning or implementation") + +## 4. Testing and Validation + +- [x] 4.1 Test skill template generation by invoking `getClarifyChangeSkillTemplate()` and validating returned structure +- [x] 4.2 Test with real change containing ambiguous specs to verify end-to-end workflow +- [x] 4.3 Verify cross-platform path handling in template instructions (use path.join() references) +- [x] 4.4 Test multiple-choice question format generates valid markdown tables +- [x] 4.5 Test short-answer question format with suggestions +- [x] 4.6 Test incremental spec updates add `## Clarifications` section correctly +- [x] 4.7 Test timestamped session tracking across multiple clarification runs +- [x] 4.8 Test coverage summary reports correctly show resolved/deferred/outstanding by category + +## 5. Edge Cases and Error Handling + +- [x] 5.1 Test behavior when change has no spec artifacts (should report and terminate) +- [x] 5.2 Test behavior when no ambiguities are found (should report specs are clear and terminate) +- [x] 5.3 Test user deferral of questions (skip/defer commands) +- [x] 5.4 Test early termination before all questions answered (done/stop commands) +- [x] 5.5 Test answer validation for multiple-choice (reject invalid options) +- [x] 5.6 Test answer validation for short-answer (reject empty responses) +- [x] 5.7 Test spec file write failures (error handling and user notification) +- [x] 5.8 Test cross-spec answer propagation when clarification applies to multiple capabilities diff --git a/src/core/shared/skill-generation.ts b/src/core/shared/skill-generation.ts index 898e7a25e..975db5894 100644 --- a/src/core/shared/skill-generation.ts +++ b/src/core/shared/skill-generation.ts @@ -9,6 +9,7 @@ import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, + getClarifyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, @@ -25,6 +26,7 @@ import { getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, + getOpsxClarifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, type SkillTemplate, @@ -64,6 +66,7 @@ export function getSkillTemplates(workflowFilter?: readonly string[]): SkillTemp { template: getArchiveChangeSkillTemplate(), dirName: 'openspec-archive-change', workflowId: 'archive' }, { template: getBulkArchiveChangeSkillTemplate(), dirName: 'openspec-bulk-archive-change', workflowId: 'bulk-archive' }, { template: getVerifyChangeSkillTemplate(), dirName: 'openspec-verify-change', workflowId: 'verify' }, + { template: getClarifyChangeSkillTemplate(), dirName: 'openspec-clarify-change' }, { template: getOnboardSkillTemplate(), dirName: 'openspec-onboard', workflowId: 'onboard' }, { template: getOpsxProposeSkillTemplate(), dirName: 'openspec-propose', workflowId: 'propose' }, ]; @@ -90,6 +93,7 @@ export function getCommandTemplates(workflowFilter?: readonly string[]): Command { template: getOpsxArchiveCommandTemplate(), id: 'archive' }, { template: getOpsxBulkArchiveCommandTemplate(), id: 'bulk-archive' }, { template: getOpsxVerifyCommandTemplate(), id: 'verify' }, + { template: getOpsxClarifyCommandTemplate(), id: 'clarify' }, { template: getOpsxOnboardCommandTemplate(), id: 'onboard' }, { template: getOpsxProposeCommandTemplate(), id: 'propose' }, ]; diff --git a/src/core/templates/skill-templates.ts b/src/core/templates/skill-templates.ts index ff687d900..1859d7e70 100644 --- a/src/core/templates/skill-templates.ts +++ b/src/core/templates/skill-templates.ts @@ -15,6 +15,7 @@ export { getSyncSpecsSkillTemplate, getOpsxSyncCommandTemplate } from './workflo export { getArchiveChangeSkillTemplate, getOpsxArchiveCommandTemplate } from './workflows/archive-change.js'; export { getBulkArchiveChangeSkillTemplate, getOpsxBulkArchiveCommandTemplate } from './workflows/bulk-archive-change.js'; export { getVerifyChangeSkillTemplate, getOpsxVerifyCommandTemplate } from './workflows/verify-change.js'; +export { getClarifyChangeSkillTemplate, getOpsxClarifyCommandTemplate } from './workflows/clarify-change.js'; export { getOnboardSkillTemplate, getOpsxOnboardCommandTemplate } from './workflows/onboard.js'; export { getOpsxProposeSkillTemplate, getOpsxProposeCommandTemplate } from './workflows/propose.js'; export { getFeedbackSkillTemplate } from './workflows/feedback.js'; diff --git a/src/core/templates/workflows/clarify-change.ts b/src/core/templates/workflows/clarify-change.ts new file mode 100644 index 000000000..7ee410d22 --- /dev/null +++ b/src/core/templates/workflows/clarify-change.ts @@ -0,0 +1,518 @@ +/** + * Skill Template Workflow Modules + * + * This file is generated by splitting the legacy monolithic + * templates file into workflow-focused modules. + */ +import type { SkillTemplate, CommandTemplate } from '../types.js'; + +export function getClarifyChangeSkillTemplate(): SkillTemplate { + return { + name: 'openspec-clarify', + description: 'Clarify underspecified areas in an OpenSpec change by asking up to 5 targeted questions and writing answers back into spec artifacts.', + instructions: `Clarify underspecified areas in an OpenSpec change by systematically identifying ambiguities and resolving them through interactive Q&A. + +**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. + +**Steps** + +1. **Select the change** + + If a name is provided, use it. Otherwise: + - Infer from conversation context if the user mentioned a change + - Auto-select if only one active change exists + - If ambiguous, run \`openspec list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select + + Always announce: "Using change: " and how to override (e.g., \`/opsx:clarify \`). + +2. **Check status to verify specs exist** + \`\`\`bash + openspec status --change "" --json + \`\`\` + Parse the JSON to check: + - Does the change have spec artifacts completed? + - If no specs exist, report: "This change doesn't have spec artifacts yet. Create them with \`/opsx:continue\` first." and terminate. + +3. **Load spec artifacts** + + Read all spec files from the change's specs directory (pattern: \`specs/**/*.md\`). + + Use the file reading tools to load each spec file for analysis. + +4. **Scan for ambiguities using the taxonomy** + + Systematically scan the specs across **10 categories**: + + 1. **Functional Scope and Behavior** + - Vague verbs without concrete definitions ("handle", "process", "manage", "deal with") + - Missing input/output specifications or format details + - Incomplete user/system flows or interaction sequences + - Unspecified behavior for common operations + + 2. **Domain and Data Model** + - Undefined types, entities, or data structures + - Unclear relationships between entities (1:1, 1:N, M:N) + - Missing validation rules or constraints on data + - Unspecified data formats, schemas, or serialization + + 3. **Interaction and UX Flow** + - Missing feedback states (loading, success, error, empty) + - Unclear navigation paths or state transitions + - Interaction gaps (what happens between steps) + - Unspecified user input validation or feedback + + 4. **Non-Functional Quality Attributes** + - Missing performance targets (latency, throughput, response time) + - Unspecified security requirements (authentication, authorization, encryption) + - Missing accessibility criteria (WCAG levels, screen reader support) + - Unclear reliability/availability requirements (uptime, fault tolerance) + + 5. **Integration and External Dependencies** + - References to undefined external systems or services + - Missing API contracts, protocol details, or data formats + - Unspecified error handling for external failures + - Missing fallback or retry strategies + + 6. **Edge Cases and Failure Handling** + - Unspecified behavior for empty/null/zero inputs + - Missing boundary condition handling (min/max values) + - Unclear concurrent operation behavior (race conditions, conflicts) + - Unspecified failure modes and recovery strategies + + 7. **Constraints and Tradeoffs** + - Missing limits or quotas (rate limits, size limits, count limits) + - Unspecified resource boundaries (memory, disk, bandwidth) + - Missing capacity planning considerations + - Unclear cost/performance tradeoffs + + 8. **Terminology and Consistency** + - Overloaded terms used with multiple meanings + - Undefined abbreviations, acronyms, or jargon + - Context-dependent terms without clear definitions + - Inconsistent naming across requirements + + 9. **Completion Signals** + - Missing acceptance criteria or definition of "done" + - Unspecified success metrics or verification methods + - Missing done conditions for workflows or processes + - Unclear testing or validation requirements + + 10. **Misc and Placeholders** + - TODO markers without resolution + - TBD placeholders or "to be determined" language + - Comments indicating missing information + - Deferred decisions that block implementation + + For each category, identify specific ambiguities that would **materially impact implementation**. + +5. **Generate question queue (max 5 questions)** + + - Prioritize ambiguities by **blocking potential** (what would stop or significantly slow implementation?) + - Select top 5 most impactful questions + - If fewer than 5 ambiguities found, include all + - If **no ambiguities found**, report: "Specs are clear! No ambiguities detected." and terminate successfully + +6. **Interactive Q&A loop** + + For each question: + + **Question Format Options:** + + A. **Multiple-choice (for enumerable options)**: + \`\`\` + Question 2 of 5 - *Category: Constraints* + + **What is the maximum file upload size?** + + | Option | Description | Pros/Cons | + |--------|-------------|-----------| + | 10 MB | Standard limit | Simple, covers most use cases | + | 50 MB | Medium limit | Supports larger files, moderate storage cost | + | 100 MB (Recommended) | Large limit | Handles all common scenarios, higher storage/bandwidth cost but best UX | + | No limit | Unlimited | Flexible but risk of abuse and storage issues | + + Please select an option or provide custom answer: + \`\`\` + + B. **Short-answer (for open-ended)**: + \`\`\` + Question 3 of 5 - *Category: Terminology* + + **What does "session" mean in this context?** + + Suggestions: "User login session", "Data collection session", "WebSocket connection session" + + Please provide answer (≤5 words if possible): + \`\`\` + + **User Response Options:** + - Provide answer (from options or custom) + - Type "skip" or "defer" to skip question + - Type "done" or "stop" to end early + + **Validation:** + - Multiple-choice: Verify answer matches an option (or is clearly custom) + - Short-answer: Reject empty responses + - Re-prompt if invalid + + **Incremental Integration:** + After each valid answer, immediately: + - Add/append to the spec's \`## Clarifications\` section + - Use format: \`**Q: [question]** → A: [answer]\` under a timestamped session (e.g., \`### Session 2026-02-12\`) + - Apply the answer to relevant spec sections (update requirements, add scenarios, add constraints, etc.) + - Confirm write succeeded before showing next question + +7. **Update spec sections based on clarifications** + + For each answer, intelligently update the appropriate spec sections: + + - **Clarification resolves ambiguous requirement** → Update requirement text to incorporate answer + - **Clarification defines new edge case** → Add new scenario to relevant requirement + - **Clarification defines terminology** → Add glossary entry or definition + - **Clarification specifies constraint** → Document in constraints or add to requirement + + **Cross-spec propagation:** If an answer applies to multiple capabilities, write it to all relevant spec files. + +8. **Coverage summary report** + + After Q&A completes (or user stops early), generate a summary: + + \`\`\` + ## Clarification Summary + + **Change:** + **Status:** 3/5 questions answered + + | Category | Resolved | Deferred | + |----------|----------|----------| + | Functional Scope | 1 | 0 | + | Constraints | 2 (Recommended) | 0 | + | Edge Cases | 0 | 1 | + | Terminology | 0 | 1 | + + ### Deferred Items + - [Edge Cases] Behavior when concurrent uploads occur + - [Terminology] Definition of "active user" + + **Next Steps:** + - Run \`/opsx:clarify\` again to address deferred items + - Or continue creating artifacts: \`/opsx:continue\` + \`\`\` + +**Ambiguity Detection Guidelines** + +When scanning specs, look for: +- Vague or abstract language without concrete details +- References to undefined entities, types, or systems +- Missing specifications for common cases (empty input, errors, limits) +- Overloaded terms used inconsistently +- Placeholder language (TODO, TBD, "will be defined") +- Implicit assumptions not stated explicitly +- Missing acceptance criteria or success metrics + +**Question Generation Guidelines** + +Good questions: +- Target specific implementation blockers +- Have clear, actionable answers +- Include AI-generated recommendations with explicit reasoning +- Present recommendations inline in tables using "(Recommended)" marker +- Use acceptance phrases like "yes", "recommended", "suggested" for default options +- Are scoped to the change at hand + +Avoid: +- Questions about things already clearly specified +- Over-detailed questions that belong in implementation +- Questions that can't reasonably be answered without extensive research + +**Spec Integration Guidelines** + +- **Add \`## Clarifications\` section** if it doesn't exist (place at end of spec file, after all other sections) +- **Use timestamped sessions** (e.g., \`### Session 2026-02-12\`) to track multiple clarification runs +- **Format answers**: \`**Q: [question]** → A: [answer]\` with category label +- **Update existing sections** to reflect clarifications (don't just append to Clarifications) +- **Write incrementally** (one answer at a time, not batched) +- **Validate consistency** - warn if answer contradicts existing spec content + +**Guardrails** + +- **Max 5 questions** per session (keeps sessions focused) +- **Prioritize by blocking potential** (implementation blockers first) +- **Allow early termination** (user can stop anytime with "done") +- **Allow deferrals** (user can skip questions with "skip") +- **Validate answers** before writing (reject empty, malformed, or invalid responses) +- **Write incrementally** (each answer written immediately, preserves work if interrupted) +- **Report clearly** if no specs exist or no ambiguities found + +**Example Session Flow** + +\`\`\` +Using change: add-user-auth + +Loading specs... Found 2 specs +Scanning for ambiguities... + +Found 7 ambiguities across 4 categories. Prioritizing top 5 questions. + +--- + +Question 1 of 5 - *Category: Data Model* + +**What fields should the User entity include?** + +Suggestions: "email, password_hash, created_at", "email, username, password_hash, role, created_at" + +Please provide answer: [user response] + +✓ Answer recorded. Updating spec... + +--- + +Question 2 of 5 - *Category: Non-Functional* +... +\`\`\``, + license: 'MIT', + compatibility: 'Requires openspec CLI.', + metadata: { author: 'openspec', version: '1.0' }, + }; +} + +export function getOpsxClarifyCommandTemplate(): CommandTemplate { + return { + name: 'OPSX: Clarify', + description: 'Clarify underspecified areas in specs through interactive Q&A (Experimental)', + category: 'Workflow', + tags: ['workflow', 'clarify', 'experimental'], + content: `Clarify underspecified areas in an OpenSpec change by systematically identifying ambiguities and resolving them through interactive Q&A. + +**Input**: Optionally specify a change name after \`/opsx:clarify\` (e.g., \`/opsx:clarify add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. + +**Steps** + +1. **Select the change** + + If a name is provided, use it. Otherwise: + - Infer from conversation context if the user mentioned a change + - Auto-select if only one active change exists + - If ambiguous, run \`openspec list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select + + Always announce: "Using change: " and how to override (e.g., \`/opsx:clarify \`). + +2. **Check status to verify specs exist** + \`\`\`bash + openspec status --change "" --json + \`\`\` + Parse the JSON to check: + - Does the change have spec artifacts completed? + - If no specs exist, report: "This change doesn't have spec artifacts yet. Create them with \`/opsx:continue\` first." and terminate. + +3. **Load spec artifacts** + + Read all spec files from the change's specs directory (pattern: \`openspec/changes//specs/**/*.md\`). + + Use the file reading tools to load each spec file for analysis. + +4. **Scan for ambiguities using the taxonomy** + + Systematically scan the specs across **10 categories**: + + 1. **Functional Scope and Behavior** + - Vague verbs without concrete definitions ("handle", "process", "manage", "deal with") + - Missing input/output specifications or format details + - Incomplete user/system flows or interaction sequences + - Unspecified behavior for common operations + + 2. **Domain and Data Model** + - Undefined types, entities, or data structures + - Unclear relationships between entities (1:1, 1:N, M:N) + - Missing validation rules or constraints on data + - Unspecified data formats, schemas, or serialization + + 3. **Interaction and UX Flow** + - Missing feedback states (loading, success, error, empty) + - Unclear navigation paths or state transitions + - Interaction gaps (what happens between steps) + - Unspecified user input validation or feedback + + 4. **Non-Functional Quality Attributes** + - Missing performance targets (latency, throughput, response time) + - Unspecified security requirements (authentication, authorization, encryption) + - Missing accessibility criteria (WCAG levels, screen reader support) + - Unclear reliability/availability requirements (uptime, fault tolerance) + + 5. **Integration and External Dependencies** + - References to undefined external systems or services + - Missing API contracts, protocol details, or data formats + - Unspecified error handling for external failures + - Missing fallback or retry strategies + + 6. **Edge Cases and Failure Handling** + - Unspecified behavior for empty/null/zero inputs + - Missing boundary condition handling (min/max values) + - Unclear concurrent operation behavior (race conditions, conflicts) + - Unspecified failure modes and recovery strategies + + 7. **Constraints and Tradeoffs** + - Missing limits or quotas (rate limits, size limits, count limits) + - Unspecified resource boundaries (memory, disk, bandwidth) + - Missing capacity planning considerations + - Unclear cost/performance tradeoffs + + 8. **Terminology and Consistency** + - Overloaded terms used with multiple meanings + - Undefined abbreviations, acronyms, or jargon + - Context-dependent terms without clear definitions + - Inconsistent naming across requirements + + 9. **Completion Signals** + - Missing acceptance criteria or definition of "done" + - Unspecified success metrics or verification methods + - Missing done conditions for workflows or processes + - Unclear testing or validation requirements + + 10. **Misc and Placeholders** + - TODO markers without resolution + - TBD placeholders or "to be determined" language + - Comments indicating missing information + - Deferred decisions that block implementation + + For each category, identify specific ambiguities that would **materially impact implementation**. + +5. **Generate question queue (max 5 questions)** + + From the ambiguities found: + - **Prioritize**: Implementation blockers > High-impact design decisions > Clarifications + - **Limit to 5 questions**: Focus on most critical gaps + - **Generate AI recommendations** for each question: + - Multiple-choice format with 2-3 concrete options + - Each option backed by brief reasoning + - Mark one option as "(Recommended)" based on context + +6. **Interactive Q&A Loop** + + For each question (up to 5): + + a. **Present question with recommendations**: + \`\`\` + Question X of 5 - *Category: * + + **** + + | Option | Description | Reasoning | + |--------|-------------|-----------| + | A |