Postel's Law for AI-Written Documents

Software that displays AI-written plans should keep the user's content visible when a heading changes or a draft spans several Markdown blocks. Give the producer a clear vocabulary, and make the consumer accommodate reasonable variation. This is a useful application of Postel's Law, the principle stated in RFC 793 in 1981: be conservative in what you do, be liberal in what you accept from others.

I learned how much that tolerance matters while building the daily-plan view in my console. It renders a Markdown file written each morning by an agentic AI assistant. The plan has typed sections: decisions waiting on me, priority tasks, message drafts ready to send. The view recognizes each section and gives it the controls I need: a button for a decision, a checkbox for a task, Copy/Send for a draft. The assistant writes the file. The console reads it. Two pieces of software I wrote, two ends of a wire, both at my desk.

I shipped the cockpit view as a new feature, started using it on my actual plan, and within hours I had filed three same-day bugs against my own work. The decisions section was empty even though my plan opened with a heading called "Open ask" and a paragraph asking for help with something. A morning ritual had created a "Drafts ready to send" section with two drafts in it, and mid-day updates had inserted three more drafts inline next to the situations that prompted them, under a different heading. The view showed the first two and missed the others entirely. About 15% of the section headings in my historical daily plans fell through to a generic "Other" bucket, including section names I actually use day-to-day.

I had mistaken substring matching for tolerance; the parser was strict in a costume. Adding vocabulary helped, but I also needed a shared contract between the instructions producing the plan and the application displaying it.

A document has different needs from an API payload

When I control both sides of a data interface, I usually want a defined schema and validation on both sides. JSON Schema, Protobuf and OpenAPI help make the expected shape explicit. Tests can check that fields survive the trip and that invalid inputs fail visibly. Those are useful disciplines for AI integrations too.

A freely written Markdown plan has a different purpose. Its headings organize a day for a person. "Decisions needed," "Decisions to make" and "Open ask" can all be sensible ways to introduce that day's request. The assistant is working with the plan's content and the user's instructions, so a wording change can be reasonable even when the parser does not recognize it. Hiding that section makes the plan harder to use.

A model can also participate in a constrained data interface. OpenAI's current Structured Outputs documentation describes responses constrained to a supplied supported JSON Schema, with refusals handled separately. It also warns that structured responses can still contain mistakes. Schema adherence concerns the response's shape; the meaning of its values still needs checking. My daily-plan workflow used prose instructions and flexible Markdown, without that schema-constrained response mechanism.

For a document view, I want the canonical form to be easy to produce and the fallback to be useful. A new heading should leave readable content on the screen while giving me evidence that the vocabulary needs attention. That is the purpose of the document-as-contract pattern.

One vocabulary, documented on both sides

The producer's instructions and the console's design documentation carry the same vocabulary table: recognized section types, canonical names and known synonyms. The producer's copy tells the assistant what to write. The consumer's copy tells the parser implementer which forms the interface understands. The documents cross-reference each other.

The producer instructions prefer canonical names and require recognized synonyms when varying them; new section types should be proposed as additions. Those instructions guide the assistant. They do not mechanically constrain every generated heading, so the consumer still needs to handle deviations. The fallback also helps when a person edits the plan directly.

On the consumer side, a recognized heading gets its corresponding section type. An unfamiliar heading returns other and appears as ordinary Markdown in a collapsible at the bottom of the view. The content remains available even when it has no specialized controls.

Keeping both documents current is essential. I treat them as one specification with two locations. Since they live in separate repositories, changing them requires a coordinated change with a commit on each side; an ordinary Git commit records changes in one repository. A useful change record links the two revisions. Before calling the work complete, compare the vocabulary tables, run the consumer against the producer's examples, and check older plans. The documentation and parser must agree about what a newly recognized heading means.

Tolerant parsing in practice

This abbreviated excerpt shows three branches of the classifier and its fallback.

function classifyH2(text: string): SectionKind {
  // Strip noise the LLM might add.
  const t = text
    .replace(/~~/g, "")
    .replace(/[🚨🔥🚀🟡🟢💡📞🤖🧪🆕✅⚠️⛔🎯📋🔧📌]/g, "")
    .trim()
    .toLowerCase();

  // Substring + case-insensitive. First match wins.
  if (/decisions?\s+(?:needed|to\s+make)|open\s+asks?\b|open\s+items?\b/i.test(t)) return "decisions";
  if (/^priority\s+tasks?\b|^today'?s?\s+(?:tasks?|priorit)|^still\s+to\s+do/i.test(t)) return "priority-tasks";
  if (/^drafts?\b|unsent\s*(?:[—-]\s*)?(?:ready|drafts?)|^pending\s+emails?/i.test(t)) return "drafts";
  // ... seven more section kinds, same shape ...

  // Anything else renders as plain markdown.
  return "other";
}

The normalization step removes strikethrough markers and the listed emoji before matching. ## ~~CRITICAL: Old launch issue~~ and ## 🚨 Decisions needed therefore reach their respective branches with those decorations removed. The full classifier's branch for CRITICAL: is among the branches omitted here.

The patterns are case-insensitive, but they differ in where they match. The decisions expression accepts "Decisions needed today" and "Decisions to make this week." The priority expression uses start anchors: "Priority tasks tomorrow" matches, while "Tomorrow priority tasks" does not. Tolerance needs a defined extent; removing every anchor would admit a different set of mistakes.

Each section kind includes recognized synonyms, about twenty additional variants across the full classifier, learned from the real corpus. A new synonym belongs in both the parser and the vocabulary table. First-match behavior also needs attention: "Open ask: drafts ready" matches decisions before the drafts branch is considered.

The other return value is only the classifier's part of the fallback. The application has to render that section visibly. In my plan view, it goes into the lower collapsibles as plain Markdown, so I can still read an unfamiliar section and decide whether it deserves a dedicated treatment.

A draft can span several Markdown blocks

Hours after the vocabulary fix shipped, a different bug surfaced. A draft message body in my plan was wrapped in a triple-backtick code fence, the convention for "this is the message to send verbatim." Inside the message, the assistant had included four code-block examples: curl, npx, git clone and rm -rf install commands, each in its own triple-backtick fence.

A CommonMark closing fence uses the same character as the opener and must be at least as long. A bare internal triple-backtick line can therefore close a triple-backtick outer block. In my draft, the parser saw alternating open and closed blocks. The prose appeared in monospace and the install commands appeared as plain hyperlinked text, exactly inverted.

The console's draft-decoration logic made the result worse. It attached the action bar, with Copy, Edit and Send, to the first parsed fenced block. Copy referred to a fragment of the draft; the rest of the body appeared below the controls, disconnected from the message it belonged to. The heading was canonical. The mistake concerned the body's boundaries.

I changed both sides of that boundary. The producer's draft-format instructions specify a longer outer fence when the message contains internal fences: four backticks around content containing triples. The inner markers remain literal text inside the outer block. They are not nested Markdown blocks at that stage.

The consumer needed a complete draft region. The parser starts after the **Send to:** <recipient> paragraph, allowing an optional Subject paragraph, and continues to the next parsed heading, a **Sent:** ... or **Grounding:** ... paragraph, or the end of the document. It uses Markdown tokens for those boundaries. A heading-shaped line inside a code fence is literal content, not a new section.

The rendered region gets one container and one action bar at its end. A single fenced body keeps its inner content as the editable message. A single blockquote keeps its existing edit-and-save behavior. A body made of introductory prose, a fenced example, more prose and another fenced example becomes one multi-segment draft. Its Copy operation takes the complete body region, retaining the internal triple-backtick syntax for pasting into Slack.

That gave the application a unit of work corresponding to the actual message. The controls no longer had to guess that the first code block represented the whole thing.

A correct Markdown parser can feed an incomplete interface

There was a reasonable argument for fixing only the producer: the Markdown parser followed its specification, so making the outer fence longer would produce the intended HTML. That corrected the particular input. It left the draft-decoration assumption untouched.

The application layer was responsible for selecting the message and attaching its controls. A legitimate draft containing two fenced examples could still be cut into fragments by that layer. A blockquote body or an indented code example could expose another version of the same assumption. Compliance with CommonMark does not establish that Copy refers to the whole message the user sees.

I want regression checks at that application boundary: identify the draft, compare the complete expected text with what Copy returns, and verify that the controls attach once to the whole region. The producer's canonical format helps avoid accidental ambiguity. The consumer's treatment determines whether a reasonable variation remains usable.

Use the historical corpus and targeted examples

My audit script walks plans in the historical archive, classifies their headings and reports the breakdown. In the April 29 work, it reported 94.4% classified into typed kinds and 5.6% falling through to Other, after the earlier roughly 15% fallback. An illustrative report looks like this (the population labels are placeholders):

Plans:   <a year-plus of accumulated files>
Headings: <thousands of total H2 headings>
Classified to typed kinds: 94.4%
Fell through to "other":   5.6%

Top "other" sections:
  Everything Else        (intentional catch-all)
  Background Agent Demo  (intentional catch-all)
  Reading Queue          (consider adding)
  Onboarding Notes       (consider adding)
  ...

The intentional catch-all rows are sections I want in Other. The "consider adding" rows are vocabulary the assistant has been using that the contract could learn. Each is a design decision: extend the contract, or keep the section as a readable catch-all because it does not need specialized controls.

A rising fallback share can reveal vocabulary drift between sessions or model versions. It also tells me where to look. But 94.4% recognition is not 94.4% correct classification. A heading can hit a typed branch for the wrong reason. The displayed regex, for example, classifies "No decisions needed" as decisions. Counting that match as a success would conceal the very mistake a user notices.

Use the corpus audit to discover real variations, then turn useful cases into tests with an intended result. Targeted examples should include canonical headings, synonyms, decorations, deliberate unknowns, ambiguous matches and negative wording. Structural checks should cover a longer closing fence, a shorter non-closing fence, headings inside fences and complete multi-segment drafts. An invented boundary case can reveal a problem before it appears in a historical plan.

The offline companion runs the published classifier excerpt and constructed Markdown examples, with literal expected results. It includes both the anchored priority case and the misleading "No decisions needed" match, so you can see the difference between reproducing code behavior and deciding that the behavior is right. The Markdown checks use a bundled parser and compare complete HTML. They do not exercise the console's action bar or send anything.

Using the console on real plans remains part of the work. The corpus shows what has already happened; targeted tests explore cases I choose; daily use reveals combinations neither covered. When a new combination fails, keep that input as a regression case and repair the layer that lost its meaning.

Keep strict contracts where actions depend on them

This pattern serves human-readable material whose structure is useful but deliberately flexible: plans, meeting notes, design documents and project files. I control the producer instructions and the consumer, and I can compare the rendered result with the source. I want unexpected content to remain visible while the application identifies what it can safely understand.

For a defined data exchange, including schema-constrained model output, use the schema and validate the values. An external API also needs an explicit contract and a deliberate policy for changes that affect its consumers. Owning both sides of my plan view lets me coordinate a vocabulary change; it does not give a third-party API that flexibility.

Security-sensitive and financial actions require strict validation. Even my own assistant can produce wrong content or incorporate untrusted material. Recognizing a Drafts heading is not permission to send a message. Recipient resolution, the exact message body and approval belong to the action boundary. Likewise, displaying an unfamiliar section must not turn text embedded in it into an instruction to execute.

A plan view that quietly omits an ask is worse than one that makes the unfamiliar section conspicuous. Vocabulary was the first problem I encountered; body structure followed hours later. Markdown in table cells, blockquotes inside fenced blocks and embedded HTML are further cases I would check, each at the layer that interprets it. My standard is that the user can still find the content, understand how the application treated it, and act on the complete intended unit. Keeping the producer's guidance, the consumer's behavior and the tests in step is how I maintain that standard.