speckit-clarify

To resolve ambiguities in a feature specification, scan the spec for underspecified areas and generate up to five targeted clarification questions, then encode accepted answers back into the spec. This reduces downstream rework by ensuring acceptance criteria and data shapes are explicit.

Spec ambiguities to clarify include functional scope, data model shapes, UX flows, non-functional attributes, integrations, edge cases, constraints, and terminology. The clarification process prioritizes high-impact uncertainties within these categories to ensure security requirements and acceptance criteria are explicit.

To interactively clarify requirements in a spec-kit project, run a prerequisite discovery script within the .specify directory to expose FEATURE_DIR and FEATURE_SPEC. The system then asks one multiple-choice or short-answer question at a time, recommends an option, validates the response, and writes accepted answers into a Clarifications section.

Yes, a prerequisite script exposing FEATURE_DIR and FEATURE_SPEC is required to enforce safe, atomic spec updates. This ensures the feature specification exists, enforces formatting and validation rules, and updates the spec incrementally with one accepted answer per write operation.

No, the clarification session is limited to a maximum of five prioritized questions. This constraint focuses the interactive loop on high-impact uncertainties, ensuring functional scope and data model ambiguities are resolved efficiently without overwhelming the product manager or engineer.

The best way to enforce short-answer or multiple-choice responses is to use an interactive clarification loop that validates inputs against formatting rules. This mechanism ensures each accepted clarification is properly constrained before being atomically written back into the spec's sessioned Clarifications section.