A story is a promise of a conversation

A user story is a small slice of value described from one user's side. The common template comes from Rachel Davies' team at Connextra: As a [role], I want [capability], so that [benefit]. Ron Jeffries described the three parts of a story in 2001 as Card, Conversation, Confirmation: a card with just enough words to identify the need, a conversation where the details are worked out, and a confirmation, the acceptance tests that show it works.

Bill Wake's INVEST checklist (2003) says a good story is Independent, Negotiable, Valuable, Estimable, Small and Testable. In practice, "small" means a few days of work for the team, and "testable" means you can already picture the scenarios.

• Weak: "As a user, I want a claims API." There is no real role, no benefit, and only a technical layer.
• Strong: "As a partner shop owner, I want to report missing cartons while the driver is still at my door, so that I get credit without phoning my sales rep."

Big stories, sometimes called epics, need splitting. Split so that every piece still gives a user something they can see and accept:

• By workflow step: report, driver confirms, finance approves, credit appears.
• By business rule: claims at the door, late claims after the driver leaves; claims up to $50, claims above $50.
• By data variation: missing cartons, damaged cartons, wrong item delivered.
• Happy path first, unhappy paths next: the normal case ships, then the failures get their own stories.
• By role: the shop owner's view first, the shop assistant's later.

Avoid splitting by technical layer (a screen story, an API story, a database story). No layer alone gives a user value, and nobody outside engineering can accept it. When the team does not know enough to size a story, add a spike: a time-boxed investigation, such as two days to check whether the ERP can create credit notes through its API.

To see the whole workflow before you split, Jeff Patton's story map (User Story Mapping, 2014) lays the user's steps left to right and the stories under each step, so you can cut a first release across all steps instead of finishing one step perfectly.

Acceptance criteria as Given/When/Then

Acceptance criteria turn a story into checks that the PM, the developer and the tester read the same way. The most widely used format comes from Dan North, who described it in "Introducing BDD" in 2006: Given some initial context, When an event occurs, Then ensure some outcomes. His example was a cash machine: given the account is in credit and the card is valid and the dispenser contains cash, when the customer requests cash, then the account is debited, cash is dispensed and the card is returned.

Teams that automate these checks often write them in Gherkin, the syntax used by Cucumber and similar tools, which adds a few keywords: Feature, Scenario, And, But, and Scenario Outline with an Examples table for rules that need several values. You do not need the tools to use the format. It is valuable on paper too.

Rules for scenarios that work:

• One behaviour per scenario. If you need two Whens, you have two scenarios.
• Concrete values. "3 cartons of cooking oil at $22 each", never "some items".
• Describe what the user does and sees, not which button they press. "When the driver confirms with his code" survives a redesign; "When he taps the green button" does not.
• An observable Then. Something on a screen, in a record or in a message that a tester can check. "Then the claim is processed correctly" is not a check.
• Short. Three to seven lines. Long scenarios hide several behaviours.

Scenario: Driver confirms a door claim for missing cartons
  Given delivery D-5531 to Ravi's shop lists 10 cartons of cooking oil at $22.00
  And driver Karim is assigned to D-5531
  When Ravi reports 3 cartons missing
  And Karim confirms the claim with his driver code
  Then claim C-1042 for $66.00 shows "Waiting for finance" in the Partner app
  And the claim records Karim as the confirming driver

Boundaries are where bugs live, so test the values on each side of a rule. A Scenario Outline keeps that compact:

Scenario Outline: Driver-confirmed claims up to $50 are approved automatically
  Given a driver-confirmed claim worth <amount>
  When the claim reaches the server
  Then its status is "<status>"

  Examples:
    | amount | status               |
    | 49.99  | Approved             |
    | 50.00  | Approved             |
    | 50.01  | Waiting for finance  |

Finding edge cases on purpose

Edge cases are found by asking the same questions every time. Run this checklist against each story; most stories trigger four or five of the categories.

The "repeats" row deserves special care in any app that retries. A request is idempotent when doing it twice has the same effect as doing it once. The usual way is for the app to create a unique ID for each claim and for the server to ignore a second claim with the same ID. Write it as a scenario, or a slow network will one day create duplicate credit notes.

To find the questions you cannot answer alone, run example mapping, described by Matt Wynne of the Cucumber project in 2015. The PM, a developer and a tester sit with a stack of coloured cards. The story goes on a yellow card, each rule (an acceptance criterion) on a blue card, examples of each rule on green cards under it, and every question nobody can answer on a red card. About 25 minutes is enough for a well-sized story. Many red cards mean the story is not ready: give each question an owner, or split the story. Too many blue cards usually means the story is too big.

Non-functional requirements that bite in operations software

A non-functional requirement (NFR) says how well, or under what conditions, the system must work. Consumer apps that ignore them lose users. Operations software that ignores them keeps its users, who cannot leave, and they quietly go back to paper and chat groups while the data rots. Most failed rollouts in stores and warehouses are NFR failures: the feature worked in the office on Wi-Fi with a new phone and failed at the shop door. Four NFRs matter most, and each can be written as Given/When/Then with numbers.

Offline. Say what works without a network, for how long, and what the user sees. For claims: creating a claim, taking photos and the driver's confirmation work offline for a full day (up to 50 claims and 200 photos). The delivery record downloaded at the depot includes what confirmation needs, such as the assigned driver's code in a protected form. The screen shows how many claims are waiting to send and when the phone last synced. Some things never work offline, and the spec should say so: the finance approval above $50 and the credit note itself. The engineering side of this, from queues to conflicts, is in Offline-first apps and data sync.

Speed on cheap handhelds. "Fast" is untestable. Name the device (your slowest supported phone or the store's handheld model), the conditions (a 500-line delivery, battery saver on, a weak 3G signal), the percentile and the number. Jakob Nielsen's classic limits (1993) are a good guide: about 0.1 seconds feels instant, 1 second keeps the user's flow of thought, and past 10 seconds attention is lost. Android itself shows an "app not responding" dialog when an app does not respond to a tap or key press within 5 seconds. Test on the real device with real data volumes. A laptop emulator on office Wi-Fi tells you almost nothing about a three-year-old phone in a storeroom.

Permissions. Write down who may create, confirm, approve, edit and cancel, and require the server to enforce it. Hiding a button is a design choice, never a security control, because anyone with the API can still call it. Say what happens when a role changes during a shift, and how shared devices work: store handhelds pass between staff, so each person needs their own sign-in or PIN, or the system cannot know who did what. The security side is in Security essentials.

Audit trail. For every change to money or stock, record who (user and role), what (the action, with the value before and after), when (device time and server time), where (shop or store, device, app version) and why (reason code or note). Entries are append-only: a correction is a new entry, and nobody can edit history, administrators included. Keep entries as long as your finance policy requires, and make them searchable by support in under a minute, because "who changed this?" is asked most during disputes.

Ready and done

Acceptance criteria belong to one story. A Definition of Done applies to every story. The 2020 Scrum Guide calls it a formal description of the state of the work when it meets the quality measures the product requires. For an operations product, a good one includes: code reviewed (Pull requests and code review), every scenario covered by an automated or written test, tested on the slowest supported device, analytics events added (Instrumentation), behind a feature flag where risky (Shipping safely), and support notes written.

Many teams also keep a Definition of Ready, a check before a story enters a sprint: scenarios written, open questions answered or split off, designs linked, NFRs noted, and small enough for a few days. Treat it as a guide; a rigid gate can stall a team waiting for perfect stories.

When an outside company builds the feature, acceptance criteria do two more jobs. They become the user acceptance test cases, and they draw the line between a defect (the build does not do what the criteria say) and a change request (you now want something the criteria never said). Vague criteria make that line blurry, and blurry lines cost money (Working with vendors and agencies).