Requirements Planning

Requirements Planning

A complete reference for writing requirements that are clear, testable, and ready for development — from individual user stories to full PRDs.

When to Activate

• Writing a PRD, one-pager, or product requirements document
• Creating user stories or acceptance criteria for a feature
• Story pointing or sprint planning
• Breaking down an epic into implementable tasks
• Defining Done criteria for a story or sprint
• Reviewing whether requirements are testable and complete

---

User Stories

INVEST Criteria

Every well-formed user story satisfies all six INVEST properties.

| Criteria | Meaning | Test question | |--------------|------------------------------------------------------|------------------------------------------------| | Independent | Can be developed without depending on another story | "Can this be built and deployed alone?" | | Negotiable | Details can be discussed, not a rigid contract | "Is there flexibility in the how?" | | Valuable | Delivers value to a user or stakeholder | "Who benefits and how?" | | Estimable | Team can roughly size it | "Do we know enough to estimate?" | | Small | Can be completed in one sprint | "Can one developer finish this in ≤5 days?" | | Testable | Acceptance criteria can be verified | "How will we know it's done?" |

Story Format

As a ,
I want to ,
so that .

BAD — This is a task disguised as a story:

As a developer,
I want to implement the login endpoint,
so that the API exists.

GOOD — Clear role, action, and benefit:

As a returning user,
I want to log in with my email and password,
so that I can access my account and personal data.

Common Anti-Patterns

• Story is a task — "Implement the login endpoint" describes technical work, not user value. Reframe around what the user can do.
• No acceptance criteria — Without AC, there is no shared definition of done. Write AC before any code is written.
• Story spans multiple sprints — If a story cannot be completed in a single sprint, split it using vertical slicing (see below).
• Story says how instead of what — Requirements describe the desired outcome, not the implementation. Leave the how to the team.
• Passive voice hides the actor — "Notifications should be sent" — by whom? to whom? Make the subject explicit.

---

Acceptance Criteria

BDD Format (Gherkin-style)

Use for behavioral, user-facing requirements. Each scenario maps to a test case.

Given 
When 
Then 
And   # optional

Example — login story:

Given a registered user with email "user@example.com"
When they submit valid credentials
Then they receive a JWT access token
And they are redirected to the dashboard

Given a registered user
When they submit an incorrect password 3 times
Then their account is locked for 30 minutes

Given a registered user whose account is locked
When they attempt to log in
Then they see the message "Account locked. Try again in 30 minutes."

Checklist-Style AC

Use for non-behavioral or non-functional requirements where Given/When/Then does not fit naturally.

- [ ] Response time < 200ms at p95
- [ ] Works on Chrome, Firefox, Safari (last 2 versions)
- [ ] Error message shown for invalid input
- [ ] Form fields validated client-side before submission

Functional vs Non-Functional AC

| Type | Example | Who writes it | |---------------|--------------------------------------------------|-----------------------| | Functional | "User can reset password via email link" | PO / Dev together | | Performance | "API responds in < 500ms" | Dev / SRE | | Security | "Session expires after 30 min inactivity" | Security / Dev | | Accessibility | "Form navigable by keyboard" | Designer / Dev |

Non-functional requirements are frequently omitted. Make them explicit on every story where they apply.

---

PRD Template

Use this template when writing a product requirements document, feature brief, or one-pager.

# PRD: [Feature Name]

## Problem Statement
[1–2 sentences: what problem are we solving and for whom?]

## Goals
- Goal 1 (measurable)
- Goal 2

## Non-Goals
- Explicitly out of scope item 1
- Explicitly out of scope item 2

## User Personas
| Persona | Description | Primary need |
|---------|-------------|-------------|
| ...     | ...         | ...         |

## Functional Requirements
1. [REQ-001] The system shall...
2. [REQ-002] The system shall...

## Non-Functional Requirements
- Performance: [e.g., p95 latency < 300ms]
- Security: [e.g., data encrypted at rest]
- Scalability: [e.g., support 10k concurrent users]

## Out of Scope
- ...

## Open Questions
| Question | Owner | Due |
|----------|-------|-----|
| ...      | ...   | ... |

## Success Metrics
- Metric 1: [e.g., 20% increase in activation rate]
- Metric 2: [e.g., 0 P0 security incidents]

## Timeline
| Milestone | Date |
|-----------|------|
| ...       | ...  |

PRD Writing Tips

• Non-Goals are mandatory. Explicitly stating what is out of scope prevents scope creep and misaligned expectations.
• Every goal must be measurable. "Improve performance" is not a goal. "Reduce p95 latency from 800ms to 300ms" is a goal.
• Open questions block progress. Assign every open question an owner and a deadline. Review at the next refinement session.
• Success metrics connect to goals. If you cannot measure whether a goal was achieved, the goal is not yet well-formed.

---

Story Pointing

Fibonacci Scale

Points are assigned from the sequence: 1, 2, 3, 5, 8, 13, 21 (and ∞ for "we cannot estimate this yet").

• Points measure complexity + uncertainty, NOT hours worked.
• A story pointed at 8 is roughly twice as complex and uncertain as a story pointed at 3.
• Calibration anchor: pick a well-understood story the team agrees is a 3, then size all others relative to it.
• If a story is pointed at 13 or 21, strongly consider splitting it before the sprint.
• ∞ means the team lacks enough information to estimate — do discovery work before committing to the story.

T-Shirt Sizing (Alternative)

Use XS / S / M / L / XL when:

• The team is new and has no calibration anchor.
• Estimating at the epic level rather than the story level.
• Rough relative sizing is sufficient (roadmap planning, not sprint planning).

Map to Fibonacci before sprint planning: XS → 1–2, S → 3, M → 5, L → 8, XL → 13+.

Planning Poker Norms

• Everyone reveals their estimate simultaneously — avoids anchoring on a loud voice.
• High variance (e.g., one person says 3, another says 13) means the team has different assumptions. Discuss, do not average.
• After discussion, re-estimate if the spread was greater than 2 sizes.
• Keep the round time-boxed: aim to settle an estimate in under 5 minutes.

What Affects Points

| Increases points | Does NOT affect points | |-------------------------------------------|----------------------------------| | Technical complexity | Who will work on it | | Uncertainty / unknowns | Time of day or week | | Integration risk (third-party APIs, etc.) | Developer seniority or speed | | Testing surface area | Calendar deadline pressure | | Cross-team dependencies | Whether the work is boring or fun |

---

Epic and Feature Decomposition

Horizontal vs Vertical Slicing

| Approach | Definition | Example | Problem | |------------|-------------------------------------------------|-------------------------------------------------------------------|----------------------------------| | Horizontal | Split by technical layer | "Build the database schema", "Build the API", "Build the UI" | Not independently valuable | | Vertical | Split by user journey / thin feature slice | "User can register with email (no profile picture yet)" | None — preferred approach |

Vertical slices are shippable. Each delivers some user value. Horizontal slices only deliver value when all layers are complete — meaning nothing is releasable until all layers are done.

Walking Skeleton

1. Build the thinnest possible end-to-end slice first (e.g., login → dashboard with placeholder data).
2. This proves the architecture works before building width.
3. Subsequent stories add depth to each slice — more data, edge cases, polish.

The walking skeleton is never the full feature. It is the minimal path through the system.

Decomposition Patterns

| Pattern | Description | Example | |----------------------|-------------------------------------------------------|---------------------------------------------------------| | By user role | Different actors get separate stories | Admin story vs regular user story for the same screen | | By data volume | Simple case first, then scale | "View first 10 items" → "View paginated list" | | By exception flow | Happy path first, error paths separately | "User logs in" → "User sees error on locked account" | | By CRUD operation | Each operation is a separate story | Create → Read → Update → Delete as four stories | | By configuration | Default behaviour first, then customization | "Email sends with default template" → "Custom template" |

---

Definition of Done

Org-Level DoD (applies to all stories)

Copy this into your team's working agreement and adjust as needed.

- [ ] Code reviewed and approved (minimum 1 reviewer)
- [ ] Unit tests written and passing
- [ ] Integration tests passing
- [ ] No new HIGH/CRITICAL security vulnerabilities introduced
- [ ] Feature deployed to staging and smoke-tested
- [ ] Acceptance criteria verified by PO or QA
- [ ] Documentation updated (if applicable)
- [ ] No unresolved review comments left open

Story-Level DoD (specific to the story)

• Written by the team during refinement, before sprint start.
• Lives inside the story ticket as part of the acceptance criteria.
• Example for "User profile picture upload":

```

• [ ] File size validated (max 5MB, reject otherwise with error message)
• [ ] Uploaded file stored in S3 under /users/{id}/avatar
• [ ] S3 URL saved to the users table (avatar_url column)
• [ ] Profile page displays new avatar within 1 page reload
• [ ] Old avatar deleted from S3 on successful replacement

```

Sprint-Level DoD (applies to the sprint as a whole)

- [ ] All stories meeting org-level DoD are merged to main
- [ ] Release notes drafted
- [ ] Regression suite passing on staging
- [ ] PO has signed off on the sprint goal

---

Red Flags

• User stories without acceptance criteria — "as a user I want to log in" is untestable; every story needs explicit Given/When/Then scenarios agreed before development starts
• Estimating in hours — hour estimates imply false precision and ignore team velocity variance; use relative Fibonacci story points for sizing
• Horizontal technical slices ("backend API for X", "DB schema for X") — these deliver no user value alone; always slice to include the full end-to-end user-visible behavior
• Definition of Done defined inconsistently per story — inconsistent DoD creates review surprises; agree on a team-wide DoD (tests, review, deployed to staging) before the sprint starts
• Non-goals written as "future work" — "multi-tenant support in v2" in a non-goals section implies a promise; explicitly state items are out of scope with no timeline
• Success metrics defined as "users will love it" — unmeasurable goals make it impossible to declare a feature successful or failed; tie metrics to specific, observable behavior
• No timebox for stories with unknown technical risk — committing to high-uncertainty stories without a spike investigation leads to wildly missed estimates and scope creep

Checklist

• [ ] Every story follows the "As a / I want / so that" format
• [ ] Story satisfies all INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
• [ ] Acceptance criteria are written before development starts
• [ ] BDD Given/When/Then used for behavioral requirements
• [ ] Non-functional requirements captured explicitly (performance, security, accessibility)
• [ ] Epic decomposed into vertical slices, not horizontal layers
• [ ] Story is sized (points or T-shirt) and team agrees on the estimate
• [ ] Definition of Done agreed upon before sprint starts
• [ ] Open questions in the PRD have owners and deadlines assigned
• [ ] Success metrics are defined, measurable, and tied to stated goals

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kid-sid
• Source: kid-sid/claude-spellbook
• License: MIT

Install and usage instructions live in the source repository linked above.