Skip to main content

πŸ“ Requirements Phase Documentation

The requirements phase forms the foundation of specification-driven development, where vague feature ideas are transformed into clear, testable requirements using the EARS (Easy Approach to Requirements Syntax) format. This phase ensures shared understanding among all stakeholders about what needs to be built before proceeding to design and implementation stages.

Purpose and Objectives​

The requirements phase serves to:

  • Transform vague ideas into specific, measurable, and testable requirements
  • Establish clear acceptance criteria for evaluating feature success
  • Create shared understanding among all project participants
  • Provide a basis for decision-making during design and implementation phases
  • Enable effective testing and validation strategies

Step-by-Step Process​

Step 1: Initial Requirements Generation​

Objective: Create an initial draft of requirements based on a feature idea

Process:

  1. Analyze the feature idea: Break down the core concept into user scenarios
  2. Identify user roles: Determine all participants interacting with the feature
  3. Formulate user stories: Describe in the format "As a [role], I want [feature] so that [benefit]"
  4. Translate into EARS requirements: Convert user stories into testable acceptance criteria

Key Principles:

  • Start with user experience, not technical implementation
  • Focus on observable and measurable system behavior
  • Systematically consider edge cases and error scenarios
  • Think about the complete user journey, not isolated steps

Step 2: Structuring Requirements in EARS Format​

Objective: Formalize requirements in a standardized, testable format

Document Structure:

### Requirement 1
**User Story:** As a [role], I want [feature] so that [benefit]

#### Acceptance Criteria
1. WHEN [event] THEN the system SHALL [response]
2. IF [precondition] THEN the system SHALL [response]
3. WHEN [event] AND [condition] THEN the system SHALL [response]

[Additional requirements...]

Core EARS Templates​

1. Simple Event-Response (most common template)
Used for direct system responses to user actions

Example:
WHEN the user clicks the "Submit" button THEN the system SHALL validate form data

2. Conditional Behavior
Applied when an action depends on the current system state

Example:
IF the user is authenticated THEN the system SHALL display the user dashboard

3. Complex Conditions
Combines multiple conditions using logical operators

Example:
WHEN the user submits the form AND all required fields are filled THEN the system SHALL process the submission

4. Error Handling
Describes system behavior in exceptional situations

Example:
WHEN the user submits invalid data THEN the system SHALL display specific error messages

EARS Application Guidelines​

  • WHEN: Always start with a triggering event (user action or system event)
  • IF: Use to describe preconditions that must be true
  • THEN: Clearly define expected system behavior (always use "SHALL")
  • AND/OR: Use to combine conditions, but avoid excessive complexity
  • SHALL: Use consistently for mandatory requirements (do not mix with "MAY" or "SHOULD")

Formulation Tips​

  • Avoid technical implementation details ("the system uses Redis")
  • Do not use vague terms ("fast," "convenient")
  • Each requirement must be independent and testable
  • Verify requirement completeness: happy path, edge cases, errors

Step 3: Requirements Validation​

Validation Criteria:

  • Each requirement is testable and measurable
  • Requirements cover normal, edge, and error scenarios
  • User stories provide clear business value
  • Acceptance criteria are specific and unambiguous
  • Requirements are independent and non-conflicting
  • All user roles and their interactions are accounted for

Verification Questions:

  • How will we verify this requirement is fulfilled?
  • Is the expected behavior clearly defined?
  • What assumptions are embedded in this requirement?
  • What happens upon failure or in exceptional situations?
  • Are all user scenarios covered?

Step 4: Iterative Refinement​

Refinement Process:

  1. Stakeholder review: Gather feedback on completeness and accuracy
  2. Gap identification: Find missing scenarios or ambiguous wording
  3. Ambiguity resolution: Eliminate vague or conflicting requirements
  4. Add missing details: Include edge cases and error handling
  5. Business value verification: Confirm each requirement serves a specific purpose

Recommendations:

  • Implement one change per iteration to track modifications
  • Record approval from all stakeholders after changes
  • Document rationale for key decisions
  • Maintain an appropriate level of detail: specific enough for clarity, but not at implementation level

Final Requirements Checklist​

Completeness​

  • All user roles and scenarios are accounted for
  • Normal, edge, and error cases are covered
  • All interactions have defined system responses
  • Business rules and constraints are explicitly documented

Clarity​

  • Requirements use precise, unambiguous language
  • Technical jargon is either absent or clearly defined
  • Wording maintains a user-centric perspective
  • Expected behavior is concrete and measurable

Consistency​

  • EARS format is applied consistently throughout the document
  • Terminology is uniform across the entire document
  • Requirements do not contradict each other
  • Similar scenarios follow a unified template

Testability​

  • Each requirement can be verified through testing
  • Success criteria are observable and quantitatively measurable
  • Both input conditions and expected results are specified
  • Wording is specific enough to develop test cases

Examples of Well-Formulated Requirements​

Example 1: User Registration Feature​

User Story: As a new user, I want to create an account so that I can access personalized features.

Acceptance Criteria:

  1. WHEN the user provides a valid email and password THEN the system SHALL create a new account
  2. WHEN the user provides an existing email THEN the system SHALL display the error "Email already registered"
  3. WHEN the user provides an email in an invalid format THEN the system SHALL display the error "Invalid email format"
  4. WHEN the user provides a password shorter than 8 characters THEN the system SHALL display the error "Password must be at least 8 characters long"
  5. WHEN account creation is successful THEN the system SHALL send a confirmation email within 30 seconds
  6. WHEN account creation is successful THEN the system SHALL redirect to the welcome page

Example 2: Data Validation Feature​

User Story: As a user, I want my input validated in real time so that I can avoid submitting incorrect information.

Acceptance Criteria:

  1. WHEN the user enters data into a required field THEN the system SHALL remove the error highlight for that field
  2. WHEN the user submits a form with empty required fields THEN the system SHALL highlight missing fields in red
  3. WHEN the user enters data that does not match the required format THEN the system SHALL display format requirements below the input field
  4. WHEN all fields pass validation THEN the system SHALL enable the submit button
  5. IF validation fails THEN the system SHALL keep the submit button disabled
  6. WHEN the user hovers over the tooltip icon THEN the system SHALL display an example of correct format

Common Mistakes and How to Avoid Them​

Mistake 1: Vague Wording​

Problem:
"The system must be fast and convenient"

Consequences:
Impossible to verify fulfillment; multiple interpretations

How to Fix:
"WHEN the user requests data THEN the system SHALL display the result within 2 seconds for 95% of requests"

Mistake 2: Including Implementation Details​

Problem:
"The system must use Redis for data caching"

Consequences:
Limits implementation options; focuses on technology rather than outcome

How to Fix:
"WHEN the user repeatedly requests frequently used data THEN the system SHALL return the result within 500 ms"

Mistake 3: Missing Error Handling​

Problem:
Only describing the "happy path" without edge cases

Consequences:
Functionality gaps; unexpected failures during operation

How to Fix:
For each main scenario, add 2–3 error-handling and boundary-condition scenarios

Mistake 4: Untestable Requirements​

Problem:
"The interface must be intuitive"

Consequences:
Impossible to confirm requirement fulfillment

How to Fix:
"WHEN a new user first accesses the system THEN the system SHALL provide an onboarding tour enabling completion of core actions in no more than 3 clicks"

Document Template​

# Requirements for "[Brief Feature Name]"

**Business Objective:** [Description of the feature's business goal and its value to the product/customer]  
**Scope:** [Boundaries of functionalityβ€”what is included/excluded]  
**Related Documents:** [Links to technical specifications, user research, etc.]

---

## [Requirement/Feature Name]

**User Story:**  
As a [user role], I want [feature description] so that [business value/benefit]

### Acceptance Criteria

*(Select the appropriate EARS template and fill in according to instructions)*

1. **[Simple Event-Response]**  
   WHEN [specific event/user action] THEN the system SHALL [observable result]  
   *[Example: WHEN the user clicks the "Save" button THEN the system SHALL save changes to the database]*

2. **[Conditional Behavior]**  
   IF [precondition/system state] THEN the system SHALL [observable result]  
   *[Example: IF the cart contains items THEN the system SHALL display the total amount]*

3. **[Complex Condition]**  
   WHEN [event] AND [additional condition] THEN the system SHALL [observable result]  
   *[Example: WHEN the user enters a password AND password length < 8 characters THEN the system SHALL display an error]*

4. **[Error Handling]**  
   WHEN [exceptional situation] THEN the system SHALL [error-handling action]  
   *[Example: WHEN the server connection is lost THEN the system SHALL display the notification "Check your internet connection"]*

*[Repeat this structure for each independent requirement]*

---

## Requirements Quality Checklist

*(Completed after finalizing the document)*

| Criterion                                                              | Completed | Comment |
| ---------------------------------------------------------------------- | --------- | ------- |
| All requirements are testable and measurable                           | ☐         |         |
| Normal, edge, and error scenarios are covered                          | ☐         |         |
| No technical implementation details included                           | ☐         |         |
| No vague wording ("fast," "convenient")                                | ☐         |         |
| All requirements are independent and non-conflicting                   | ☐         |         |
| Input conditions and expected results specified for each requirement   | ☐         |         |