Skip to content
arula

Take a change an AI wrote, check what could be wrong, and explain what you would approve, send back, or ask an owner to decide.

Chapter 05 / 07

Explain the fee defect

Connect the reproduced fee failure to its requirement, account impact, and the decision the product owner needs to make.

What you should leave with
Shared intuition
a defect report connects a failure to a requirement and a consequence someone can understand.
Shared language
observed describes what happened; expected names the required behavior; impact explains who receives the wrong amount.
Shared behavior
attach a reproduction, identify what remains unknown, and ask for a specific decision. Now let's put those exact facts into Define.
Step 1 of 4

Establish the failure

We have a passing Task 1 Eval and a separately reproduced fee failure.
Let’s take that fee failure into a report a product manager can act on.
We’ll use one defect throughout: “Capture fee truncates instead of rounding half up.”

The request was to add refund retries.
The fee failure happens during capture, before any refund is attempted.
That matters when we describe the problem: a merchant can encounter this calculation without using the new retry helper.

Do: Open fixture test/service.test.ts, lines 107–115. Point to the capture at line 111 and the assertion at line 112. Open the captured run in docs/assets/lab-3-define/risk-02-output.txt, lines 13–28.

The test captures 200 minor units and checks the fee recorded in the ledger.
It expects three and gets two.
That’s the failure we reproduced.
The test stops at this assertion, so this run doesn’t reach the merchant assertion or the second capture case.

A failed test gives us a disagreement to explain.
We still need to establish why the expected value is correct.

Do: Open fixture specs/tech/payments.md, lines 42–43, and specs/tests/payments.md, line 54.

The tech spec requires half-up rounding and explicitly rules out truncation.
The test spec applies that rule to this capture: fee three, merchant amount 197.
So the test’s expectation has a requirement behind it.
We don’t need the product manager to choose a rounding rule.

Step 2 of 4

Follow the money

Do: Show fixture src/payments/service.ts, line 43 and lines 118–139. Follow the fee calculation at line 119 into the subtraction at line 120, then the merchant and fee postings at lines 126–139.

Keep all the amounts in minor units, as the test does.
The capture is 200 and the fee rate is 1.49 percent.
Multiplying those gives 2.98.
The required rounding gives three; Math.floor discards the fraction and gives two.

The service subtracts the fee from the capture to calculate the merchant amount.
With a fee of two, that leaves 198.
With the required fee of three, it should leave 197.
The ledger therefore assigns one minor unit too little to the fee account and one too much to the merchant.
Both splits total 200, so a check of the total alone would miss this error.

Step 3 of 4

Explain observed and expected

That gives us the opening of our report.
For Observed, we’ll write:

Capturing 200 minor units records a scheme fee of 2 and a merchant amount of 198. The RISK-02 fee assertion fails: actual 2, expected 3.

Then Expected explains the rule and the required amounts:

TR4 requires half-up rounding. For a capture of 200 minor units, record a fee of 3 and a merchant amount of 197.

Those sentences give the reader something concrete to compare.
The first reports the behavior we checked; the second gives its required replacement.
The merchant amount follows from the calculation and posting we just read, rather than from an assertion that never ran.

Step 4 of 4

Ask for the right decision

Now explain why someone should care.
Write that the fee account receives too little and the merchant account too much.
The one-unit example demonstrates the wrong allocation.
To understand its wider impact, we would need to find which deployed versions contain this calculation and how many payments it affects.
We haven’t established either fact in this fixture.

Do: Show fixture specs/product/payments.md, line 3, naming payments-product. Keep the reproduction output beside the report wording.

Our request to that owner will be:

Set repair priority and agree whether to investigate deployed versions and affected payments. Production exposure and frequency are unknown.

The engineering repair can follow the existing rounding requirement.
The product decision concerns urgency and the scope of follow-up.
Keep those separate so the report asks for a decision the reader actually needs to make.

We also have to make the failure repeatable.
We’ll include the exact fee-test command, its failure output, and the environment that produced it.
That evidence came from our separate RISK-02 check.
Task 1’s passing RETRY-01 result doesn’t supply it.

Shared intuition: a defect report connects a failure to a requirement and a consequence someone can understand.
Shared language: observed describes what happened; expected names the required behavior; impact explains who receives the wrong amount.
Shared behavior: attach a reproduction, identify what remains unknown, and ask for a specific decision.
Now let’s put those exact facts into Define.

Carry forward

Keep observed behavior, required behavior, impact, and unknown exposure separate. Bring those facts into the Define draft.

Help me reason through this

Both account splits still total 200. The error is the allocation: one minor unit too little for fees and one too much for the merchant.

Your explanation is saved in this browser.