STYLE: the mechanics
Reader: a VP/Director of data who may forward it to an executive (nov30 targets:33; P1:6 PROPOSED). Purpose: a build note, "what I built on Snowflake, what broke, what I'd do next" (CONTRACT [[2026-09-29-nov30-credibility-targets]]:23). Floor for clarity: WRITING-rdco.md; voice rules shape the surface (WRITING-rdco.md:36, :42). Tags: CONTRACT · OBSERVED (the three drafts P1-P3 are Ray's, so their patterns are PROPOSED until he keeps them) · PROPOSED.
Headline formula (PROPOSED, from P1:11, P2:15, P3:16)
- Two short sentences, the second overturning the first: "Agents don't need your data warehouse. They need your definitions." / "My AI agent didn't crash. It waited." Each sentence under ten words.
- Or a plain question-shaped title with the caveat in parentheses: "What studying for SnowPro Gen AI taught me about Cortex (and what it didn't)".
- Clear over cute (CONTRACT [[2026-10-02-site-spec|site-spec]]:32). No "N things", no "nobody tells you" (VOICE).
- Site hero and tagline are fixed copy, not headlines: DESIGN-denominator.md:129-131 (CONTRACT).
Structure of a build note (PROPOSED, the order P1-P3 share)
- Byline in italics: "By Ben Wilson, Principal Consultant at phData." No disclaimer (CONTRACT site-spec:43). [TITLE:] note until the title is confirmed (P1:13).
- Hook, two sentences: what is easy now / what is still hard (P1:15).
- A rule line, then the scene with two concrete numbers, labelled "(Hypothetical example, invented numbers.)" when invented (P1:19-25).
- [BEN: ...] slot for his own non-client anecdote (P1:27).
- What broke, numbered H2s in the order it happened, each ending "For your agents: ..." (P2:31-65).
- What to invest in (three bold-lead bullets), then The bear case, then one confidence line (P1:47-67).
- "Your turn": one question to the reader. No summary (P1:69-71; VOICE closes).
- Receipts after the rule: Verified product claims (table with the doc), Unverified, Deliberately left out (P2:122-134).
- The LinkedIn cut, 150-180 words, acronyms re-expanded, backticks stripped, no link in the body (P1:77-101; WELSH:57, :65 PROPOSED). Diagrams are a core feature (CONTRACT site-spec:28): one per post, plain white PNG, after the byline (DESIGN-denominator.md:50).
Numbers (CONTRACT WRITING-rdco.md:32; forms OBSERVED in P1-P3, PROPOSED as rules)
- Every quantitative claim carries its basis inline or within reach: source, formula, or range. No naked percentages.
- Decimals keep the sign: 14.8%, 12.1%. A number that opens a sentence is spelled out: "Twenty-nine percent". Counts under twenty in words (four times, ten fixes), larger in digits (35 hours). Scores as "854 of 1000". Dates as "October 2" / "Sep 15, 2026".
- Numerals in illustrations are ink on a white face; never in the handwriting face (CONTRACT DESIGN-denominator.md:58, :113).
Acronyms (CONTRACT WRITING-rdco.md:17-19)
Expand on first use per standalone document: "Model Context Protocol (MCP)". The LinkedIn cut is its own document and re-expands. One term per concept; avoid the acronym when a plain word does the job.
Em-dash discipline (CONTRACT memory/feedback_no_em_dashes.md:17-18, :23; WRITING-rdco.md:40)
Default to a hyphen; his own habit is " - " (OBSERVED [[voice-profile-2026-05-08]]:123). Two em-dashes in a paragraph is the ceiling; three is overuse. En-dashes for ranges stay fine (MEM-emdash:20). No ", never X" comma hangers, no colon chains (WRITING-rdco.md:29). Never narrate the audit.
[BEN:] callouts (CONTRACT DESIGN-denominator.md:50, :88, :120, :132)
- Form:
[BEN: <what is needed, one line, in his words to fill>].[TITLE: ...]for the byline title only. - They render as notes to self (mono, grey fill, dashed ink border). The DRAFT badge comes from the EmDash is_draft flag (OBSERVED PostCard.astro:46), so clearing the notes and clearing the flag are two steps. The sticky on drafts says why: "draft: the dashed boxes are my notes to self".
- Hero invite and the subscribe-card line carry a note until he approves them (DESIGN:131-132).
Post length (PROPOSED, measured on P1-P3)
Body 1,000-1,100 words (P1 ~1,070, P2 ~1,032, P3 ~1,057) plus receipts. LinkedIn cut 150-180 words. X reply: one or two sentences (CONTRACT memory/feedback_x_voice_mismatch.md:10); Ray's working cap is 25 words unless quoting code (PROPOSED, MEM-x:17). Sentences: procedural under 20 words, descriptive under 25 (CONTRACT WRITING-rdco.md:26).
Edit write-back (the procedure Ray follows after the founder edits a draft)
- Keep Ray's sent draft as
drafts/<post>-vN.mdand save his returned version untouched asdrafts/<post>-vN-ben.md. Never rewrite his words; if a later draft needs his sentence, copy it verbatim. - Diff:
diff -u <vN>.md <vN-ben>.md(or the EmDash revision history). Walk every hunk. - Classify each change as one of four: voice (word choice, rhythm, humor, person), fact (a number, name, date, claim), structure (order, headings, cuts, length), taste (anything he changed that no rule explains yet). A hunk can carry two classes; record both.
- Log every change in VOICE.md "Observed edits" with the date, the draft, the class, Ray's text and Ben's text, verbatim and short.
- Promote to a rule only on the second occurrence of the same kind of edit (same class and same pattern, e.g. he cut a summary paragraph twice). Append a dated rule:
- 2026-MM-DD (from edits <draft A>, <draft B>): <rule>under the matching heading in VOICE.md (voice, taste) or STYLE.md (fact handling, structure, mechanics). Facts themselves go to the post, never to a rule. - Until the second occurrence, the first edit stays in the log only. Do not infer a trait from one edit (Every: "it may mistake one essay's subject for a permanent interest or promote a tic into a trait", 2026-09-02-every-compound-writing-guide.md:42).
- Each rule carries a before/after pair from his edit, in his words. Re-read the rule on the next draft; narrow a rule that overfires, delete one that stopped helping (compound-writing-guide:48-50).
- Keep both files at one page. When a file passes one page, fold the oldest log entries into the dated rules they produced and drop the rest.