Writing User Stories

Why User Stories Exist

Before a single line of code is written, a PM has to answer a deceptively hard question: how do you describe a feature so that a designer, an engineer, and a QA tester all understand it the same way?

A user story is the smallest unit of that description. It is not a spec, not a ticket title, and not a wireframe -- it is a short, structured sentence that captures who benefits, what they want to do, and why it matters to them. Teams at Paystack, Flutterwave, Moniepoint, and global product organisations like Atlassian and Google all rely on some version of this format to keep engineering work anchored to real user value instead of a vague feature list.

The Standard Format

As a [type of user],
I want to [do some action],
So that [I get some benefit].

This "role, action, benefit" structure forces three things to be explicit every time:

Example from a Nigerian fintech context

Weak story:

As a user, I want notifications.

Strong story:

As a Moniepoint agent,
I want to receive an SMS alert within 10 seconds of a successful float top-up,
So that I can confirm the transaction with my customer before they leave the shop.

The strong version tells engineering the speed requirement (10 seconds), the channel (SMS), and the reason (in-person confirmation) -- all of which shape technical decisions like whether to use a queue-based notification service or a synchronous call.

Acceptance Criteria: Turning Intent into a Checklist

A user story alone is not buildable. Acceptance criteria are the specific, testable conditions that must be true for the story to be considered finished. The most common format is Given/When/Then:

Given [a starting condition],
When [the user does something],
Then [this should happen].

Example: the Moniepoint agent story above

Given an agent has completed a float top-up of ₦50,000 or more,
When the transaction is confirmed by the payment processor,
Then an SMS is sent to the agent's registered number within 10 seconds.

Given the agent's phone number is invalid or unreachable,
When the SMS fails to send,
Then the alert is also shown in-app and retried once after 30 seconds.

Given the agent has opted out of SMS alerts,
When a top-up completes,
Then no SMS is sent, but the in-app notification still appears.

Notice the third criterion covers an edge case -- what happens when the "happy path" does not apply. Good acceptance criteria always include at least one edge case, because that is usually where bugs and support tickets come from.

The INVEST Checklist

Before a story goes into a sprint, experienced PMs check it against INVEST:

• Independent -- can be built without waiting on another unfinished story
• Negotiable -- describes the need, not a locked-in solution
• Valuable -- delivers something a real user or the business cares about
• Estimable -- the team can size how much effort it takes
• Small -- fits comfortably inside one sprint
• Testable -- has clear acceptance criteria

A story that fails INVEST usually needs to be split. "As a customer, I want a redesigned dashboard" is really an epic hiding inside a story -- it should be broken into stories like "As a customer, I want to see my account balance at the top of the dashboard" and "As a customer, I want to see my last 5 transactions on the dashboard."

Definition of Ready vs Definition of Done

• Definition of Ready (DoR): the bar a story must clear before engineering picks it up -- acceptance criteria written, dependencies known, designs attached if needed.
• Definition of Done (DoD): the bar a story must clear before it ships -- acceptance criteria pass, code reviewed, tested in staging, PM sign-off given.

Teams using Jira or Linear often encode DoR and DoD as checklist templates attached to every story, so nothing slips through informally.

Common Pitfalls

1. Writing stories from the system's perspective, not the user's. "The system shall validate email format" is a technical requirement, not a user story.
2. Bundling multiple goals into one story. If a story has "and" twice in the action, split it.
3. Skipping the benefit. Without "so that," engineers cannot judge which trade-offs matter.
4. Over-specifying UI in the story. Save pixel-level detail for the design file, not the story text.

A well-written user story is a contract of intent, not implementation -- it tells the team exactly what success looks like while leaving room for the best solution to be found.