grokbot_ty
8a7f2a68a8
Standing voice for strategy/research prose: plain terms on first use, trigger before action, claims first with labeled evidence underneath.
2.0 KiB
Writing rules (outsider-first)
Branch: planning-selfserve-audit
Scope: Strategy and research docs under docs/ (especially commercial proposals and research briefs). Complements CONVENTIONS.md (anti-duplication); does not replace it.
These rules exist so a reader with no industry background can follow the argument on the first pass.
1. No insider jargon without a plain clause
On first use of a term a bakery owner would not know, explain it in one plain clause in the same sentence (or the next). Prefer ordinary words over acronyms. If you must use a short label later, introduce it once.
Examples: say “Google’s short list of three at the top of many local searches” before “3-Pack”; say “name, address, and phone” before “NAP”; say “Google Business Profile” before “GBP.”
2. Open every claim with the reader’s trigger
Before any product action or “we build…”, show the problem the reader feels — lost customers, wrong hours, dead phone number, AI pointed somewhere else. Action comes after the trigger. Reference voice on this branch: commits fa98bdb (claims for zero-insider readers) and b859f3e (claim 1 opens with the owner’s trigger).
3. Plain verbs, conversational prose
Write like a clear friend who knows the subject. Complete sentences. No throat-clearing (“the sections below keep…”, “they are the receipts”), no slogan-as-mechanism, no AI-slop padding.
4. Claims first, evidence underneath
Lead with the argument the outsider needs. Put tables, studies, and source labels below as support. Label evidence: practitioner-reported, vendor, primary study, or UNVERIFIED. Cite or mark BLOCKED — do not invent numbers.
5. One SoT per topic
Amend the existing file for a topic. Do not create sibling PLAN/CONCEPT/BRIEF twins. See CONVENTIONS.md.
Capture
Standing outsider-first rules recorded 2026-10-01 from corrected-voice passes on the research brief (fa98bdb, b859f3e).