83 lines
2.4 KiB
Markdown
83 lines
2.4 KiB
Markdown
# Specs - Requirements from JIRA Story
|
|
|
|
This command captures user stories and acceptance criteria in structured EARS notation. It does not implement anything, but helps to define the requirements clearly.
|
|
|
|
## Usage
|
|
|
|
To create a new requirement, just type:
|
|
|
|
```
|
|
/spec:req <jira_issue_id>
|
|
```
|
|
|
|
## What This Command Does
|
|
|
|
1. Retrieves the story with the given ID <jira_issue_id> from JIRA.
|
|
2. Checks if a folder with a filepath-safe version of <jira_issue_id> already exists under `.specs`, if not it creates it.
|
|
3. Checks if a file named `requirements.md` exists in the newly created folder, if not it creates one.
|
|
4. Turns the description of the JIRA story into a fully fleshed out `requirements.md` file in the appropriate format.
|
|
5. Asks the user for additional details to fill out the requirements. This is a repetitive process until all details are captured.
|
|
6. Once finished, it asks the user to review the `requirements.md` file.
|
|
7. If the user approves, it determines the changes to the original requirements and posts them as comment to the JIRA issue in the language of the original issue description.
|
|
|
|
## Appropriate Format
|
|
|
|
```md
|
|
<!-- markdownlint-disable-file MD024 -->
|
|
<!-- markdownlint-disable-file MD013 -->
|
|
<!-- markdownlint-disable-file MD040 -->
|
|
|
|
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
Describe the feature in a detailed paragraph.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1
|
|
|
|
**User Story** Describe the user story for requirement 1.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. Describe the first acceptance criterion in EARS format.
|
|
2. Describe the second acceptance criterion in EARS format.
|
|
3. Describe the third acceptance criterion in EARS format.
|
|
|
|
### Requirement 2
|
|
|
|
**User Story** Describe the user story for requirement 2.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. Describe the first acceptance criterion in EARS format.
|
|
2. Describe the second acceptance criterion in EARS format.
|
|
```
|
|
|
|
## EARS format
|
|
|
|
EARS (Easy Approach to Requirements Syntax) notation provides a structured format for writing clear, testable requirements. Each acceptance criterion should be expressed in the following format:
|
|
|
|
```
|
|
WHEN [condition/event]
|
|
THE SYSTEM SHALL [expected behavior]
|
|
```
|
|
|
|
```
|
|
IF [unwanted condition/event],
|
|
THEN THE SYSTEM SHALL [system response/behavior]
|
|
```
|
|
|
|
```
|
|
WHILE [system state],
|
|
THE SYSTEM SHALL [system response/behavior]
|
|
```
|
|
|
|
```
|
|
WHERE [feature],
|
|
THE SYSTEM SHALL [system response/behavior]
|
|
```
|
|
|
|
Note these patterns can be combined for more complex scenarios.
|