Requirements Engineering

Patterns for translating product vision into clear, actionable engineering specifications.

User Stories

Standard Format

As a [type of user],
I want [goal/desire],
so that [benefit/value].

INVEST Criteria

Good user stories are:

Criterion	Description	Example Check
Independent	Can be developed separately	No hard dependencies on other stories
Negotiable	Details can be discussed	Not a contract, a conversation starter
Valuable	Delivers user/business value	Answers "so what?"
Estimable	Can be sized by the team	Clear enough to estimate
Small	Fits in a sprint	1-5 days of work typically
Testable	Has clear acceptance criteria	Know when it's done

Story Examples

Good:

As a sales manager,
I want to see my team's pipeline by stage,
so that I can identify bottlenecks and coach accordingly.

Acceptance Criteria:
- [ ] Shows deals grouped by stage (Lead, Qualified, Proposal, Negotiation, Closed)
- [ ] Displays deal count and total value per stage
- [ ] Filters by date range (default: current quarter)
- [ ] Updates in real-time when deals move stages

Bad (too vague):

As a user, I want better reporting.

Bad (solution-focused):

As a user, I want a pie chart on the dashboard.

Acceptance Criteria

Given-When-Then Format (Gherkin)

Feature: User Login

Scenario: Successful login with valid credentials
  Given I am on the login page
  And I have a valid account
  When I enter my email "user@example.com"
  And I enter my password "validpass123"
  And I click the "Sign In" button
  Then I should be redirected to the dashboard
  And I should see "Welcome back" message

Scenario: Failed login with invalid password
  Given I am on the login page
  When I enter my email "user@example.com"
  And I enter my password "wrongpassword"
  And I click the "Sign In" button
  Then I should see "Invalid credentials" error
  And I should remain on the login page

Checklist Format

## Acceptance Criteria: Password Reset

### Functional
- [ ] User can request reset via email
- [ ] Reset link expires after 24 hours
- [ ] Reset link is single-use
- [ ] New password must meet complexity requirements
- [ ] User receives confirmation email after reset

### Edge Cases
- [ ] Handles non-existent email gracefully (no user enumeration)
- [ ] Rate limits requests (max 3 per hour per email)
- [ ] Works with SSO-enabled accounts (shows appropriate message)

### Non-Functional
- [ ] Reset email sent within 30 seconds
- [ ] Page loads in < 2 seconds
- [ ] Accessible (WCAG 2.1 AA)

Product Requirements Document (PRD)

PRD Template

# PRD: [Feature Name]

**Author:** [Name]
**Last Updated:** [Date]
**Status:** Draft | In Review | Approved | Shipped

---

## Overview

### Problem Statement
[1-2 paragraphs describing the problem we're solving]

### Goals
1. [Primary goal with measurable outcome]
2. [Secondary goal]
3. [Secondary goal]

### Non-Goals (Out of Scope)
- [Explicitly what we're NOT doing]
- [Feature for future consideration]

### Success Metrics
| Metric | Current | Target | Timeline |
|--------|---------|--------|----------|
| | | | |

---

## User Stories

### P0 - Must Have (MVP)
- [ ] Story 1: As a..., I want..., so that...
- [ ] Story 2: ...

### P1 - Should Have
- [ ] Story 3: ...

### P2 - Nice to Have
- [ ] Story 4: ...

---

## Design

### User Flow
[Link to Figma/diagrams or embed]

### Wireframes
[Visual mockups]

### Technical Design
[Link to technical spec or high-level architecture]

---

## Dependencies

| Dependency | Owner | Status | ETA |
|------------|-------|--------|-----|
| API endpoint | Backend | In Progress | Week 2 |
| Design assets | Design | Complete | - |

---

## Risks & Mitigations

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| | | | |

---

## Timeline

| Milestone | Date | Status |
|-----------|------|--------|
| PRD Approved | | |
| Design Complete | | |
| Dev Complete | | |
| QA Complete | | |
| Launch | | |

---

## Open Questions
1. [Question that needs resolution]
2. [Decision pending stakeholder input]

---

## Appendix
- [Link to research]
- [Link to competitive analysis]
- [Link to technical RFC]

Requirements Prioritization

Priority Levels

Level	Meaning	Criteria
P0	Must have for MVP	Users cannot accomplish core job without this
P1	Important	Significantly improves experience, high demand
P2	Nice to have	Enhances experience, moderate demand
P3	Future	Backlog for later consideration

Definition of Ready

Before a story enters a sprint:

## Definition of Ready Checklist

- [ ] User story follows standard format
- [ ] Acceptance criteria are complete and testable
- [ ] Dependencies identified and resolved (or planned)
- [ ] Design artifacts available (if applicable)
- [ ] Story is estimated by the team
- [ ] Story fits within a single sprint
- [ ] Product owner available for questions

Definition of Done

Before a story is considered complete:

## Definition of Done Checklist

- [ ] Code complete and reviewed
- [ ] Unit tests written and passing
- [ ] Integration tests passing
- [ ] Acceptance criteria verified
- [ ] Documentation updated
- [ ] Deployed to staging
- [ ] QA sign-off received
- [ ] Product owner acceptance

Functional vs. Non-Functional Requirements

Functional Requirements

What the system should do.

- FR1: System shall allow users to create new accounts
- FR2: System shall send email notifications for new messages
- FR3: System shall support export to CSV and PDF formats

Non-Functional Requirements (NFRs)

Category	Example Requirement
Performance	Page load time < 2 seconds at 95th percentile
Scalability	Support 10,000 concurrent users
Availability	99.9% uptime (8.76 hours downtime/year)
Security	All data encrypted at rest and in transit
Accessibility	WCAG 2.1 AA compliant
Localization	Support English, Spanish, French
Compliance	GDPR and SOC 2 Type II compliant

Best Practices

• Living documents: PRDs evolve—link to retrospective notes
• AI-assisted: Use AI to draft initial requirements, human review for accuracy
• Hybrid approach: Combine concise PRD with evolving user stories
• Measurable success: If you can't define success metrics, don't write the PRD yet
• Reduce rework: Effective requirements eliminate 50-80% of defects (CMU SEI study)

Common Pitfalls

Pitfall	Mitigation
Solution masquerading as requirement	Focus on "what" not "how"
Missing edge cases	Include negative scenarios in AC
Untestable criteria	Use specific, measurable terms
Scope creep	Maintain explicit out-of-scope section
Stale documents	Set review cadence, archive old versions

Related Skills

• product-strategy-frameworks - Strategic context for requirements
• prioritization-frameworks - Prioritizing the backlog
• user-research-methods - Research that informs requirements

Claude Code PDF Handling (CC 2.1.30+)

When extracting requirements from large specification documents:

Reading Large PDFs

Use the pages parameter for PDFs >10 pages:

# Read executive summary and overview (pages 1-10)
Read(file_path="/path/to/spec.pdf", pages="1-10")

# Read requirements section (pages 25-45)
Read(file_path="/path/to/spec.pdf", pages="25-45")

# Read appendix with data models (pages 80-90)
Read(file_path="/path/to/spec.pdf", pages="80-90")

Recommended Workflow

1. Initial scan - Read first 5-10 pages for TOC and structure
2. Identify sections - Note page ranges for requirements, use cases, constraints
3. Extract incrementally - Read relevant sections (max 20 pages per request)
4. Cross-reference - Jump to appendices for data models, glossary

Limits

• Max 20 pages per Read request
• Max 20MB file size
• Large PDFs (>10 pages) return lightweight reference when @ mentioned

---

References

• PRD Template
• User Story Workshop Guide

Version: 1.1.0 (February )