# Clarify Command > Run the `speckit-helper:clarify` workflow from the original Claude slash command. Use when the user asks to clarify ambiguous areas in specifications through targeted Q&A - Skill: `datamaker-kr/clarify-command` (Agent Skill) - Install (CLI): `npx skillmds@latest add datamaker-kr/clarify-command` - Raw SKILL.md: https://api.skillmd.com/api/skills/datamaker-kr/clarify-command/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: datamaker-kr (https://skillmd.com/u/datamaker-kr) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/datamaker-kr/clarify-command --- # speckit-helper:clarify Command Workflow ## Codex Adaptation - Treat the user request or explicitly supplied text as the command arguments. - Use the available Codex file, search, terminal, and clarification capabilities that match the workflow. - Do not depend on Claude-only slash command variables or tool names. # /speckit-helper:clarify Clarify ambiguous areas in an existing specification through targeted Q&A. --- ## Overview This command analyzes an existing specification for vague language, missing edge cases, undefined terms, and unresolved questions. It generates targeted clarification questions, collects answers from the user, and updates the spec inline. The goal is to tighten the specification without expanding its scope. --- ## Workflow ### Step 1: Resolve Feature Slug Determine which specification to clarify: - **If a feature-slug is provided in `the user request or explicit arguments`:** Use it directly. Verify that `.speckit//spec.md` exists. If not, print an error: > "No specification found at `.speckit//spec.md`. Run > `/speckit-helper:specify` to create one first." - **If `the user request or explicit arguments` is empty:** Find the most recently modified spec by scanning all `.speckit/*/spec.md` files using Glob. Sort by modification time and select the newest one. Print which spec was auto-selected: > "Auto-selected most recent spec: ``" - **If no specs exist at all:** Print an error: > "No specifications found in `.speckit/`. Run `/speckit-helper:specify` first." ### Step 2: Read the Specification Read the full contents of `.speckit//spec.md`. Parse and identify the following sections for analysis: - User Stories and their acceptance criteria - Functional Requirements (FR-*) - Non-Functional Requirements (NFR-*) - Assumptions & Constraints - Open Questions - Any text marked with `[Clarification needed]` ### Step 3: Analyze for Ambiguities Scan the specification for the following categories of ambiguity: **Vague Language** Flag any requirements or acceptance criteria containing: - "should" (instead of "must" or "shall") - "might", "may", "could" (uncertain commitment) - "approximately", "roughly", "around" (imprecise quantities) - "etc.", "and so on", "and more" (open-ended lists) - "appropriate", "suitable", "reasonable" (subjective terms) - "fast", "quick", "efficient" (unmeasurable performance) **Missing Edge Cases** Identify requirements that lack: - Error handling behavior - Boundary conditions (empty input, max limits, concurrent access) - Failure and recovery scenarios - Permission and authorization edge cases **Undefined Terms** Find domain-specific terms or acronyms used but never defined in the spec. **Unresolved Markers** Locate all instances of: - `[Clarification needed]` markers - Unchecked `[ ]` items in Open Questions - TODO or TBD placeholders ### Step 4: Generate Clarification Questions From the analysis, generate up to **5** targeted clarification questions. Prioritize questions by impact: 1. Questions that block multiple requirements (highest priority) 2. Questions about core user stories (P1 priority stories) 3. Questions about undefined terms used frequently 4. Questions about missing edge cases in critical flows 5. Questions about vague NFRs (e.g., "What does 'fast' mean in SC-001?") Format each question clearly with context: > **Q1 (FR-003):** The requirement says users "should be able to export data." > Does this mean export is mandatory (must) or optional (should)? What formats > are required? Use the **ask the user a concise clarification** tool to present questions to the user and collect answers. Ask questions one at a time or in a small batch (no more than 5). ### Step 5: Update the Specification Apply the user's answers to the specification by editing `.speckit//spec.md`: - **Add detail** to the relevant sections based on the user's responses. - **Replace vague language** with precise language (e.g., "should" -> "must", "fast" -> "under 200ms"). - **Resolve `[Clarification needed]` markers** by replacing them with the clarified content. - **Check off resolved Open Questions** by changing `[ ]` to `[x]` and adding the resolution inline. - **Add edge case handling** to acceptance criteria where the user confirmed the expected behavior. - **Update the Changelog** table with an entry: - Date: current date - Version: increment patch (e.g., v0.1.0 -> v0.1.1) - Description: "Clarification pass: resolved N items" Use the Edit tool for inline modifications to preserve the rest of the document. ### Step 6: Anti-Scope-Creep Guard **IMPORTANT:** This step is a strict constraint on the clarification process. - ONLY clarify existing requirements. Do NOT add new features or requirements. - If the user's answer implies a new feature, note it in Open Questions instead of adding it to the requirements: > `[ ] User suggested: (out of scope for this clarification)` - If the user wants to add new requirements, direct them to use: > `/speckit-helper:refine ` - Do NOT increase the scope of user stories beyond their original intent. - Do NOT add new user stories, FRs, or NFRs during clarification. ### Step 7: Print Summary After all updates are applied, print a summary: ``` --- Clarification Complete --- Feature: Spec: .speckit//spec.md Changes made: - Resolved ambiguous terms - Clarified requirements - Answered open questions - Remaining open questions: - Remaining [Clarification needed] markers: Suggested next steps: /speckit-helper:clarify (if items remain) /speckit-helper:analyze (run gap analysis) /speckit-helper:refine (add new requirements) ``` --- ## Notes - This command can be run multiple times on the same spec. Each pass should reduce the number of ambiguities. - The anti-scope-creep guard is essential: clarification must only sharpen existing requirements, never expand them. - If the user declines to answer a question, leave the existing text as-is and keep the `[Clarification needed]` marker or open question intact. - Questions should reference specific requirement IDs (FR-001, NFR-002, etc.) so the user has full context when answering.