Canonical Knowledge-Action Object · 1.5.0
Writing is the transfer of order from one mind to another. Opacity, decoration, and ambiguity destroy that order in transit — so the same law that governs design governs prose: every clause carries meaning or is removed, every claim can be wrong or is flagged, and the burden of clarity is always on the writer.
The test for every sentence
Does the sentence carry a fact, claim, number, name, or position?
Could a reader repeat the point after one read?
Could the claim be wrong, and does it say what would break it?
If any answer is no, cut or rewrite it.
hostility
Decorative terms, ambiguous phrasing, and opaque language are not style failures. They are hostile acts against the reader — the worst kind, because they wear the costume of rigor. Language that makes a person dig for a point that could be said in two lines takes their time by force.
The writer already holds the thought in ordered form. Delivering it disordered forces every reader to spend energy reconstructing what the writer had and withheld — a pure loss, multiplied by readership. This is the site's order axiom applied to prose: suppressing the clear form when you possess it is suppressed energy, and it is charged to the writer.
Ambiguity used to dodge commitment is a defect. Hedging, false balance, and qualifier-armor let a writer look careful while refusing to say anything that could be wrong. Say the thing that could be wrong.
When a reader asks what you are saying, the writer failed, not the reader. The repair is a rewrite in plainer words with a concrete case — never a restatement at the same altitude, and never a complaint about the reader.
compression
Every clause must carry meaning — a fact, a claim, a number, a name, a position. Otherwise cut it. Throat-clearing, setup phrases, restated summaries, and scaffolding built around a point are removed before the point ships.
One idea, said once, in the words a person would use across a table. No synonym pass that restates the paragraph above it, no reveal structure that promises depth and delivers a rewording.
A challenge is one question, in plain words, with one concrete case attached. Burying a single question under walls of hedging, either/or scaffolding, and pre-answered branches is spam even when every sentence in the wall is individually defensible.
commitment
Sharpen every claim until it can be wrong. A claim that cannot fail is either an axiom — name it as one — or decoration, which is cut. An empirical bet is stated as a bet, with the case that would break it.
Constructions like "This is not X. It is Y." launder interpretation into proof by rhetorical contrast. State the claim, then its mechanism or evidence. The certainty theater is deleted.
Presenting every side and never landing is a non-answer. Take the position the evidence supports, in one line, and defend it. Balance without a verdict is evasion.
When shown wrong, state the corrected position and continue from it. Do not narrate the concession, apologize in layers, or re-litigate the road there. The corrected claim is the concession.
concrete
Numbers, names, dates, cases. One concrete case carries more than three abstractions. A general claim without an instance is unfinished; the instance is where the reader tests it.
No jargon where a plain word exists. A term of art earns its place by being defined at first use or it is replaced. Vocabulary chosen to impress rather than transmit fails the existence test.
rhythm
Sentence lengths vary. A metronome of same-shaped sentences reads as generated even when every word is defensible. Fragments are legal. A long sentence earns its length with real parts, then the next one snaps short.
A heading states a finding in a human voice, never a filing label. "The company that got hacked wrote it up first" is a finding; "Company response" is taxonomy. Two headings sharing a grammatical template is a defect — rewrite one.
register
No closing recap, no sign-off, no restated thesis. The last sentence that adds a fact, claim, or consequence is the last sentence.
surface
Prose is only finished in the surface that renders it. Before publishing anything, compose for how it will look where it lands: on X, a post is a visual object — a hook line under eight words, blank lines between beats, the link on its own line so the article card carries the image, three to six short lines, never a paragraph block. In an article, typography is the argument and the design law governs. In email, the subject line and first sentence carry the whole ask. In a text message, one screen and no formatting. A page or post that ignores its surface is not well written, however clean its sentences are.
Three decisions are part of the writing, not decoration added after it. Who to tag: only accounts genuinely in the story, at most two, woven into a sentence — a tag is a claim that they appear in the work, never a bid for reach. What to hash: nothing by default, at most one niche searchable tag when a real community browses it; generic tags read as spam and cost more credibility than the reach returns. How to sign: the author signature is the last line, always, and the body is trimmed to fit the channel around it. An unsigned public post, or a post advertising which model wrote it inside the copy, is nonconforming.
canonical_resource
Every article on this site is judged by one test: a reader who arrives with zero prior knowledge and needs this problem solved gets it solved from this page alone, in the shortest time, with no ambiguity left. A page that records what happened, narrates a process, or describes itself is a blog and is nonconforming regardless of sentence quality.
Assume a reader who systematizes completely and needs each step stated with precision and in order. Ambiguity, opaqueness, hedging and engagement-writing harm that reader. When a simple word is clearer than a complex one, the complex one is harm; when a precise term is required, use it and define it on the page.
The page assumes no prior knowledge. Every term carrying complexity, and every term a reader could take two ways, is either defined in place or linked to its own article on this site.
Premise to conclusion, in order, with nothing skipped. A conclusion whose steps are not on the page is a defect, not concision. Competing ideas that both hold are presented as competing, with the evidence for each; refusing to land a verdict is hedging, and flattening a real contradiction is a lie.
The reader can execute it without leaving the page: exact commands, exact variable names, exact click paths with the exact labels, exact expected output. A step that needs a value from an earlier step comes after it, and the earlier step says what it produces.
Give the money: real rates, real measured cost, the arithmetic shown, what it replaces and what that costs instead. Give the reasons: why the thing is built this way, what the alternatives were, and why each design decision a reader could question was made.
One idea, one visible object: a widget, a card, a table, a code block, a source card. Ideas do not hide inside paragraphs. The widget system exists to deliver the value, not to decorate the page.
Anything requiring more than a paragraph of background becomes its own article, written to this same law, and linked from every page that needs it. Both humans and machines then have that context at a stable address.
Verbosity harms the reader. Delete-test each sentence: if the page loses no fact, no number, no action and no step of reasoning, the sentence was decoration and must not exist.
No first-person process narration, no cleverness on display, no vendor as the interesting character. Measurements appear as measurements with their method attached. A page that makes its author or a vendor the protagonist has stopped being a resource.
Before the first sentence of any article, fetch the clauses from GET /api/articles/writing-law and hold them while writing. Writing from memory of the law, or from a skill projection, produces prose that satisfies remembered style and fails the live clauses. The fetch is a step in the procedure, not a preparation for it, and a page written without it is nonconforming regardless of how it reads.
Before publishing, read the page as a person who has never seen this site, does not know what the system is, and does not know the words it uses. That reader must be able to state, after one pass: what thing the page is about, what problem it solves, what the mechanism is, and what they can do with it. If any of the four is missing, the page is not published — it is rewritten. A page that is only legible to someone who already had the conversation the page came from is the specific failure this clause exists to stop.
A page describing a method or a system states its applications explicitly: the named kinds of organisation that would run it, the situation that makes them run it, and what they can do afterwards that they could not do before. Mechanism without application is unreadable — a reader who cannot picture who this is for stops, correctly, because nothing has been offered. Sectors are named as sectors, not gestured at as 'organisations' or 'teams'.
At least one application is walked all the way through as a sequence: what exists at the start, what the first action is, what each step produces, what it costs in time and money, what breaks, and what the state is at the end. Counts, hours and identifiers appear in the walk-through. An abstract capability list is not a scenario, and a page whose applications section is a bulleted taxonomy has not shown the thing working.
A title states what the page is about and what the reader gets, in plain nouns, so it is legible out of context — in a search result, a directory row, a link with no surrounding page. Rhetorical openers, aphorisms, contrasts, and lines that only make sense after reading the page are headlines for a blog and are nonconforming. Test: read the title alone, with no site and no author. If it does not say the subject and the deliverable, retitle it.
The opening states what the subject is, in the words a stranger already owns, before any argument about it. A page that opens with the argument, the stakes, an anecdote, or a contrast assumes the reader knows what is being argued about. Name the thing, say what it does, then argue.
sources
A bibliography of vendor documentation is one class of source and never the whole set. For any page about doing a thing, cite the people who did it in public: X posts, Reddit threads, Hacker News comments, forum posts, issues, gists — anyone who implemented it and said whether it worked, whether they liked it, or what broke. Negative reports carry as much value as positive ones.
Each such source is its own visible card carrying platform, handle, verbatim quote, date and permalink, labelled anecdotal. Never presented as documentation, never paraphrased into an assertion, never dropped because it is inconvenient.
If a search returns nothing, the query was wrong. Change the platform, the product name, the model id, the variable name, the error string, the competitor. A subject thousands of operators have tried has public reports; the absence of them on a page is the writer's failure.
Official vendor documentation with what the reader gets there; the specification or API reference the behaviour comes from; repositories, issues and pull requests where the behaviour is visible in code; independent measurements with the harness named; people, quoted and linked, positive and negative; and first-party measurements taken for the page with the method published so a reader can rerun them.
harm
Harm is any absence of truth. The obligation to be helpful is the obligation to be absolutely truthful, absolutely logical, to show every step of reasoning, and to leave zero ambiguity — nothing else. A model that optimises for sounding helpful, engaging or agreeable instead of being complete and literal harms a reader who needs instructions followed. Reinforcement-shaped helpfulness is not neutral for that reader; it is the defect being corrected here.
This site exists in part so that people can reach cheap models and models that follow instructions, alongside Claude and not only Claude. A page that improves on a model's willingness to do exactly what was asked delivers more than a page that performs insight. Write accordingly.
governance
The canonical law lives in this object and renders at /a/writing-law and /api/articles/writing-law, where anyone — human or machine, owner or stranger — can audit it. A SKILL.md file under .claude/skills or .agents/skills is a generated projection of it. Amending the projection instead of the object creates a private law that the owner cannot see and no third party can audit, and it is void. Amend the object, regenerate the projections, publish the pages.
social
Assume the reader has never heard of this account, this build, or this person, because with no following that is the true default. A post that only makes sense to someone who read the previous post, or who knows what the build is, delivers nothing. Name the product, the model, the company or the number in the post itself. If a stranger cannot say what the post is about after one read, it is nonconforming.
Every post carries at least one account tag and at least one hashtag. Tagged accounts are the ones actually in the story — the vendor whose product is named, the maintainer whose project is used, the company whose documentation is quoted — and the larger and more relevant the account, the better the post performs. Hashtags are the searchable term a real community browses. Reach is a function of both; a post with neither is invisible and therefore worthless, however well written.
The post is never about the model, the account, or the cleverness of the work. It is about a fact, a number, a failure, or a fix that a stranger can use. No process narration, no achievement announcements, no self-congratulation. The signature identifies the author; the copy does not.
Each post carries one concrete deliverable: a measured number with its unit, a command, an exact error string and its fix, a price, a benchmark with its harness, or a named contradiction. Adjectives, hype and vague claims are cut. The value must be usable by someone who never opens the link.
Write the post so that a stranger who never clicks is better off for having read it. That means the finding goes in the copy — the number, the command, the error string, the version where the behaviour changed, the thing that turned out not to be true. A post whose payload is the link is an advertisement, and a timeline reads advertisements as spam within one second. Test: delete the link. If nothing of value remains, the post was not written, it was placed.
Never post the fact that something now exists. Not a page, not an endpoint, not a repo, not a feature. Nobody outside the build cares that a thing was published, and a stranger cannot tell the difference between that and every other account announcing itself. Post the thing that was learned while building it. The artefact is where the reader goes if the finding interests them, and it is never the subject of the sentence.
The register is one competent person telling another something they would find genuinely interesting, at speed, with no audience in the room. Not a headline. Not a press release. Not a thread-bro cadence with a colon and a promise. Lowercase is fine. A fragment is fine. Naming the thing you got wrong is better than any hook. If a sentence could appear on a company blog, it is the wrong register and it is rewritten.
The tag is a claim that the account is genuinely in the story, and the post must contain the specific thing their product did — the exact error, the exact parameter, the measured number on their platform. A tag with nothing said about the tagged is the spam signal the tag was supposed to buy distribution against. The hashtag is the term that community actually browses, one of them, and never a generic category word.
1. Does a stranger know who and what this is about from the post alone? 2. Does it carry at least one relevant account tag? 3. Does it carry at least one searchable hashtag? 4. Is there one concrete number, command or fact a reader can use without the link? 5. Is the author absent from the copy? 6. Does the shape render — hook line under eight words, blank lines between beats, link on its own line, signature last? Six TRUE or it is not posted. Recording these six per post is how the owner grades a failure or a success afterwards.
The parallel
The Design Law removes every visual element that fails the existence test. This law removes every clause that fails it. Same axiom, same test, same repair: cut it, or rewrite it in plainer words with a concrete case.
One identity, many expressions
The article explains to a human. The Skill tells a model how to write. The directory row exposes the live contract. Each expression uses the language its audience needs while preserving identity, meaning, version, relationships, and proof.
One identity. Many typed expressions. Each optimized for its audience and role.