I Couldn't Read My Own Note Three Days Later

The note I wrote and couldn’t read

I was scanning through work I’d done a few days earlier when I hit a comment I’d left myself. I remembered writing it. I still had to stop, slow down, and decode it like it belonged to someone else.

That’s the tell. If the person who wrote a sentence can’t parse it back cold, nobody reading it after them stood a chance.

Two different readers, one habit of mixing them

Every note I write has one real reader in mind, and it’s always one of two kinds. Either a person skimming for a quick sense of where things stand, or a system that’s going to act on the exact details later and needs the precise value, not a paraphrase of it. The mistake was writing as if both readers wanted the same thing. A person wants three seconds and a plain sentence. A system wants the exact number, because it’s going to use that number, not just nod along at it.

Once I noticed it in that one comment, I started seeing the same habit everywhere. Notes that were supposed to be a quick status update, quietly filled with the kind of precise detail only a system would ever need to act on. Every one of them was a surface meant for a fast human read that had slowly filled up with the wrong kind of content, because writing both at once had felt efficient at the time.

It wasn’t efficient. It cost twice: once for the person who had to mentally strip out the technical detail to get the gist, and again later, because folding the exact values into plain prose is how they get lost or garbled on the way in.

What changed

The fix wasn’t “write more clearly.” It was picking, before typing anything, who actually owns that particular surface, and keeping the two kinds of writing apart from then on. A status update that a person will skim gets written so a person unfamiliar with the details could still follow it in one read, no lookups needed. Anything a system needs to act on precisely, an exact number, a specific setting, a precise comparison, goes somewhere built for that instead.

The exact detail never disappears. It just moves to the place built for the reader who actually needs it, instead of getting stuffed into the note meant for someone glancing past it in three seconds.

What a person still has to decide

Nobody automated the judgment call here. A person still decides which surface is for skimming and which is for exact values, and that decision has to happen before anything gets written, not after something turns out unreadable. What can be automated is catching the mixed cases and cleaning them up once the two kinds are told apart. Deciding where that line goes stays a human call, every time.

The rule worth keeping

Before you write a status note, decide who it’s actually for: someone skimming for a quick answer, or something that’s going to act precisely on what you wrote. If you can’t tell which, or you’re trying to serve both, that note will end up unreadable to someone eventually, possibly you. Read your own writing back cold a few days later. If you have to stop and decode it, so will everyone after you.

dxdev LESSON · paste into your AI coding agent
LESSON: If You Can't Parse Your Own Note Back Cold, Nobody Else Stood A Chance
SOURCE: dxdev.com/blog/2026-08-04_i-couldnt-read-my-own-note-days-later
WHAT HAPPENED: A status comment written days earlier, mixing a plain narration with an exact technical value and a comparison symbol, could not be parsed back cold by the same person who'd written it. That was the tell: the note had been written for two different readers at once, a person skimming for status and a system that needed exact values, and it served neither well. The fix was deciding, before writing anything, which reader actually owns a given surface, and never blending the two again. The exact values didn't disappear. They moved to a separate place built for the reader that actually needed them.
THE RULE: A note written for both a person skimming for status and a system that needs exact values ends up serving neither. Decide who the surface is for before you write a word, and if you can't read your own writing back cold later, nobody else stood a chance either.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
  1. Any status note, comment, or log entry mixing a plain summary with exact technical values in a sentence meant for a quick human read.
  2. Any shared surface with no clear primary reader, where technical and plain-language content get blended out of habit.
  3. Rereading your own recent writing and needing to stop and decode it, which means everyone else reading it pays the same cost.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.