house-rules

House rules

The four plugins this replaces could all write documentation. None of them could tell you which sentences were true. These are the rules that close that gap.

---

1. The governing rule

A sentence about behaviour needs a source, or it needs a tag. There is no third option and no exemption for sentences that are obviously true.

A source is one of:

• a file:line anchor that resolves in the current tree
• a command plus the output it actually produced
• a named test that covers the behaviour
• the screen, for a claim about what a reader sees. "The Deployments page has a New button" is checked by looking at it, and the anchor is the component that renders it or a screenshot in the page. This class exists because without it every sentence on a user page has to be justified against source code, and a writer who spends the day in source writes about source. survey.py returns the product's own on-screen wording under user_surface

Write the anchor down as you go. Reconstructing sources afterwards does not work, because by then you no longer remember which sentences you checked and which ones you assumed.

2. Working notation, and where it stops

While drafting, mark what you have not verified. Four tags, borrowed from HADS:

[SPEC]   Authoritative. Sourced. Terse.
[NOTE]   Human context, history, reasoning. Not a behavioural claim.
[BUG]    A verified failure. Requires symptom, cause, fix.
[?]      Inferred, not verified. Says what would settle it.

None of it ships. These tags are for the draft and for the plan. A reader who opens a product's documentation and finds [?] in the middle of a sentence is being shown the tooling that produced the page, and no product does that.

The honesty the tag carries is not optional, only the notation is. Before publishing, every [?] resolves one of three ways:

1. Go and check it. Then it is a plain sentence.
2. Say it in ordinary words. "This has not been tested against a live server" is honest, readable, and belongs on the page.
3. Cut the sentence. Silence is better than a claim nobody stands behind.