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

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

Risks & Mitigations

Timeline

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

• Initial scan - Read first 5-10 pages for TOC and structure

• Identify sections - Note page ranges for requirements, use cases, constraints

• Extract incrementally - Read relevant sections (max 20 pages per request)

• 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 )