← Blog

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?

The same rule, read two ways One rule nobody had agreed to: the same run, logged twice, is counted once. Read as code, in the docs and the pipeline, I skimmed past it. Read as a sentence in the blog post, it said 539 activities were not counted, which raised the question of who decided that. The race directors decided to count every logged activity; 23 of about 1,650 runners changed, by about 3,000 miles. One rule nobody had agreed to The same run, logged twice, is counted once Read as code In the docs and pipeline I skimmed past it Read as a sentence 539 activities not counted “Who decided that?” Decided: count every logged activity 23 of about 1,650 runners changed, by about 3,000 miles
The rule was written down all along. As a plain sentence with a number, it raised the question.

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.