clarify

name	clarify
description	Analyze specifications and generate clarification questions to eliminate ambiguity before implementation
argument-hint	<feature-name> [--interactive]
arguments	["feature-name"]
license	MIT
user-invocable	true
allowed-tools	Read, Write, Edit, Glob, Grep, AskUserQuestion
disallowed-tools	Bash

Clarify - Specification Clarification

Scans specifications across 9 key categories and generates targeted clarification questions to eliminate ambiguity before implementation.

Prerequisites

Read the following prerequisite references before execution:

• references/prerequisites_plugin_update.md - Check for plugin updates
• references/prerequisites_principles.md - Read AI-SDD principles document
• references/prerequisites_directory_paths.md - Resolve directory paths using SDD_* environment variables

Relationship to Vibe Detector Skill

This command is complementary to the vibe-detector skill:

Tool	Purpose	When to Use
vibe-detector	Detects vague instructions in user requests	During task initiation
clarify	Scans existing specs for ambiguity and gaps	Before implementation planning

Language Configuration

Output templates are located under templates/${SDD_LANG:-en}/ within this skill directory. The SDD_LANG environment variable determines the language (default: en).

Input

• feature-name: $feature-name

Full argument string: $ARGUMENTS

Fallback: If the value above is empty, remains a literal $ placeholder, or starts with -- (a flag captured positionally), treat the argument as omitted and interpret the full argument string instead. Ask the user interactively when a required argument is missing.

Argument	Required	Description
feature-name	Yes	Target feature name or path (e.g., user-auth, auth/user-login)
--interactive	-	Interactive mode: Answer questions one at a time

Input Examples

Reference: references/command_examples.md

Processing Flow

1. Load Target Specifications

Both flat and hierarchical structures are supported.

See references/target_specification_loading.md for the list of paths to load for flat and hierarchical structures.

Note the difference in naming conventions:

• Under requirement: No suffix (index.md, {feature-name}.md)
• Under specification: _spec or _design suffix required (index_spec.md, {feature-name}_spec.md)

2. Nine Category Analysis

Analyze specifications across 9 key categories. See references/nine_category_analysis.md for:

• Full category definitions and analysis focus
• Clarity level classification (Clear / Partial / Missing)
• Question prioritization criteria
• Question format template

3. Generate Clarification Questions

Based on category analysis, generate up to 5 high-impact questions using the format in references/nine_category_analysis.md.

4. Integrate Answers

After receiving user answers, the main agent (this skill) applies the integration:

1. Review Integration Proposals: Review proposals from clarification-assistant agent output
2. Update Specifications: Apply approved changes to appropriate *_spec.md or *_design.md using Edit/Write tools
3. Mark Resolved: Track which questions have been addressed
4. Generate Diff: Show what was added to specifications

Note: The clarification-assistant agent outputs integration proposals (target file, section, content). This skill applies the actual edits.

Output

Use the templates/${SDD_LANG:-en}/clarification_output.md template for output formatting.

Integration Mode

When user provides answers, use the --integrate flag (e.g. /clarify user-auth --integrate).

This will:

1. Prompt for answers to each question
2. Update specifications incrementally
3. Show diffs of changes

Best Practices

When to Use This Command

Scenario	Recommended Action
Before task breakdown	Run /clarify to catch ambiguities early
After receiving vague requirements	Use with /generate-spec to build complete specs
During spec review	Verify all 9 categories are addressed
Before implementation	Final check to ensure no hidden assumptions

Complementary Commands

See references/complementary_commands.md for the recommended command sequence around /clarify.

Advanced Options

Focus on Specific Categories

Use --categories with a comma-separated list, e.g. /clarify user-auth --categories flow,integrations,edge-cases.

Specify Output Detail Level

Use --detail with one of the following values:

Value	Effect
minimal	Top 3 questions only
standard	Top 5 questions (default)
comprehensive	All identified issues

Post-Clarification Verification

Automatic Verification (Performed)

The following verifications are automatically performed during clarification:

• Nine Category Scan: Comprehensively detect ambiguities across functional scope, data model, flow, etc.
• Clarity Score Calculation: Classify items as Clear/Partial/Missing and calculate overall score
• Question Prioritization: Select questions based on impact, risk, and blocker status

Verification Commands

Reference: references/verification_commands.md

Implementation Readiness Criteria

Clarity Score	Recommended Action
80% or above	Ready for implementation
60-79%	Recommended to resolve Partial items
Below 60%	Further clarification required before implementation

Notes

• Questions are generated based on specification analysis, not assumptions
• Prioritize questions that would cause most implementation uncertainty
• Some ambiguity is acceptable for low-risk, low-impact decisions
• Re-run after major specification updates to catch new ambiguities
• Works best when combined with vibe-detector skill during task initiation