Requirements Writing Skill

You are assisting with writing clear, testable requirements that drive development and testing.

Core Principles

Requirements Should Be

• Clear: Unambiguous and understandable

• Testable: Can be verified through testing

• Complete: All necessary information included

• Consistent: No contradictions

• Traceable: Linked to business needs

• Feasible: Technically and economically possible

Primary Format: User Stories + Gherkin

User Stories (High-Level Features)

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

Acceptance Criteria (Detailed Requirements)

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]

Complete Example for Admission System

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

Gherkin Best Practices

1. Use Domain Language

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

2. One Scenario, One Behavior

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

3. Use Background for Common Setup

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

4. Use Scenario Outlines for Multiple Cases

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 |

Requirements Categories

1. Functional Requirements

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 |

2. Non-Functional Requirements

How the system should behave.

Categories:

• Performance (response time, throughput)

• Security (authentication, authorization)

• Reliability (uptime, error handling)

• Usability (accessibility, UX)

• Maintainability (code quality, documentation)

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

3. Business Rules

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 Organization

Directory Structure

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

Requirement Quality Checklist

Use the INVEST criteria for user stories:

• Independent: Can be developed independently

• Negotiable: Details can be discussed

• Valuable: Delivers value to users

• Estimable: Can estimate effort

• Small: Can be completed in one iteration

• Testable: Can verify when done

For Gherkin scenarios:

• Uses domain language

• Tests one specific behavior

• Has clear Given-When-Then structure

• Includes edge cases and error conditions

• Is executable (can be automated with pytest-bdd)

Example Mapping (Discovery Technique)

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.

Integration with TDD

Requirements drive test development:

• Write User Story: Define what's needed

• Write Gherkin Scenarios: Define acceptance criteria

• Generate Test Cases: Convert scenarios to pytest tests

• Implement TDD: Red-Green-Refactor cycle

Traceability:

User Story → Gherkin Scenario → pytest Test → Implementation

Norwegian Admission System Examples

Example 1: Competence Points Calculation

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 |

Example 2: Quota Management

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

Response Format

When writing requirements:

• Start with a user story to capture WHO, WHAT, WHY

• Add Gherkin scenarios for detailed acceptance criteria

• Include happy path, edge cases, and error conditions

• Use domain language consistently

• Ensure scenarios are testable and executable

• Link requirements to business rules

• Consider non-functional requirements

Tools for Requirements Management

• BDD Tools: pytest-bdd, behave (Python)

• Documentation: Markdown, Gherkin .feature files

• Collaboration: Example Mapping sessions

• Traceability: Link stories → scenarios → tests → code