requirements-engineering

What this skill does

# Requirements Engineering

Structured approaches for capturing what to build before how to build it.

---

## Core Principle

**Specify WHAT, not HOW.** Requirements describe outcomes and behaviors, not implementation details.

---

## EARS Format

**Easy Approach to Requirements Syntax** - structured acceptance criteria.

| Pattern | Template | Use Case |
|---------|----------|----------|
| **Event-driven** | WHEN [event] THEN [system] SHALL [response] | User actions, triggers |
| **Conditional** | IF [condition] THEN [system] SHALL [response] | Business rules |
| **State-driven** | WHILE [state] [system] SHALL [response] | Ongoing behaviors |
| **Ubiquitous** | WHERE [feature] [system] SHALL [response] | Always-true rules |
| **Unconditional** | [system] SHALL [response] | Basic capabilities |

### Examples

| Type | Example |
|------|---------|
| Event | WHEN user clicks "Submit" THEN system SHALL validate all required fields |
| Conditional | IF user is not authenticated THEN system SHALL redirect to login |
| State | WHILE file is uploading system SHALL display progress indicator |
| Ubiquitous | WHERE data is displayed system SHALL use consistent date format |

---

## User Story Format

```
As a [role]
I want [capability]
So that [benefit]
```

### Good vs Bad

| Bad | Good |
|-----|------|
| As a user I want to login | As a returning customer I want to login with my email so that I can access my order history |
| As a user I want a button | As a content creator I want a publish button so that I can share my work publicly |

**Key concept**: The "so that" clause reveals the actual need - often the stated "want" isn't what's really needed.

---

## Requirements Document Structure

| Section | Content |
|---------|---------|
| **Problem Statement** | What problem are we solving? |
| **User Stories** | Who wants what and why? |
| **Acceptance Criteria** | How do we know it's done? (EARS) |
| **Non-Functional** | Performance, security, accessibility |
| **Out of Scope** | What we're NOT building |
| **Success Metrics** | How do we measure success? |

---

## Constitution (Governing Principles)

For complex projects, establish guiding principles before features:

| Element | Purpose |
|---------|---------|
| **Core Values** | What matters most (simplicity > cleverness) |
| **Technical Principles** | Architecture standards |
| **Decision Framework** | How to make trade-offs |
| **Quality Standards** | Testing, review requirements |

**Key concept**: Constitution prevents scope creep and ensures consistency across features.

---

## Clarification Techniques

Before implementation, resolve ambiguities:

| Technique | When to Use |
|-----------|-------------|
| **Ask "what if"** | Edge cases, error scenarios |
| **Present options** | Multiple valid approaches |
| **Challenge assumptions** | "Is this actually required?" |
| **Define boundaries** | What's in/out of scope |

### Questions to Ask

- What happens when [edge case]?
- What does success look like?
- What's the minimum viable version?
- What can we defer to later?

---

## Non-Functional Requirements

| Category | Questions to Answer |
|----------|---------------------|
| **Performance** | Response time? Throughput? Concurrent users? |
| **Security** | Authentication? Authorization? Data protection? |
| **Accessibility** | WCAG level? Screen reader support? |
| **Scalability** | Expected growth? Peak load? |
| **Reliability** | Uptime requirements? Recovery time? |

---

## Anti-Patterns

| Don't | Why |
|-------|-----|
| Specify implementation | "Use React" locks in decisions |
| Assume requirements | Validate with stakeholders |
| Skip edge cases | They become bugs later |
| Mix requirements with design | Conflates what with how |
| Write vague criteria | "System should be fast" is untestable |

---

## Testable vs Untestable

| Untestable | Testable |
|------------|----------|
| "Fast response" | "Response under 200ms" |
| "User-friendly" | "Task completable in <3 clicks" |
| "Secure" | "Passwords hashed with bcrypt" |
| "Scalable" | "Handles 10K concurrent users" |

**Key concept**: If you can't write a test for it, it's not a requirement - it's a wish.