Surface Format Matches Audience

The comment that made no sense read aloud

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

That is the tell. If the person who wrote a sentence cannot parse it back cold, nobody else stood a chance. The comment was not wrong. It was aimed at the wrong reader. I had written an agent-facing status update into a human-facing field, and every reviewer after me paid the decoding tax I’d just paid myself.

Two readers, one habit of blending them

Every note I write has a primary reader, and it is always one of two kinds: a person skimming for status, or an agent (often a future instance of me, or a future instance of the tool) picking up the thread later and needing exact state. The mistake was writing as if those two readers 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, not just nod at it.

Once I saw the ticket comment for what it was, I started noticing the pattern 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. Every one of them was a surface built for a human reader that had quietly filled up with agent-shaped debris, because writing both at once felt efficient in the moment.

It isn’t efficient. It’s a tax paid twice: once by the human who has to mentally strip the jargon, and once by the agent later, because the exact values got compressed into prose and lost precision on the way in.

The fix was a sorting rule, not a style rule

The fix wasn’t “write better.” It was picking, before typing a word, which reader owns this surface, and never blending 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 I now run three checks before I 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’s never touched this project follow it. “Dry-run”, “spend gate”, “utf-8 stdout” all fail that one, no matter how normal they sound to me. And count what each word is doing. If a twenty-five word sentence only needs twelve of those words to say the same thing, I ship the twelve.

Run the ticket comment back 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 rest of it goes

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

I know the split is holding when a mixed surface starts feeling wrong on sight, the way the original comment did when I reread it. If I catch myself reaching for a flag name or a version number in a status line, that’s the signal I’m writing for both readers and serving neither. Pick one, write for that one, and let the other surface carry what it needs.

The comment that started this wasn’t a disaster. Nobody got paged over it. It just cost every reader, including me, a few extra seconds of translation they shouldn’t have had to spend. Multiply that across a year of tickets and logs, and a few seconds a comment adds up to a habit worth breaking.

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/2026-08-04_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.