Chapter 01 / 07
The payments change
Understand the support request, the four-file change, and who owns the requirements.
What you should leave with
- Shared intuition
- Tools help us inspect a change, but their claims still need checking.
- Shared language
- The product spec says what must happen; the tech spec says how. Each names its owner.
- Shared behavior
- Check the change, retain evidence, and ask the owner to decide what the requirements leave open.
Why judgment matters
Original classroom timing
| Minutes | What happens |
|---|---|
| 0–2½ | Welcome, the problem, and how the afternoon works |
| 2½–3½ | The business background and the change |
| 3½–7 | Walk through the four files together |
| 7–8 | Where the specs are, then bridge to Diagnose |
Original classroom introduction
Hi, I’m [name].
[Coach names] are here to help you through the afternoon.
Quick show of hands.
Who’s reviewed a pull request in the last month that was mostly written by an AI?
Keep your hand up if you read every line.
Yeah.
Me neither.
That’s why we’re here.
The agents write code faster than we can read it.
If our plan is to read harder, we lose.
So today you’ll use tools that do a lot of the reading for you.
But tools get things wrong.
They flag things that are fine.
They miss things.
And some decisions aren’t theirs to make.
If nobody has written down how something should work, a tool can’t decide that for you.
Neither can you.
You find the person who owns that decision, and you ask them.
By the end of today, you’ll be able to take a change an AI wrote and work out what could
be wrong.
You’ll check it with the tools.
Then you’ll say what you’d approve, what you’d send back, and who has to decide the
rest.
Original classroom introduction
Here’s how the afternoon works.
It’s just under three hours, with a break at about the seventy-minute mark.
You’ll sit in pods of four and work in pairs.
Swap who’s typing after every step.
If you get stuck, ask your partner, then your pod, then grab a coach.
At the end, you’ll do one round on your own.
That’s how you and I will both know it stuck.
The business request
Some background first.
This is a card payments service.
A merchant reserves money on a customer’s card, then takes the money later.
When goods come back, the merchant refunds the customer.
Every refund is tied to the payment it came from.
Here’s the change.
Sometimes a merchant calls support and says, “I issued a refund, but the money hasn’t
reached my customer’s account.”
The agent was asked to give support a way to send that refund again.
If sending fails, it tries again, up to three times in total.
Why should you care about this one?
It’s payments code.
It moves real money, and it handles card numbers.
A mistake here costs someone money, or leaks card data.
Let’s look at what the agent produced.
Inspect the four files
Walkthrough notes
Show the agent’s commit; participants run these commands on their machines.
git show --stat 965029f
git show 965029fWalkthrough notes
The first command lists the four files; the second shows their changes.
Use this commit for the opening.
The whole branch diff also includes course configuration, docs, specs, and test renames.
Four files.
Let’s go through them.
retry.ts is new.
It’s the retry itself.
It sends the refund, and if that fails, it tries again, up to three times.
service.ts is the main payments service.
The agent changed two lines here.
One is in how a failed card check gets logged.
The other is in how the fee is worked out.
cards.ts is test data.
The agent added one card number for testing.
refund-retry.test.ts is the new test.
Its comment says it confirms that a retried refund is accepted.
Walkthrough notes
Scroll through the fixture files in that order: src/payments/retry.ts, lines 10–28;
src/payments/service.ts, lines 62–68 and 118–120;
test/fixtures/cards.ts, lines 18–19;
test/refund-retry.test.ts, lines 6–16.
Find the requirements
You also have what the agent was working from.
The product spec says what the payments service must do.
The tech spec says how.
Both are in the specs folder.
Each one names the team that owns it.
That’s who you’d ask.
So that’s the change.
Before anyone decides whether it’s good, let’s see what the tools point at.
Walkthrough notes
Leave both fixture paths visible: specs/product/payments.md, line 3, names
payments-product;
specs/tech/payments.md, line 3, names payments-engineering.
Preparation and evidence notes
Presenter notes: Keep the approved opening descriptive.
If someone asks whether something is a bug, say, “Hold that thought.
We’ll check it.”
Name where logging and fees changed without deciding either claim.
The old presenter note claimed an unredacted log; the current serializer redacts its
context.
That correction is supported by fixture src/obs/index.ts, lines 49–64.
The retry test never calls the helper; save that explanation for the later checks.
Hold the test spec until Eval; its RETRY-01 row characterizes behavior without approving
a refund policy.
That row is in fixture specs/tests/payments.md, lines 88–92.
Say “AI coding agent”: the agent wrote the code, and the code itself has no AI in it.
Carry forward
We know what the agent was asked to do. Next, inspect what Diagnose notices without deciding whether it is a defect.
Help me reason through this
Separate the refund request from the logging and fee changes. The product and tech specs name their owners.
Your explanation is saved in this browser.