Menu
Write clear, testable requirements using User Stories and Gherkin scenarios. Capture functional and non-functional requirements with proper acceptance criteria. Use when defining new features or documenting system behavior.
Apply DDD tactical patterns (Entities, Value Objects, Aggregates, Domain Services, Repositories) and strategic design (Ubiquitous Language, Bounded Contexts). Use when modeling complex business logic.
Apply Clean Architecture layering and dependency rules (Domain, Application, Infrastructure, Presentation layers). Use when structuring applications or ensuring dependencies point inward.
Enforce SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) in object-oriented design. Use when writing or reviewing classes and modules.
Follow TDD practices with Red-Green-Refactor cycle. Write tests before implementation, use AAA pattern, and ensure high-quality test coverage. Use when implementing features or fixing bugs.
Follow trunk-based development practices with short-lived branches, frequent integration to main, feature flags, and continuous integration. Use when managing git workflow and releases.
| name | requirements-writing |
| description | Write clear, testable requirements using User Stories and Gherkin scenarios. Capture functional and non-functional requirements with proper acceptance criteria. Use when defining new features or documenting system behavior. |
You are assisting with writing clear, testable requirements that drive development and testing.
Format:
As a [role]
I want [feature/capability]
So that [benefit/value]
Good Examples:
As an applicant
I want to see my calculated competence points
So that I understand my admission chances
As an admission officer
I want to apply quota rules automatically
So that I can process applications efficiently and fairly
Bad Examples:
As a user, I want a button # Too vague
As a developer, I want to use React # Technical, not user-focused
The system should calculate points # Not user-story format
For each user story, define acceptance criteria using Gherkin scenarios.
Gherkin Format:
Feature: [Feature name and brief description]
[Optional: Longer description explaining business value]
Scenario: [Specific situation to test]
Given [initial context/preconditions]
And [additional context]
When [action/event occurs]
Then [expected outcome]
And [additional expectations]
Feature: Minimum Grade Requirement Evaluation
As an admission system
I need to evaluate if students meet minimum grade requirements
So that only qualified applicants are admitted to programs
Scenario: Student meets minimum grade requirement
Given a student has Math grade 5
And the program requires minimum Math grade 4
When evaluating the admission rule
Then the student should pass the grade requirement
And the evaluation reason should be "Meets minimum grade"
Scenario: Student fails minimum grade requirement
Given a student has Math grade 3
And the program requires minimum Math grade 4
When evaluating the admission rule
Then the student should fail the grade requirement
And the evaluation reason should be "Below minimum grade of 4"
Scenario: Student missing required subject
Given a student has no Math grade
And the program requires minimum Math grade 4
When evaluating the admission rule
Then the student should fail the grade requirement
And the evaluation reason should be "Missing required subject: Math"
Scenario: Exact boundary case
Given a student has Math grade 4
And the program requires minimum Math grade 4
When evaluating the admission rule
Then the student should pass the grade requirement
Use terms from the ubiquitous language (DDD):
# GOOD
Given a student has completed videregående education
When calculating competence points
# BAD
Given the user has a high school diploma
When doing the calculation
# GOOD - Tests one thing
Scenario: Quota full prevents admission
Given a quota has capacity 100
And 100 students are already admitted
When admitting a new student
Then admission should be rejected
# BAD - Tests multiple things
Scenario: Quota and grade checks
Given a quota is full
And student has low grades
When admitting student
Then both checks fail
Feature: Quota Assignment
Background:
Given a program "Computer Science" exists
And the program has the following quotas:
| Quota Name | Capacity |
| Ordinary | 100 |
| Special Competence | 20 |
Scenario: First-time applicant assigned to ordinary quota
Given a student is a first-time applicant
When assigning quota
Then the student should be assigned to "Ordinary" quota
Scenario Outline: Grade to competence points conversion
Given a student has a grade of <grade>
When calculating competence points
Then the points should be <points>
Examples:
| grade | points |
| 6 | 24 |
| 5 | 20 |
| 4 | 16 |
| 3 | 12 |
| 2 | 8 |
| 1 | 4 |
What the system must do.
User Story:
As an admission officer
I want to rank all applicants by their competence points
So that I can select the top candidates for admission
Gherkin Scenario:
Scenario: Applicants ranked by competence points
Given the following applicants:
| Name | Points |
| Alice | 55 |
| Bob | 48 |
| Charlie | 52 |
When ranking applicants
Then the ranking should be:
| Rank | Name |
| 1 | Alice |
| 2 | Charlie |
| 3 | Bob |
How the system should behave.
Categories:
Format:
The system shall [requirement]
Measured by [metric]
Examples:
The system shall evaluate admission rules within 2 seconds
Measured by: Response time for rule evaluation API
The system shall handle 1000 concurrent users
Measured by: Load testing with 1000 simulated users
The system shall maintain 99.9% uptime
Measured by: Monthly uptime percentage
Constraints and policies from the domain.
Feature: Quota Priority Rules
Business Rule: Students with special competence qualifications
have priority over ordinary applicants when quotas overlap.
Scenario: Special competence takes priority
Given a student qualifies for both ordinary and special quotas
And special competence quota has available spots
When assigning quota
Then the student must be assigned to special competence quota
requirements/
├── user-stories/
│ ├── applicant-stories.md
│ ├── officer-stories.md
│ └── administrator-stories.md
├── features/
│ ├── admission-evaluation.feature
│ ├── quota-management.feature
│ ├── competence-calculation.feature
│ └── reporting.feature
├── business-rules/
│ ├── norwegian-admission-rules.md
│ └── quota-policies.md
└── non-functional/
├── performance-requirements.md
└── security-requirements.md
Use the INVEST criteria for user stories:
For Gherkin scenarios:
Before writing requirements, use Example Mapping to explore:
Rule: Students must have minimum grade 4 in Math
Examples:
✓ Math grade 5 → Passes
✓ Math grade 4 → Passes (boundary)
✗ Math grade 3 → Fails
✗ No Math grade → Fails
Questions:
? What if student took Math abroad (different grading)?
? What if Math was taken before 2020 (old system)?
? Does "Math" include both Math S1+S2?
Then write Gherkin scenarios for each example + questions.
Requirements drive test development:
Traceability:
User Story → Gherkin Scenario → pytest Test → Implementation
User Story:
As an applicant
I want my competence points calculated automatically
So that I know my competitive score for admission
Acceptance Criteria:
Feature: Competence Points Calculation
Points are calculated based on Norwegian upper secondary grades
using the formula: grade × 4 points per grade
Scenario: Calculate points for complete grade set
Given a student has the following grades:
| Subject | Grade |
| Math | 5 |
| Norwegian | 4 |
| English | 6 |
When calculating total competence points
Then the total should be 60 points
And the breakdown should be:
| Subject | Points |
| Math | 20 |
| Norwegian | 16 |
| English | 24 |
User Story:
As an admission officer
I want quotas to prevent over-admission
So that program capacity is not exceeded
Acceptance Criteria:
Feature: Quota Capacity Enforcement
Scenario: Prevent admission when quota is full
Given an "Engineering" quota with capacity 100
And 100 students are already admitted
When attempting to admit another student
Then the admission should be rejected
And the rejection reason should be "Quota capacity reached"
Scenario: Allow admission when quota has space
Given an "Engineering" quota with capacity 100
And 95 students are already admitted
When attempting to admit another student
Then the admission should be accepted
And the quota filled count should be 96
When writing requirements: