Fourth post of Season 1. Last time, I told you about the discount code that quietly changed behavior two weeks after I shipped it, because the "don't stack with sale prices" rule only ever lived in my head. This is what happened when I actually wrote it down.
Writing Down What Should Have Been Written Down
After I found that four-cent discrepancy, the first thing I did wasn’t fix the rounding. It was open a file called BUILD-NOTES.md in the project and write down what I could still remember about a decision I’d made two weeks earlier, mostly from memory, filling in what I could and leaving a couple of lines honestly blank.
It looked like this:
## What's included
- Discount codes, percentage-based
- Codes do NOT stack with items already on sale
## Edge cases we've already decided
- If a code is applied to a sale item, the code is rejected with a message, not silently ignored
- Rounding: round down to the nearest cent, always, on any final price
## Still undecided
- What happens if a customer has two valid codes at once (hasn't come up yet)That took about four minutes. Slower than answering the agent’s questions in the moment had been, two weeks earlier. Also considerably faster than the twenty minutes I’d spent staring at an order total trying to reverse-engineer a decision that should have taken four minutes to write down the first time.
The Third Ask
A week later, the same client asked for one more thing: a minimum order amount before any code could be applied, so a five-dollar code couldn’t be used on a two-dollar item.
This time, before typing the request straight in, I pointed the agent at the file first. My prompt was short: here’s what we’ve already decided about how discounts work, read BUILD-NOTES.md before you touch anything, and update it if anything here changes.
It read the file. It didn’t ask me whether codes should stack with sale prices, because that was already answered. It didn’t invent a new rounding approach, because one was already written down and it used it without me having to repeat myself. What it did ask about was the actual new question, the minimum order amount, specifically whether that minimum should be checked before or after the discount was applied. That was a real gap, correctly flagged, and one I hadn’t thought to specify either. I answered it, and the agent added the answer to the file under “Edge cases we’ve already decided” without being told to.
What Changed
A few days after that, I asked the agent the same kind of question I’d asked back in the very first piece in this season: why does it work this way. This time the answer didn’t come from a confident guess reconstructed on the spot. It came from the file, word for word, the same decision I’d written down myself, because that’s what it had actually been told to treat as true.
That’s the whole difference. Not that the agent got smarter. Not that I got more careful. Just that the decision existed somewhere outside a conversation that was going to scroll away, and the next prompt could read it instead of reinventing it.
Try this on something you already shipped without notes. Write down what you can still remember about it, right now, before you forget the rest. What comes back to you when you actually sit down to write it?
Hundred percent. I regularly do the same: have the agent summarize the juicy bits of our ongling conversation and place it into a markdown file (usually my spec file). The agents forget but so do I!