Client-Facing Documents
The files under .forge/client/ are read by Empire Teas. .claude/CLAUDE.md § Writing applies to
them; these rules add what a client reader needs. Three kinds of file are outside these rules, except
that the weekly updates follow Simple English below: the
issued proposal (project-proposal.md), frozen and changed only through the post-issue notes in its
header (.claude/rules/source-trust.md); aws-sow.md, a record of a superseded document; and the
weekly updates (weekly-updates/), which are emails written by /et-weekly-update and are not
changed once sent. A user-guide chapter is user-guide-<area>.md in this folder, beside the rest of
the pack; every file here gets a page on the doc site without being listed (render-docs-html.js). An existing file
whose header differs from the one below is brought into line when it is next edited for another
reason, not in a change of its own.
-
Plain terms, in the document itself. Say what a step means for Empire: “the IT admin says yes once”, not “admin consent”; “staff who have a Microsoft 365 licence”, not “licensed users”. A table of asks or terms gets an “In plain terms” column or line, as
dependencies.mddoes. -
Simple English, checked before the change is committed. Empire’s readers include Tea Room and sales staff who read English as a working language and have not seen the CRM’s code or specs. Every file these rules cover, and the weekly updates, meets these checks (the issued proposal and
aws-sow.mdare records and are not rewritten):- Short sentences, one idea each. Aim for under 20 words. A sentence that joins two ideas with “and”, “unless”, “because”, “so” or a semicolon is split into two.
- Say who does what. “The Tea Room publishes the prices”, not “the prices are published”. Name the person or the CRM as the subject.
- Common words. “Use”, not “utilise”; “before”, not “prior to”; “ends”, not “lapses”; “about”, not “regarding”; “can”, not “is able to”. No legal or software terms the reader would not use at work (no “effective-dated”, “idempotent”, “provision”).
- The point first. Start each section with what the reader does or gets; give the reason after.
- Steps as numbered lists, choices as “If …, …” lines or a table, never as one long paragraph.
- Explain each CRM word once, the first time it is used or in a “Words used” table, and then use that same word every time (not “round” in one place and “price set” in another).
- An example for any rule about dates or numbers: “Sale 42 starts on Tuesday 20 October, so …”.
- Screen names exactly as the screen shows them, in bold: Publish Prices.
- The test: someone in the Tea Room who has never used the CRM can follow each paragraph on the first reading. If a paragraph has to be read twice, rewrite it.
- Run the checker on the file before committing:
python3 .claude/lib/check-plain-english.py <file>lists every sentence over 30 words and every formal word, with its line. Rewrite each one, or leave it only where a long sentence is the clearer choice (a list of names in a table cell, a screen message quoted exactly).--summarygives one line per file.
Why: the lead found the first user-guide chapter and the client pack too hard to read (2026-11-16); long sentences with several conditions lose a reader who is not a native speaker.
-
Phase 1 and Phase 2 only. Never the proposal’s internal phase labels (Phase 0, 1a, 1b, 1c — the Statement of Work maps milestones to them) and never “first half” or “second half”. Internal documents keep the bridge to the proposal’s labels for traceability. The capture app is Phase 1 (since 11 November 2026).
-
A short header. The identity line,
> Prepared by Altrium for Empire Teas (Pvt) Ltd; any line the reader needs to read the document (its scope, its purpose, the date its figures are based on); then, when a change matters to the reader, one dated line saying in plain terms what changed (> **Revised <date>:** …), newest first. Keep at most three such lines in the header; the older ones move, unchanged in meaning, to a## Change historylist at the end of the document, newest first, so the reader reaches the content first (client-facing-prd.mddoes this). A dated note in the body beside the item that changed (“Updated: …”) is fine. No “draft for review” footer, no “available on request”, no “issued with the SoW”. A document Empire has still to agree says so once ( roles-and-permissions.mdandphase-1-acceptance-criteria.mdare marked DRAFT). -
No delivery internals. No team-capacity arithmetic (lane counts, effort-day totals, contingency), no per-holiday or leave lists, no internal mobilisation rows, no “a working prototype already exists”, no “deferred pending …” hedges in an out-of-scope list (the proposal’s change control covers re-scoping). That arithmetic stays in
tracker.yaml(R-ARCH-001). -
The timeline’s dates come from one table. In
project-timeline.mdthe current dates are § 1’s schedule table, anchored on the communicated kickoff, Tue 1 Sep 2026, never on an assumed signature date. § 2’s summary repeats them and must match it; no chart is added. The appendix keeps the earlier plan unchanged, as its record. -
Costs are the annexe’s figures. A cost row states the figure from
sow-cost-annexe.md, without commentary on how it differs between sources. -
A dropped item is not announced separately. Record it in
client-facing-prd.md(and the proposal’s post-issue notes where it changes a promise) and add no task to tell Empire (.claude/rules/prd.md § Conventions).
Why: the client needs the product and the dates, not our metadata or how we work; each rule here corrects something the lead removed from an earlier client page.