89 lines
5.4 KiB
Markdown
89 lines
5.4 KiB
Markdown
# 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%. |