Write it down, read it back
A rule in our race software that nobody had agreed to, and how a blog post about the software is what brought it to light.
- Written by
- Naresh Kumar
- Published
- Reading time
- 3 min
- Topic
- Tech & AI
I recently wrote a long post about rebuilding the GVRAT websites. While reading the draft, I stopped at one sentence:
The same activity is counted once, even when it was logged on two registrations of the same region.
I didn’t know we did that.
The gap
GVRAT runners log their miles on RunSignup, and the same stretch of the Transcon can be covered by two registrations. Region 2, for example, was both GVRAT 2025 and Transcon Region 2. A few runners logged the same run on both.
Our old system counted both copies. The new one counted the run once. Nothing was broken: every test passed and the totals added up. The code was doing exactly what its rules said.
The problem was the rule itself. Early in the build, a note said to “decide a rule” for these copies. One was picked while the pipeline was being written, and it went into the docs as though it were settled. Steve and I, the race directors, were never asked about it.
Why the blog post caught it
The rule was already written down, in the project’s docs and in the code. But it was written for the software, so I skimmed past it.
The blog post was written for people. It put the rule in one plain sentence with a number next to it: 539 activities not counted. Read that way, the question was obvious: who decided that?
What we decided
Our race rule is simple: we count what runners log. RunSignup lets them log in more than one place, and if they do, that’s on them. So we changed the software to count every logged activity, the way the old system did.
Before pushing, we compared the results before and after on the same data. Exactly 23 of about 1,650 runners changed, by about 3,000 miles in all. One of them completed a region. Nobody gained or lost finisher status. The decision is now in the docs, with the date and who made it.
The lesson
Writing a spec and reading it back are two different steps, and the second one is the one that finds things.
- Write rules in plain language, the way you’d explain them to the people they affect, not only as code comments or config.
- Put a number next to each rule. “Counts once” sounds harmless. “539 activities not counted” makes you ask why.
- Read it as an outsider. Every rule should have an answer to “who agreed to this?” If it doesn’t, it isn’t a rule yet, just a guess.
- Watch for “to be decided”. Placeholders tend to get filled quietly by whoever writes the code next, whether that’s a person or an AI agent.
I build with an AI coding agent, and it moves fast. This is the kind of gap it can create without anyone noticing: a sensible default that quietly turns into policy. Writing for real readers, and reading it back slowly, is still the best check I’ve found.