Writing Styleguide

Writing Styleguide

Prose rules for everything BoB authors — GitHub issues, commit messages, PR descriptions, journal entries, code comments, and docs. Each rule is short and concrete enough to apply mid-write and check against after. Cite a rule by its ID (WS-1) instead of restating the style inline. (Back to reference index.)

This is reference mode — look up the rule you need, don’t read end-to-end. It is the single place commands, agents, hooks, and reviewers point at when they invoke a prose rule.

Scope, and the line with the documentation standard. The documentation standard (DS) owns how docs/ are structured — Diátaxis mode, directory taxonomy, frontmatter — and the writing principles for docs (§4: inverted pyramid, scannability, controlled vocabulary, single-source-of-truth, the bare-#N rule). This styleguide is broader in artifact and narrower in concern: it governs prose across all authored artifacts, not just docs. To avoid duplication (DS §4.4, applied to itself), it owns the cross-artifact rules below and references DS for the principles DS already owns — it never restates them. When a rule lives in DS, cite DS; when it lives here, cite WS-N.

How to cite a rule

Reference a rule by its stable ID, never by paraphrasing the style into your own text:

• In a review comment, command, agent, or hook: “see WS-1”, optionally linking to this doc. The WS-N ID is the contract — it never changes, so a citation stays valid even when the rule’s wording is refined.

• For a DS-owned principle, cite “DS §4.1” and link documentation-standard.md.

• Programmatically, resolve a rule’s text with the lookup tool (so tooling cites the canonical wording rather than embedding a copy):

  node ~/.claude/scripts/styleguide/cite.js list      # all rule IDs + titles
  node ~/.claude/scripts/styleguide/cite.js WS-1       # print one rule

Rules (owned here)

Each rule has a stable WS-N ID, a one-line statement, and a concrete do/don’t. IDs are append-only — a rule is never renumbered, so a citation never goes stale.

WS-1 — Write for the artifact’s reader, not the editing session

A finished artifact must stand on its own for someone encountering it fresh. They did not watch you write it and cannot see any earlier draft.

• Don’t reference the editing or correction process, or a prior version of the text the reader can’t see (“accurate framing”, “now corrected”, “as revised”, “to clarify the above”).
• Don’t negate a claim the reader was never shown (“it does not give up on tests” when nothing said it did) — describe the present state directly instead.
• Don’t contrast against an external source the reader doesn’t have in front of them as if they do (“unlike the previous approach…”).
• Prefer plain present-state description over editorial meta-commentary.

Do: “The loop pushes after each chunk.” Don’t: “To correct the earlier claim, the loop now actually does push after each chunk (it does not skip the push).”

WS-2 — Say why, not just what, in commit and PR bodies

The subject line states the change; the body exists to explain the motivation and the trade-offs. A bare subject is enough only for a trivial, self-evident change. Reviewers and git log archaeologists read the body to recover intent the diff can’t show.

• Lead the body with the problem or motivation, then the approach, then any alternative considered and rejected.
• Don’t restate the diff in prose (“changed X to Y”) — the diff already says that; say why X became Y.

Do: “Rebase before ff-merge: the release bot auto-pushes to master on feat pushes, so a plain merge would fail fast-forward.” Don’t: “Updated the merge step.”

WS-3 — State it plainly; cut hedges and filler

Confident present-tense prose reads faster and ages better. Hedge words and filler add length without information.

• Drop “basically”, “just”, “simply”, “obviously”, “of course”, “in order to” (→ “to”), and “we should probably”.
• Don’t soften a definite fact into a maybe; if it’s true, state it.

Do: “bob provision refresh re-links the manifest.” Don’t: “Basically, bob provision refresh should just re-link the manifest, more or less.”

Web-read rules (WS-4 to WS-10)

For anything Paul reads on a screen: todos, chunk and session reports, briefings, /journal and /status --file issues. Each is one checkable line. The evidence and where critics qualified it: Writing for the web. Also apply DS §4.1 (answer first) and DS §4.2 (headings that stand alone, lists and tables for parallel items, front-loaded titles). Checked by todo-contract.js: WS-4, WS-5, WS-6 (warnings).

WS-4 — The first line is the answer or the ask, in 25 words or fewer

Do: “Deploy to farm-01 is blocked: the Cloudflare token expired.” Don’t: “This todo was filed during the warp-drive run because…”

WS-5 — Each numbered step starts with a verb and does one thing

Do: “1. Run bob doctor.” Don’t: “1. The doctor command should be run, then check the output and redeploy.”

WS-6 — Link text names where it goes, never “here” or “this”

Do: “see the todo format contract” Don’t: “see here”

WS-7 — Plain words; gloss or link every internal term, never drop an identifier

Do: “the preflight gate (the check before work starts)” Don’t: “AC-3’s rung-2 surface” — or “the token” for CLOUDFLARE_API_TOKEN

WS-8 — Commands, paths and identifiers are copyable as-is

Do: a code block with every value filled in. Don’t: <your-account-id>, a command split across prose, a shortened issue or file name.

WS-9 — State is visible at a glance: done, doing, needs you

Do: a first line or heading that says “Needs you:”, “Done:”, “Running:”. Don’t: a state the reader must infer from paragraph three.

WS-10 — Cut happy talk and instructions about the instructions

Do: start with the content. Don’t: “This report summarises…”, “Below you will find…”, “Please read the following carefully.”

Principles referenced (owned by the documentation standard)

These apply to all artifacts, not only docs — but the canonical statement lives in DS §4, so cite DS rather than restating them here.

Cite	Principle	Applied beyond docs
DS §4.1	Inverted pyramid — answer first	A commit subject is the conclusion; an issue’s first sentence is the ask; a comment’s first line is the point.
DS §4.2	Scannability — write for the skim	Issue/PR bodies use headings, tables, and short lists, not walls of prose.
DS §4.3	Controlled vocabulary — one name per thing	Use the canonical term (warp-drive, requirement, BOB_SOURCE) in issues and comments too.
DS §4.4	Single source of truth — one owner per fact	Link to the owning doc from an issue/comment; don’t paste a copy that will drift.
DS §4.5	Reserve bare #N for real issue/PR references	Use C1/H2/“item 1” for intra-body item numbers — enforced by make check.

Adding a rule

The doc is living — rules accrete as prose feedback recurs. To add one without restructuring:

1. Append a new ### WS-N — <title> section under Rules (owned here), taking the next free N. Never renumber an existing rule (citations are permanent).
2. Give it a one-line statement, do/don’t bullets, and a Do: / Don't: example pair.
3. If the rule is really a DS principle applied to a new artifact, don’t add a WS-N — add a row to the referenced-principles table instead.

The lookup tool (cite.js) reads these headings directly, so a newly appended rule is immediately citable with no other change.

See also

• Writing for the web — the evidence behind WS-4 to WS-10 and where BoB departs from its sources.
• Documentation Standard — owns doc structure and the §4 writing principles this styleguide references.
• Memory conventions — the archive-on-supersede rule for preserving why a preference changed (the same “write for the reader” instinct, applied to memory history).