# Feature Specification: `speckit.specify` command automation **Feature Branch**: `004-afraid-to-ask` **Created**: 2025-10-13 **Status**: Draft **Input**: User description: "Afraid to Ask. The requirements are in the .context/afraid-to-ask.md file." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Core Spec Generation (Priority: P1) A developer provides a feature description to the `/speckit.specify` command. The system automatically generates a new feature branch and a complete, structured `spec.md` file based on a template, filling in details derived from the description. **Why this priority**: This is the core functionality. Without it, the feature has no value. **Independent Test**: Can be tested by running the command with a simple description and verifying that the correct branch and a well-formed spec file are created. **Acceptance Scenarios**: 1. **Given** a developer is on the `main` branch, **When** they run `/speckit.specify "New feature"`, **Then** a new branch `[num]-new-feature` is created and checked out, and a `specs/[num]-new-feature/spec.md` file is created. 2. **Given** a feature description, **When** the spec is generated, **Then** the spec file contains all the mandatory sections from the template. --- ### User Story 2 - Validation and Checklists (Priority: P2) After generating the spec, the system automatically creates a `requirements.md` checklist and validates the spec against it. **Why this priority**: This ensures the quality and completeness of the generated spec, which is a key part of the desired workflow. **Independent Test**: Can be tested by checking for the existence and content of the `requirements.md` file after a spec is generated. **Acceptance Scenarios**: 1. **Given** a spec has been generated, **When** the validation step runs, **Then** a `checklists/requirements.md` file is created in the feature directory. 2. **Given** a generated spec has obvious omissions (e.g., empty sections), **When** the validation runs, **Then** the corresponding items in the checklist are marked as failed. --- ### User Story 3 - Interactive Clarification (Priority: P3) When the system encounters ambiguities in the feature description, it adds `[NEEDS CLARIFICATION]` markers to the spec. It then presents these as questions to the user and updates the spec with their answers. **Why this priority**: This handles cases where the AI cannot make a reasonable assumption, making the process more robust. It's P3 because the core generation can function without it for well-defined features. **Independent Test**: Can be tested by providing an ambiguous description and verifying that the system asks for clarification and correctly incorporates the answer. **Acceptance Scenarios**: 1. **Given** a feature description with an ambiguous requirement, **When** the spec is generated, **Then** it contains a `[NEEDS CLARIFICATION]` marker. 2. **Given** a spec with a clarification marker, **When** the clarification flow is triggered, **Then** the user is presented with a formatted question and options. 3. **Given** a user provides an answer, **When** the system processes it, **Then** the `[NEEDS CLARIFICATION]` marker in the spec is replaced with the user's answer. --- ### Edge Cases - What happens when the feature description is empty? - How does the system handle a non-git repository? - How does the system handle a situation where the generated branch name already exists? ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST accept a natural language string as a feature description. - **FR-002**: System MUST generate a unique, kebab-cased feature branch name from the description, prefixed with a 3-digit incrementing number. - **FR-003**: System MUST create and check out a new git branch with the generated name. - **FR-004**: System MUST create a new directory for the feature under the `specs/` directory. - **FR-005**: System MUST create a `spec.md` file in the new feature directory, populated from a template. - **FR-006**: System MUST parse the feature description to populate the sections of the `spec.md` file. - **FR-007**: System MUST create a `checklists/requirements.md` file to validate the spec. - **FR-008**: System MUST identify and flag ambiguous requirements with `[NEEDS CLARIFICATION]` markers (max 3). - **FR-009**: System MUST present clarification questions to the user and update the spec with their answers. - **FR-010**: System MUST handle cases where a generated branch name already exists by checking out the existing branch instead of failing. ### Key Entities *(include if feature involves data)* - **Feature Specification**: A markdown document that describes a new feature. It includes user scenarios, requirements, and success criteria. - **Requirement Checklist**: A markdown document used to validate the quality and completeness of a feature specification. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: A developer can generate a complete and validated draft specification from a one-sentence feature description in under 1 minute. - **SC-002**: 90% of generated specifications require no manual structural changes to the file itself (i.e., the template is correctly applied). - **SC-003**: The clarification process correctly resolves ambiguities in over 95% of cases where it is triggered. - **SC-004**: The time spent by developers writing initial feature specs is reduced by 75%.