Two readers, one status field, and a decoding tax

The comment I couldn’t parse

We were scanning a ticket we’d worked days earlier when we hit our own comment: “Starting Phase 1 (scaffold + dry-run on 1 thread per provider). Spend gate holds for the full run.” We wrote that. We remembered writing it. And we still had to stop and decode it like it belonged to someone else.

If the person who wrote a sentence can’t parse it back cold, nobody else stood a chance. The comment was aimed at the wrong reader. We had put an agent-facing status update into a human-facing field, and every reviewer after us paid the decoding tax we’d just paid ourselves.

Two readers, blended

Every note we write has a primary reader, and it is one of two kinds: a person skimming for status, or an agent (often a later session of ours, or a future instance of the tool) picking up the thread and needing exact state. We had been writing as if those two wanted the same thing. They don’t.

A person wants three seconds and a plain sentence. An agent wants the flag, the number, the file, the exact value, because it is going to act on that value.

Once we saw the ticket comment for what it was, the pattern turned up everywhere. Work log entries with parenthetical flags. Handoff notes with commit hashes buried in prose. Dashboard summaries listing file paths nobody scanning a dashboard was going to open. Each was a surface built for a human reader that had filled up with agent-shaped debris, because writing both at once felt efficient in the moment.

It wasn’t. The human had to mentally strip the jargon, and the agent later got values that had been compressed into prose and lost precision on the way in. We paid twice.

A sorting rule

Writing better was not the fix. The fix was to decide, before typing a word, which reader owns the surface, and never blend the two again. Human-primary surfaces are the ones anybody reads to get oriented fast: reviewer comments, status updates, work logs, commit messages, the reply text in a chat window. Agent-primary surfaces are the ones a script or a future session actually parses: memory files, technical dev notes, session manifests, reference docs, frontmatter that gets read by code.

For human-primary text we now run three checks before we hit send:

• Read it aloud, or imagine a phone voice reading it. If a version string or a comparison operator like <= shows up in that reading, it fails.
• Would a smart teenager who has never touched this project follow it? “Dry-run”, “spend gate” and “utf-8 stdout” all fail, no matter how normal they sound to us.
• Count what each word is doing. If a twenty-five word sentence needs only twelve of those words to say the same thing, we ship the twelve.

Run the ticket comment through that filter and it becomes: “Started a small test run to confirm everything works before paying for the full corpus.” Same event. Same facts. Readable in one pass, no lookup required.

Where the technical detail goes

The dry-run flag, the thread count, the dollar cap, the exact mechanism: none of it disappears. It moves to the surface built for it. On tickets the record is now split. The human-facing comment thread stays short and readable, while a separate technical field carries the mechanism, the file paths, the commit hashes and the precise numbers. One event, two records, each shaped for the reader who needs it.

We can tell the split is holding when a mixed surface starts to feel wrong on sight, the way the original comment did when we reread it. If we catch ourselves reaching for a flag name or a version number in a status line, we’re writing for both readers and serving neither.

Nobody got paged over the comment that started this. It cost every reader, us included, a few extra seconds of translation they shouldn’t have had to spend. Across a year of tickets and logs, those seconds add up to a habit worth breaking.

So decide who the primary reader of each status field is, a person skimming or an agent that will act on exact values, and keep the two kinds of content on separate surfaces. Exact values belong where an agent will read them, not compressed into prose.

dxdev LESSON · paste into your AI coding agent
LESSON: If you cannot parse your own status comment cold days later, every reader after you is paying the same decoding tax
SOURCE: dxdev.com/blog/surface-format-matches-audience
WHAT HAPPENED: A ticket comment written in the moment, mixing plain narration with an exact spend cap and a comparison operator, could not be parsed back cold by the same person who wrote it days later. That was the tell: an agent-facing status update had been written into a human-facing field, and every reviewer after it paid the same decoding tax. The fix was a sorting rule applied before writing anything: decide which of two readers, a person skimming for status or an agent that will act on exact values, owns a given surface, and never blend the two. Human-primary text now has to pass three checks: read aloud without a version string or comparison operator surviving, followable by someone unfamiliar with the project, and every word earning its place. The exact values, flags, counts, dollar caps, do not disappear; they move to a separate field built for the reader that actually needs them.
THE RULE: Writing one note to serve both a human skimming for status and an agent that will act on exact values serves neither; decide which reader owns a surface before writing a word, and if you cannot parse your own writing back cold, nobody else stood a chance.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Any status update, comment, or log entry mixing plain-language summary with exact technical values, such as flags, version strings, or comparison operators, in a sentence meant for quick human scanning.
      2. Any surface with no clear single primary reader, human-skimming versus agent-parsing, where the two kinds of content get blended out of habit.
      3. Rereading your own recent writing and needing to stop and decode it, which is a direct signal that every other reader is paying the same tax.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.