Walkthrough

What a SpecTrail flag looks like.

A walkthrough of one change, from the pull request that was merged to the decision a person made, using a shipping rule that moved from $50 to $75.

12 November 2026 · 5 minute read

STEP 1A pull request is merged

The pull request is called “Simplify shipping rules”. It cleans up the shipping calculator and removes a duplicate branch. Its description says nothing about prices. Every check is green and a person has approved it.

Simplify shipping rules

All tests passed
AI code review: no issues found
Approved and mergedMaya R., 2 days ago · 3 files changed

STEP 2SpecTrail compares the meaning

SpecTrail does not compare lines of code. It compares what the product now does with what the specification says it does. The specification has a requirement about free shipping. The code now behaves differently from it.

Specification says

Free shipping applies to orders of ~~$50~~ or more.

Code now does

Free shipping applies to orders of $75 or more.

A rename, a refactor or a faster query would match the specification exactly, and would pass without a word. Only a change to what the product does goes further.

STEP 3The requirement is flagged

In the specification, the requirement turns amber and gains a mark showing that a pull request has changed it. The code and test marks are still there, so the reader can see that the behaviour is built and tested. It is just no longer the behaviour the document describes.

Checkout and payments · Shipping

Free shipping applies to orders of $50 or more.

STEP 4One card has everything

Opening the requirement shows a card with what a person needs in order to decide: the pull request, who made it and when, an assessment of how the behaviour differs, and what is at stake for customers.

Waiting for youR-214

Free shipping applies to orders of $50 or more.

Simplify shipping rules · Maya R. · 2 days ago
The free-shipping threshold in the code went from $50 to $75. The pull request description does not mention prices.
Assessment
The code no longer matches this requirement. Customers with a $50–$74 cart now pay for shipping.

Accept changeEdit wordingDeny

STEP 5A person decides

The person who owns the product has three choices, and each one leaves a record.

Accept the change
The shipping change was intended. The requirement is rewritten to $75, and the history keeps the pull request and the decision.
Edit the wording
Accept the change and say it your way. The history records that the wording was edited.
Deny, with a next step
The code is wrong, so a ticket is opened to fix it. Or it was a false alarm. Or it was intended, and the note says why.

STEP 6The record stays

Whichever way it goes, the requirement’s history now shows the pull request, the assessment, the decision, who made it and when. Months later, anyone who asks why free shipping starts at $75 finds the answer on the requirement itself.

And everything else passes quietly

On the same day, other pull requests were merged. They renamed a helper and sped up a search. Neither changed what the product does, so neither reached a person.

Rename a helper no change

Faster product search no change

Simplify shipping rules waiting for you

That is the point of the flag. A person looks at one card a day and not at every pull request, and the one change that mattered was seen.