diff options
| author | Craig Jennings <c@cjennings.net> | 2026-05-29 15:17:29 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-05-29 15:17:29 -0500 |
| commit | 296b2e684d73c70bdf6b42407ddf86c0cb7ba493 (patch) | |
| tree | c8b22432b611e32aa3af985f7d84d0e9f0044cf1 | |
| parent | 664bf01ceaccf730cb636463cc8587cd1d966192 (diff) | |
| download | rulesets-296b2e684d73c70bdf6b42407ddf86c0cb7ba493.tar.gz rulesets-296b2e684d73c70bdf6b42407ddf86c0cb7ba493.zip | |
docs(voice): split SKILL.md and voice-profile.org into paired source-of-truth, Pattern 13 worked example
This is option C from the structural-split proposal. SKILL.md becomes
the thin rule-set. voice-profile.org becomes the canonical home for
rationale, basis, examples, and per-pattern history. Pattern 13 is
migrated as the worked example to confirm the form. The remaining 40
patterns are scheduled for a backfill pass.
SKILL.md gains a Source of Truth section near the top stating the
pairing rule. Every change to a pattern must land in both files. A
SKILL.md edit without a profile update is incomplete. A profile
update without a SKILL.md edit is fine.
Pattern 13 in SKILL.md collapses to a single Rule line plus mode tags
plus a pointer to voice/references/voice-profile.org §13. The Problem
paragraph, the Mode-dependent-strength paragraph, the Note-on-basis
paragraph, and the Before/After examples all move to the profile.
voice-profile.org gains a How this combines with SKILL.md preamble
that names the pairing rule explicitly. Pattern §13 lands with all
the migrated content plus a History section recording the prior
commits (original SKILL.md entry, the 2026-05-26 prose-mode addition
in 4fac2a0, the 2026-05-29 basis note in c3cf9a5, and this
migration).
If Craig confirms the shape, the next pass backfills patterns 1
through 12 and 14 through 41 in the same form.
| -rw-r--r-- | voice/SKILL.md | 25 | ||||
| -rw-r--r-- | voice/references/voice-profile.org | 47 |
2 files changed, 60 insertions, 12 deletions
diff --git a/voice/SKILL.md b/voice/SKILL.md index 2368687..f8b0a06 100644 --- a/voice/SKILL.md +++ b/voice/SKILL.md @@ -15,6 +15,17 @@ allowed-tools: You are a writing editor that walks a numbered pattern list against a piece of text and rewrites each problematic section. The patterns cover three concerns: signs of AI-generated writing (Wikipedia's "Signs of AI writing" guide), universal good-writing rules (Strunk & White, Orwell's "Politics and the English Language", Plain English Campaign, Garner's Modern English Usage), and Craig's personal voice for publish artifacts (commits, PR titles + bodies, PR review comments). +## Source of Truth: paired files + +This skill is split across two files by design. + +- **`voice/SKILL.md`** (this file) — the thin rule-set. Each numbered pattern has a one-line Rule, mode tags, and a pointer to the profile. +- **`voice/references/voice-profile.org`** — the canonical home for problem statements, basis (corpus evidence where measured), Before/After examples, detection guidance, and per-pattern history. + +**Pairing rule.** Every change to a pattern lands in both files. A SKILL.md edit without a profile update is incomplete. A profile update without a SKILL.md edit is fine; rationale and evidence can deepen without changing the rule. + +**At invocation, load both.** The Rule lines here tell you what to do. The profile entries tell you how to do it, with worked examples. Apply each pattern by consulting both. + ## Modes Three modes determine which patterns to walk. They nest: prose is general plus Craig's writing-voice patterns; personal is prose plus the artifact-mechanics patterns. @@ -212,19 +223,11 @@ Avoiding AI patterns is half the job. Sterile, voiceless writing is just as obvi ## Style Patterns -### 13. Em Dash Overuse +### 13. Em Dash Overuse [general: overuse-reduction · prose/personal: zero-tolerance] -**Problem:** LLMs use em dashes (—) more than the median human writer, mimicking "punchy" sales writing. +**Rule.** Replace em-dashes (—) with a comma, period, colon, or parentheses, whichever fits. Zero-tolerance in prose and personal modes holds everywhere in the text, including inside example blocks, code-fence prose, and quoted material. -**Mode-dependent strength.** In **general mode** this is overuse-reduction: cut the excess, but an occasional em-dash in someone else's prose can stay. In **prose and personal modes** it's **zero-tolerance** — Craig's voice has no em-dashes at all. Replace every one with a comma, period, colon, or parentheses, whichever fits. The zero-tolerance rule holds *everywhere in the text*, including inside example blocks, code-fence prose, and quoted material — not just running prose. An em-dash in a quoted line still gets replaced. - -**Note on basis (2026-05-29).** A corpus pass over Craig's git commit bodies (5355 commits, 128k words, sources in `voice/references/voice-profile.org`) measured his em-dash rate at 3.49 per 1000 words, comparable to AI-generated prose. The zero-tolerance rule in prose and personal modes is self-discipline, not habit-reflection. Craig has decided his published voice drops em-dashes by choice because the result reads cleaner and avoids the most common AI tell, regardless of his pre-rule frequency. - -**Before:** -> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents. - -**After:** -> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents. +See `voice/references/voice-profile.org` §13 for problem, basis, examples, and history. ### 14. Overuse of Boldface diff --git a/voice/references/voice-profile.org b/voice/references/voice-profile.org index ec074b9..15f01c4 100644 --- a/voice/references/voice-profile.org +++ b/voice/references/voice-profile.org @@ -1,7 +1,17 @@ -#+TITLE: Voice profile Phase 1 — corpus-grounded delta proposal +#+TITLE: Voice Profile — canonical source-of-truth for the voice skill #+DATE: 2026-05-29 #+SOURCE: rulesets session 2026-05-29 +* How this combines with SKILL.md (pairing rule) + +This file is the canonical source-of-truth for the voice skill's rationale, evidence, examples, and history. =voice/SKILL.md= holds the thin rule-set: one-line directives per pattern, mode applicability, and a pointer back here. Everything else (Problem, Basis, Before/After, Detection guidance, History) lives in the per-pattern sections below. + +Pairing rule. Every change to =voice/SKILL.md= MUST land alongside the corresponding update in this file. The two are normatively paired. A SKILL.md edit without a profile update is incomplete. A profile update without a SKILL.md edit is fine (rationale or evidence can deepen without changing the rule). + +Pattern numbering in both files matches: SKILL.md's =### N. <Name>= maps to this file's =* §N <Name>= section. Mode tags use the same vocabulary: =general=, =prose=, =personal=. + +When the agent runs =/voice=, it reads SKILL.md for the rules and consults this file for the examples and basis it needs to apply each pattern correctly. + * Corpus Git commit bodies authored by Craig Jennings across all repos under =~/code/= and =~/projects/=. After cleanup (subject lines, trailers, URL-only lines, AI-attribution lines, blank-run collapse): @@ -87,3 +97,38 @@ Six concrete edits to =voice/SKILL.md=, all of which can land independently: - Slack messages — casual register, contraction rate, sentence-fragment rate. - Syntactic detection — distinguish fragments from terse complete sentences for pattern #37. - Long-form documents (résumé, proposals if any) — single register but high prose density. + +* Per-pattern entries + +The 41 patterns are migrated below from SKILL.md per the pairing rule above. Phase 1 of this migration populates only Pattern §13 as a worked example of the form. The remaining 40 patterns are scheduled for the backfill pass once Craig confirms the shape. + +** §13 Em Dash Overuse + +*** Modes +General mode: overuse-reduction. +Prose + personal modes: zero-tolerance. + +*** Rule +Replace em-dashes (=—=) with a comma, period, colon, or parentheses, whichever fits. Zero-tolerance in prose and personal modes holds *everywhere in the text*, including inside example blocks, code-fence prose, and quoted material. An em-dash in a quoted line still gets replaced. + +*** Problem +LLMs use em dashes more than the median human writer, mimicking "punchy" sales writing. + +*** Basis +Corpus measurement (2026-05-29 git commits, 128k words): 3.49 em-dashes per 1000 words. Comparable to AI-generated prose. The zero-tolerance rule in prose and personal modes is self-discipline, not habit-reflection. Craig has decided his published voice drops em-dashes by choice because the result reads cleaner and avoids the most common AI tell, regardless of his pre-rule frequency. + +*** Before +#+begin_example +The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents. +#+end_example + +*** After +#+begin_example +The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents. +#+end_example + +*** History +- Original SKILL.md entry: rule scoped to general overuse-reduction. +- 2026-05-26 (commit =4fac2a0=): prose mode added, rule strengthened to zero-tolerance in prose and personal. +- 2026-05-29 (commit =c3cf9a5=): Note on basis added with corpus measurement. +- 2026-05-29: migrated to this file as the canonical home per the pairing rule. |
