Asking Better Questions
"How do payments work?" cannot be answered in a way that changes what you build. "Which system should be authoritative for whether an order has been paid?" can. The move is rewriting the question until an answer would decide something.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
You are stuck on payments and the only question you can form is "how do payments work?" — how do you turn it into one whose answer changes what you build next?
Checkout is next on the list. You know a payment provider is involved and you have an API key in a test dashboard. You type "how do payments work" into a search box, then into an AI, and both answer at length: cards, tokens, PCI, authorisation versus capture, 3-D Secure. It is all true, none of it tells you what to write, and you are more nervous than before.
Read until it clicks. Open the provider's documentation from the top, watch an integration walkthrough, ask the AI to "explain payments" — collect enough overview that the shape of the thing will eventually become clear. It feels responsible: you are not coding blind, you are learning first.
The overview never runs out. Every page of the documentation is relevant to *some* integration, so you cannot tell which page is relevant to yours, and "I will read one more section" becomes an afternoon that leaves checkout exactly where it was.
- The overview never runs out. Every page of the documentation is relevant to *some* integration, so you cannot tell which page is relevant to yours, and "I will read one more section" becomes an afternoon that leaves checkout exactly where it was.
- The AI answers the question you asked. "How do payments work?" gets an essay about card networks, and the essay is fine — it just contains no decision, because the question contained none. You paste none of it into the store, because there is nowhere to paste it.
- The tutorial makes the decision for you silently. Its sample marks the order paid the moment the browser reports success, because that made the video short. You copy it, and the store now believes the browser about money — a decision you never noticed making.
- When someone asks "what is blocking you?", the honest answer is "payments", which is the same word you started with. Nothing has been narrowed; the unknown has been fed, not sharpened.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Treat the question as the thing you are building, not the thing you ask on the way. A question is finished when you can say what you would do differently depending on its answer. "How do payments work?" fails that test — no answer changes the next line of code — so it is not yet a question; it is the name of a worry.
- Climb by adding what is missing, one rung at a time. Name the components involved (my backend, the provider, the customer's browser). Name the boundary between them (which requests cross it, in which direction). Ask for a mechanism rather than a concept ("what sequence of requests" rather than "how does it work"). Scope it to your system ("when *my* customer checks out"). Finally, ask for a decision: which of the named components should own the fact you care about?
- At each rung, check whether the question has become answerable by something specific — a page of documentation, a test-mode call, a log line — and whether the answer would decide something. The rung where both become true is where you stop climbing and go and find out (Unknown, Question, Experiment).
- Keep the ladder. The vague form is how the worry will resurface next time; the decisive form is what you actually need to know; and the distance between them is the reading you did not have to do.
The same worry, asked three ways
The ladder below is the whole lesson in one device. Read it bottom-up as well as top-down: the decisive question is what the vague one was always trying to ask, and the middle rung is the one you can take to documentation.
Notice what each rung adds. The middle rung adds components, a boundary and a mechanism, which makes it researchable. The bottom rung adds a decision, which makes it decisive. Neither addition is knowledge about payments — both are knowledge about what you need.
why The best form has an answer that chooses a design: if the provider is authoritative, my system needs a webhook endpoint, a payment status on the order and a "payment pending" state, and the order is marked paid only when the provider says so. The vague form is answered by an essay and the better form by a sequence diagram; only the best form is answered by a decision.
The board a good question comes from
A question does not get sharp on its own. It sharpens against what you already know: once "my backend", "the provider" and "the browser" are on the known side, "which of them decides?" is the obvious unknown. The board below is the state of the payments worry after the ladder — one specific question per line, each with the experiment that would answer it.
The assumed column matters as much as the unknown one. "The provider will call us back" was assumed until it was written down; written down, it became the reason the webhook endpoint exists.
- ✓Three parties: the customer's browser, my backend, the provider. The provider is outside my system and can fail without me.
- ✓The order must exist before payment is attempted, so there is something to mark paid.
- ✓Test mode exists, so every experiment below is free and safe.
- ~The provider reports the outcome to my backend, not only to the browser — to be verified in the first experiment, because the whole design rests on it.
- ~One currency and no partial payments in V1, so "paid" is a single fact rather than an amount.
? How do payments work?
becomes Which system should be authoritative for whether an order is paid, and how does my backend learn the provider's verdict?
experiment One test-mode payment with logging on my side of every request and every callback; note which message carries the final verdict and which side sends it.
? What if it goes wrong?
becomes When the provider's confirmation arrives twice, or arrives after my request timed out, what should the order look like afterwards?
experiment Replay the recorded callback twice against a fresh order and observe the order status; then send it before the order is created and observe what happens.
? Do I need all this security stuff?
becomes How does my backend know a confirmation actually came from the provider and not from anyone who found the URL?
experiment Send a hand-made callback with no signature and confirm the endpoint rejects it; this is one page of the documentation, not the whole PCI chapter.
Every line names an observation. The first one decides the design; the other two are the failure questions that follow once the design exists (What If Payment Fails?, Duplicate Requests).
The experiment the decisive question asks for
The decisive question is answered by the provider's documentation — but the *design* it implies is proven by a slice, not by reading. The thinnest slice through payments touches every layer the real integration will need and leaves the store out entirely.
What the slice proves is deliberately narrow. That a confirmation arrives and an order changes state is the mechanism; whether the confirmation can be trusted, repeated or lost is the next lesson. A slice that claimed to settle those would be a demo.
- Backend endpointCreates a test-mode payment for a fixed amount and stores the provider's payment id against a stub order.
- Provider (outside)Processes the test payment and calls my confirmation URL with the outcome.
- Webhook endpointReceives the confirmation, looks up the order by payment id, sets status to paid.
- DatabaseOne orders row with a status column; the slice is a pass if it reads paid afterwards and pending before.
How to do it
Most important first.
- Write the question exactly as it first occurred to you, however vague. It is the top of the ladder and it is useful evidence of what you did not know (Unknown to Specific Question).
- Underline every noun that names a component and every verb that names an action. If there are none — "how do payments work?" has neither — add them: who sends what to whom.
- Replace "how does X work" with "what sequence of Y happens when Z" — a mechanism, with a trigger. Mechanisms have documentation pages and log lines; concepts have essays.
- Add "in my system" or "when my customer does X". A question scoped to your system rules out most of the documentation, which is the point.
- Ask what you would do differently depending on the answer. If nothing, keep climbing. If two designs, you have the decisive form — write both designs down next to it (Question Quality).
- Only now open documentation, search, or an AI — with the decisive question, not the vague one. The answer will be short, and you will know whether it is right because you know what it must decide (Reading Documentation With a Goal).
Worked on a concrete problem
The move has to produce something. This is what it produced.
- Vague: "How do payments work?" No component, no boundary, no mechanism, no decision. Everything answers it and nothing follows.
- Better: "What sequence of requests occurs between my backend and the payment provider when a customer checks out?" Components: my backend, the provider. Boundary: the requests between them. Mechanism: a sequence. Scope: my checkout. This is researchable — it names the exact page of the documentation (the integration flow) and the exact experiment (make a test-mode payment and log every request and callback).
- Best: "Which system should be authoritative for whether an order has actually been paid — my database, the provider's record, or the browser's report of success?" Now an answer decides the design: if the provider is authoritative, my backend must receive its confirmation and only then mark the order paid, which means a webhook endpoint, a payment status on the order, and an order that can sit in "payment pending". If the browser were authoritative, none of that would exist — and money would be decided by a client I do not control.
- What the decisive form made unnecessary: the pages about card networks, PCI scope, currency handling and dispute flows. They are real; they are not this question. The store got a webhook endpoint and an order status instead of an afternoon of reading.
How you know it worked
What now exists that did not before, and what question you can now ask.
- You can say, before looking anything up, which two or three designs the answer would choose between.
- The question names at least one component of your own system and at least one thing that crosses a boundary.
- The documentation you open is one page, not the table of contents, and you recognise the answer when you see it.
- An AI's answer to the question is short, and you can tell whether it is wrong.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?Which components does this question involve, and what crosses the boundary between them?
- ?What would I build differently depending on the answer — and if nothing, what is the question actually asking?
- ?Which system should be authoritative for the fact I am worried about, and what has to exist in my system for it to be told?
- ?What is the smallest observation — a log line, a test call, a row — that would answer this?
What can go wrong
- Climbing forever. The question is sharpened past the point where an answer exists — "exactly which byte of the webhook body should I trust?" — and the sharpening becomes the procrastination it was meant to replace. Stop at the rung where an answer would decide something and go and get it.
- Sharpening from imagination. The components and boundary are guessed rather than read from the provider's flow, so the decisive question is about a mechanism that does not exist. One test-mode payment with logging on both sides costs less than one wrong assumption.
- Asking the decisive question and accepting an answer to the vague one. The AI or the colleague replies with the overview anyway; you must notice the answer did not decide anything and ask again.
- Treating the decisive form as the only form. The vague question was where the worry lived; the better form is what you research; the best form is what you decide. All three had a job.
- Sharpening takes effort the vague question did not: "payments" was one word to worry about, and its decisive form is a sentence you had to build and an experiment you now have to run.
- A decisive question narrows the reading, which means you learn less of the surrounding territory. On the third payment integration that is a saving; on the first it can hide a neighbouring question (refunds, disputes) you will meet later.
- A question that names components commits you to a picture of the system. If the picture is wrong, the sharp question is sharply wrong — which is at least visible, where the vague one was not.
- "So I should not ask vague questions." You cannot avoid them; they are how not-knowing first shows up. The lesson is that a vague question is the *start* of the work, and the mistake is sending it to a search engine unchanged.
- "The decisive form is always about ownership." Here it was — money needs an authority. For a rendering problem the decisive form might be "which layer should decide the price shown?"; for a queue, "what happens if this message is delivered twice?" The shape is: an answer that chooses between designs.
- "Reading the documentation first would have got me there." Sometimes. But documentation is organised by the provider's system, not by your question, and reading it without a decisive question is how the tutorial's silent decision became yours.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALThe climb — components, boundary, mechanism, scope, decision — applies to any technical unknown; for an algorithmic problem the "components" are inputs and constraints and the "decision" is which pattern applies, and the move is unchanged.
- TEAM-SPECIFICA senior who has integrated this provider before starts at the decisive rung in their head and appears to skip the ladder; a learner on their first integration needs every rung written down, and the written rungs are what they will reuse next time.
- ILLUSTRATIVEThe store, the test dashboard and the afternoon of reading are invented to show the shape of the move; the three-rung payments ladder is the worked example from the domain guide, not a description of any real provider.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto's delegation cards at /manifesto/delegating list what a payment SDK does for you and what stays yours; "who is authoritative for paid" is on the stays-yours side.