Requirements & User Stories — The CS50-Friendly Guide to Saying What Your Software Actually Does

"Requirements are promises you make to your future self — and to your users. Write them so your future self doesn't sue you in emotionally charged Git commits."

You're coming off lessons about safer code, security testing, incident response, and logging — good. Now we move one step left on the development conveyor belt: deciding what to build and how to describe it so humans and machines agree. In practice, requirements and user stories are the contract between design, engineering, and security teams (remember logging and audit trails?). Get them wrong and your code might be secure — but useless.

What are requirements? Why they matter

• Requirements are statements describing what a system should do (functional) or how it should behave (non-functional).
• They prevent the “but I thought you meant…” syndrome.

Where they appear in real life: product spec docs, tickets in your issue tracker, acceptance tests, and sometimes in panicked Slack messages at 2 a.m.

Quick taxonomy

• Functional requirements: features and behaviors (e.g., a login form, search, checkout flow).
• Non-functional requirements (NFRs): constraints like performance, scalability, security, privacy, and logging (yes — tie back to the logging & audit trails lesson).
• Constraints: legal, regulatory, budget or platform limitations.
• Stakeholder requirements: what product owners, users, ops, legal, and security care about.

User Stories — the tiny, humane requirement

A user story is a bite-sized requirement written from the user's perspective. It keeps features user-focused and testable.

Classic format:

As a [role], I want [goal], so that [benefit].

Example:

As a registered user, I want to reset my password so that I can regain account access securely.

Why use user stories?

• They frame work in real user value, not technical plumbing.
• Easier to prioritize, estimate, and test.

INVEST — the checklist for a good user story

• Independent: can be developed independently
• Negotiable: not a contract, open to discussion
• Valuable: delivers user or business value
• Estimable: small enough to estimate
• Small: fits in a sprint (or iteration)
• Testable: has clear acceptance criteria

If a story fails INVEST, it’s likely too big, too fuzzy, or too political.

From user story to acceptance tests (bring in automation!)

Every story needs acceptance criteria. These are the measurable conditions that make a story done.

Example acceptance criteria for the password reset story:

• User receives a password-reset email within 2 minutes.
• Reset link expires after 1 hour.
• Reset action logs an authentication event to the audit trail.

Write acceptance tests in Gherkin (Given/When/Then) — great for automated tests and for bridging product <> dev <> QA:

Feature: Password reset
  Scenario: User requests password reset
    Given a registered user with email alice@example.com
    When the user requests a password reset
    Then an email is sent to alice@example.com within 2 minutes
    And the reset token expires after 1 hour
    And an authentication event is logged

Notice the last line — that’s where security and logging lessons pay off. Non-functional requirements like retention period and encryption at rest should be added to the acceptance criteria or a separate NFR document.

Non-functional requirements: don’t let them be the forgotten stepchild

NFRs (performance, security, privacy, maintainability) are often under-specified. But they’re critical:

• Security: "All failed login attempts must be logged with timestamp, IP, and user agent; alerts if >10 failures/min from same IP." (ties into incident response basics)
• Privacy: "PII must be redacted from logs and stored encrypted at rest for 90 days."
• Observability: "Critical transactions must generate audit events with correlation IDs." (ties into logging and audit trails)

Make NFRs testable and link them to acceptance criteria and security testing tools earlier discussed.

From backlog to sprint: practical tips

1. Backlog grooming — clarify stories, split big ones, add acceptance criteria.
2. Estimation — use story points (relative sizing) and velocity to plan.
3. Prioritize with risks — push security-sensitive stories earlier (secure by design).
4. Definition of Done (DoD) — include tests passed, code reviewed, security checks, docs updated, and logs verified.

Story splitting trick: If a story is too big, split by workflow step, happy vs edge cases, or by UI vs backend.

Traceability and accountability

Keep a traceability matrix or link stories to requirements and tests in your tracker. This helps:

• Prove compliance (audit win)
• Map bugs back to requirements
• Prioritize incident response (you’ll remember who asked for which behavior when things blow up)

Common pitfalls (and how to avoid them)

• Vague requirements: Avoid "Make it fast" — instead specify "95th percentile response time < 300ms under X load."
• Hidden requirements: Ask stakeholders explicit questions about security, privacy, and observability. Don’t assume.
• Overloaded stories: If a story touches UI, API, and DB changes, split it.
• No acceptance criteria: You don’t know when you’re done.

Why this matters: vague or missing requirements lead to rework, missed security controls, and stressful late-night hotfixes.

Quick checklist when writing requirements or stories

• Who benefits (role)?
• What do they want (capability)?
• Why do they want it (value)?
• How will we verify it (acceptance criteria/tests)?
• Which non-functional constraints apply (security, privacy, logging, perf)?
• Who needs to sign off (stakeholders)?

Closing: Key takeaways

• User stories keep features user-focused and testable. Use INVEST.
• Acceptance criteria make stories executable tests — automate them (Gherkin helps).
• NFRs (security, logging, privacy) belong in requirements and in the DoD — tie them to your incident response and logging plans.
• Traceability reduces audit pain and speeds up incident response.

"Write a user story like you're writing instructions to someone you love but also someone who will judge you at the performance review." — you, after reading this

Go forth: write clear requirements, demand measurable acceptance criteria, and make sure your security and logging requirements are first-class citizens of the backlog. Your future on-call self will thank you.

Further practice

• Convert a feature idea from your last project into 3 INVEST-compliant user stories.
• Add acceptance criteria that include logging and retention rules.
• Write one Gherkin scenario per story and make it pass with a unit or integration test.