From 4364da208bd83ce7722befb9c6134ad035c6aef5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 12:10:36 +1100 Subject: [PATCH] docs: add the house writing style (#120) Records the product owner's 27 Oct 2026 decisions: the style applies to all repo writing; Australian spelling in prose; no generated-by footers on issues or PRs; "the product owner" on GitHub. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_019YPoXzBSj89ZHgw7nfTmbB --- docs/WRITING.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/WRITING.md diff --git a/docs/WRITING.md b/docs/WRITING.md new file mode 100644 index 0000000..8313e9c --- /dev/null +++ b/docs/WRITING.md @@ -0,0 +1,53 @@ +# Writing in this repo + +This is the house style for every issue, PR, comment and doc in this repo, whoever writes it. The product owner decided on 27 Oct 2026 that it applies to all repo writing. + +## Rules + +1. **Evidence before status.** Write "closed", "passing" or "verified" only when you can name the evidence: a run, a commit or an attached file. Quote test results as passed / failed / skipped, for example "297 passed, 0 failed, 0 skipped". Docs such as `VCRM.md` are claims, not evidence. +2. **No issue closes without clean evidence.** Every issue ends with a **Done when** section that says what evidence will close it. A rehearsal is not the real run. +3. **State the gaps.** Say what wasn't run, wasn't attached or couldn't be checked, as plainly as the results. If a cause is unknown, say so and list what to check. +4. **The product owner decides scope.** Present options with a recommendation, for example "Defaults I chose (please confirm)" with a Why column. Credit decisions once taken: "Approved by the product owner on 26 Oct." Don't reopen items marked "risk accepted" or "deferred by decision". +5. **Runnable commands.** PowerShell for the dev machine, and every block starts with `cd ""`. Linux-side steps, such as the offline VM, are labelled bash. Put Python in a `.py` file, never in a pasted multi-line block. +6. **Traceable references.** Use issue and PR numbers, short commit hashes, file paths in backticks, and absolute dates ("27 Oct 2026"). Don't use "recently" or "the earlier fix". +7. **Never write secrets.** Passwords, API keys, tokens and `PGPASSWORD` values never go into issues, PRs, docs or evidence files. + +## Conventions + +- **Audience:** in issues, PRs and repo docs, refer to the decision-maker as "the product owner". +- **Spelling:** Australian in prose ("authorisation", "behaviour"). Code identifiers, routes and library names keep their own spelling. +- **Footers:** no "Generated with …" footer on issues or PRs. +- **Style:** + - Short sentences, with numbers instead of adjectives. + - Bold lead-ins for bullets the reader will scan. + - Avoid "robust", "seamless", "production-ready" and "should work". + - Don't use "fully offline" until #60 has its evidence. + +## Templates + +**Issue** + +```markdown +Found on while . Relates to
. + +## What happened + + +## Proposed + + +## Done when + +``` + +**PR** + +```markdown +Fixes #N. Part of (
). + +## What changes + + +## Checks + +```