Requirement Discovery Canvas
Nine fields, in the order you would ask them. The left column is the online store after its first hour; the right column is yours. Under every example is what went wrong, weeks later, when that field was left blank.
In one paragraph, in the words of the person who asked for it: what is this thing, and what does its owner get when it works?
A small shop sells its own products online. A customer finds a product, buys it, and the shop finds out it has been paid so it can ship. The owner wants orders to arrive without phone calls; nothing about "platform", "marketplace" or "scale" was said.
Who uses it? Not roles from an org chart — the people (and systems) whose actions the software has to respond to.
Customer (browses, buys). Admin — in V1 the owner — (creates products, changes price and stock, sees orders). Later and written down as later: warehouse staff, support. The payment provider is an actor too, because it sends us a confirmation we did not ask for at that moment.
For each actor, the concrete verbs — "adds a product to the cart", not "manages cart". Then mark the one workflow whose completion means the thing works.
Customer: browse products → view a product → add to cart → check out → pay → see confirmation. Admin: create product, edit price, edit stock, view orders. The core workflow is the customer's, end to end; everything else exists to make it possible.
What has to exist, and what has to survive a restart? Nouns from the actions, then a line for each: persists / may persist / never persists.
Product, Cart, CartItem, Order, OrderItem, Payment. Must persist: products, orders, payments. May persist: carts (an anonymous cart is a design decision, not a default). An OrderItem snapshots the price at purchase; it does not reference the product's current price.
Time, expected users, data volume, the technologies you already know, the ones you are required to use, budget, and anything legal — each with a number or a name, not an adjective.
One developer, a deadline measured in weeks not months. Tens of customers a day at launch. A few hundred products. Must accept card payments; must not store card numbers (that alone rules out building payments). Must issue an invoice the accountant accepts. The developer knows one web stack well.
What is outside your system and therefore able to fail without you: providers, services, files, other teams' APIs. For each: what do we send, what do we receive, and who is authoritative?
Payment provider (we send an intent to charge; it tells us, later and asynchronously, whether it succeeded — it is authoritative for "paid"). Email delivery. Wherever product images live. In V2, a shipping label service.
After the happy path is written: what if the payment fails, the request repeats, the database is down, the browser closes mid-checkout, the last unit sells twice? For each, what should the customer see and what should the data say?
Payment declined: order stays unpaid, customer told, cart intact. Confirmation arrives twice: second one is a no-op. Two customers buy the last unit: one order succeeds, the other is told at checkout, and stock never goes negative. Provider times out: order is "pending", not "failed", and we ask again.
What do you not understand? Write each one, then rewrite it until it is a question someone could answer and attach the smallest experiment that would answer it.
"Payments" → "what sequence of requests happens between my backend and the provider, and which system is authoritative for paid?" Experiment: a test-mode charge and a confirmation handler, no store around them. "Inventory" → "what happens when two customers buy the last unit at once?" Experiment: one row, two concurrent decrements.
The smallest slice that touches every layer and proves the pieces connect — and the smallest version of the core workflow a real customer could complete after it.
Skeleton: one product in the database, an endpoint that returns it, a page that renders it. First milestone: browse → add to cart → create an order with no payment, so the workflow is testable before the riskiest integration. Payment is the milestone after, preceded by its spike.
How to read this page honestly
What the tool does, and what it deliberately refuses to do.