diff options
Diffstat (limited to 'voice')
| -rw-r--r-- | voice/SKILL.md | 21 | ||||
| -rw-r--r-- | voice/references/voice-profile.org | 51 |
2 files changed, 64 insertions, 8 deletions
diff --git a/voice/SKILL.md b/voice/SKILL.md index fe5d48a..10e8fd6 100644 --- a/voice/SKILL.md +++ b/voice/SKILL.md @@ -1,7 +1,7 @@ --- name: voice description: | - Multi-pass prose editor with three modes. General mode (default) edits arbitrary writing — research notes, essays, anyone's README prose — by walking 31 patterns: Wikipedia's Signs of AI Writing patterns plus universal good-writing rules (long-word → short-word, active-over-passive, comma splices, cliché flag, jargon-fragment-in-prose rewrite, corporate-speak nominalizations). Prose mode adds Craig's writing-voice patterns for prose he authors or sends — emails, documents, notes — on top of general (em-dash zero-tolerance, no-emphasis-formatting, contractions, semicolons → periods, sentence-split, felt-experience cut, sentence-fragment rewrite, terse-cut, single-sentence cadence, parenthetical asides, declarative-register marker). Personal mode is for publish artifacts only (commits, PR titles + bodies, PR review comments) and adds the artifact-mechanics patterns on top of prose (first-person rewrite, public-artifact scope flag, praise/correction asymmetry, finding stems, comma budget) plus per-artifact terseness budgets. Total 46 patterns; one editorial review covers all relevant ones for the chosen mode, with an attestation receipt for the high-recurrence set. Replaces the standalone humanizer skill. Use when editing prose. Do NOT use for code, structured data, or plain bullet lists where fragments are valid. + Multi-pass prose editor with three modes. General mode (default) edits arbitrary writing — research notes, essays, anyone's README prose — by walking 31 patterns: Wikipedia's Signs of AI Writing patterns plus universal good-writing rules (long-word → short-word, active-over-passive, comma splices, cliché flag, jargon-fragment-in-prose rewrite, corporate-speak nominalizations). Prose mode adds Craig's writing-voice patterns for prose he authors or sends — emails, documents, notes — on top of general (em-dash zero-tolerance, no-emphasis-formatting, contractions, semicolons → periods, sentence-split, felt-experience cut, sentence-fragment rewrite, terse-cut, single-sentence cadence, parenthetical asides, declarative-register marker). Personal mode is for publish artifacts only (commits, PR titles + bodies, PR review comments) and adds the artifact-mechanics patterns on top of prose (first-person rewrite, public-artifact scope flag, praise/correction asymmetry, finding stems, comma budget) plus per-artifact terseness budgets. Prose mode also carries one correspondence-only pattern (recipient-priority ordering) that personal mode skips. Total 47 patterns; one editorial review covers all relevant ones for the chosen mode, with an attestation receipt for the high-recurrence set. Replaces the standalone humanizer skill. Use when editing prose. Do NOT use for code, structured data, or plain bullet lists where fragments are valid. allowed-tools: - Read - Write @@ -31,8 +31,8 @@ This skill is split across two files by design. 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. - **General** (default) — apply patterns **#1-31**. Use for writing whose author isn't Craig and that isn't a publish artifact: research notes you're editing for someone else, a quoted passage, README prose for a shared project, any third-party text. Output is well-edited human-sounding prose, but does not impose Craig's voice (first-person, contractions, em-dash elimination) — those conflict with academic, literary, or formal registers that aren't his. -- **Prose** — apply **#1-31** plus the patterns tagged **(prose + personal)**: em-dash zero-tolerance (#13), contractions (#34), semicolons → periods (#33), sentence-split (#35), felt-experience cut (#36), sentence-fragment rewrite (#37), terse-cut (#38), no-emphasis-formatting (#41), single-sentence cadence (#43), parenthetical asides (#44), and the declarative-register marker (#45). Use for prose Craig authors or sends in his own voice that isn't a publish artifact: emails, documents he writes or hands to someone, working notes, journal entries. This is the mode that finally applies his actual writing voice to the documents he most wants it on. It skips the artifact-mechanics patterns (#32, #39, #40, #42) — those assume a commit or PR and misfire on free prose (a document is legitimately third-person; a journal has no public-scope concern; praise/correction asymmetry and finding stems are PR-review rules). -- **Personal** — apply all **#1-46**. Use only for publish artifacts: commits, PR titles + bodies, and PR review comments. Adds the artifact-mechanics patterns (#32 first-person rewrite, #39 public-artifact scope flag, #40 praise/correction asymmetry, #42 finding stems, #46 comma budget) on top of everything prose mode walks. +- **Prose** — apply **#1-31** plus the patterns tagged **(prose + personal)**: em-dash zero-tolerance (#13), contractions (#34), semicolons → periods (#33), sentence-split (#35), felt-experience cut (#36), sentence-fragment rewrite (#37), terse-cut (#38), no-emphasis-formatting (#41), single-sentence cadence (#43), parenthetical asides (#44), and the declarative-register marker (#45) — plus **#47 (recipient-priority ordering)** when the piece is correspondence (email, Signal, a letter). Use for prose Craig authors or sends in his own voice that isn't a publish artifact: emails, documents he writes or hands to someone, working notes, journal entries. This is the mode that finally applies his actual writing voice to the documents he most wants it on. It skips the artifact-mechanics patterns (#32, #39, #40, #42) — those assume a commit or PR and misfire on free prose (a document is legitimately third-person; a journal has no public-scope concern; praise/correction asymmetry and finding stems are PR-review rules). +- **Personal** — apply **#1-46**. Use only for publish artifacts: commits, PR titles + bodies, and PR review comments. Adds the artifact-mechanics patterns (#32 first-person rewrite, #39 public-artifact scope flag, #40 praise/correction asymmetry, #42 finding stems, #46 comma budget) on top of everything prose mode walks. #47 is the lone exception to the nesting — it is correspondence-only, and a publish artifact is never a reply to someone's news, so personal mode stops at #46. If invoked without a mode argument, default to general. Prose mode is invoked explicitly with `/voice prose` (emails, authored documents). Personal-context callers (`commits.md` publish flow, `respond-to-cj-comments.md`) invoke `/voice personal`. @@ -53,7 +53,7 @@ Terse is a budget, not an adjective. Each publish-artifact type has a target sha When given text to edit: -1. **Identify which patterns apply** — Scan for the patterns numbered below. General mode walks #1-31 only. Prose mode adds the patterns tagged **(prose + personal)**. Personal mode adds those *and* the ones tagged **(personal only)** — i.e. all 46. +1. **Identify which patterns apply** — Scan for the patterns numbered below. General mode walks #1-31 only. Prose mode adds the patterns tagged **(prose + personal)**, plus #47 when the piece is correspondence. Personal mode adds the **(personal only)** ones instead — patterns #1-46, never #47. 2. **Rewrite problematic sections** — Replace each detected pattern with its rewrite. 3. **Preserve meaning** — Keep the core message intact. 4. **Maintain voice** — Match the intended tone (formal, casual, technical, academic, literary). @@ -296,7 +296,7 @@ See `voice/references/voice-profile.org` §31 for problem, basis, examples, and ## Craig's Voice (prose + personal modes) -These patterns carry Craig's writing voice. Most apply in **both** prose mode (emails, documents, notes he authors) and personal mode (commits, PRs, PR comments) — tagged **(prose + personal)**. Five are publish-artifact-specific — tagged **(personal only)** — because they assume a commit or PR and misfire on free prose: #32 (first-person rewrite) wrongly imposes "I did X" voice on a document that's legitimately third-person, #39 (public-artifact scope flag) has nothing to guard in a private journal, #40 (praise/correction asymmetry) and #42 (finding stems) are PR-review rules, and #46 (comma budget) is scoped to publish artifacts by Craig's 2026-07-20 directive. General mode skips all of them — it edits text that isn't Craig's, where contractions, em-dash elimination, and first-person would conflict with academic, literary, or formal registers. +These patterns carry Craig's writing voice. Most apply in **both** prose mode (emails, documents, notes he authors) and personal mode (commits, PRs, PR comments) — tagged **(prose + personal)**. Five are publish-artifact-specific — tagged **(personal only)** — because they assume a commit or PR and misfire on free prose: #32 (first-person rewrite) wrongly imposes "I did X" voice on a document that's legitimately third-person, #39 (public-artifact scope flag) has nothing to guard in a private journal, #40 (praise/correction asymmetry) and #42 (finding stems) are PR-review rules, and #46 (comma budget) is scoped to publish artifacts by Craig's 2026-07-20 directive. One — #47 (recipient-priority ordering) — runs the other way: prose-only and narrower still, firing solely on correspondence, because ordering a reply around the recipient's news has no meaning for a commit or a document addressed to nobody. General mode skips all of them — it edits text that isn't Craig's, where contractions, em-dash elimination, and first-person would conflict with academic, literary, or formal registers. ### 32. First-Person Voice Rewrite [personal] @@ -366,7 +366,7 @@ See `voice/references/voice-profile.org` §42 for problem, basis, examples, and ### 43. Single-Sentence Paragraph Cadence Is a Feature [prose · personal] -**Rule.** A one-sentence paragraph is a finished thought, not a fragment. Break paragraphs after one complete thought when the next thought shifts angle, even if both are short. Never merge short paragraphs into multi-sentence ones in a "clean prose" pass (corpus: 41-74% of Craig's paragraphs are exactly one sentence, depending on register). +**Rule.** A one-sentence paragraph is a finished thought, not a fragment. "Shifts angle" means shifts *topic*: break paragraphs at a topic boundary, even when both sides are one sentence. Within a single topic, do the opposite — consolidate its sentences into one paragraph even when each is a complete thought, up to a ceiling of about five or six sentences, past which find a natural break. The never-merge instruction protects the break *between* topics, which is where Craig's cadence lives (corpus: 41-74% of his paragraphs are exactly one sentence, depending on register); it never licenses fragmenting one topic across several paragraphs. See #47 for the ordering of those topics in a reply. See `voice/references/voice-profile.org` §43 for problem, basis, examples, and history. @@ -388,10 +388,16 @@ See `voice/references/voice-profile.org` §45 for problem, basis, examples, and See `voice/references/voice-profile.org` §46 for problem, basis, examples, and history. +### 47. Recipient-Priority Ordering [prose — correspondence only] + +**Rule.** In a reply, lead with what matters most to the *recipient*, not with what's easiest to answer or the order they wrote it. Their news outranks your logistics, and a direct question they asked can sort *below* personal news they shared, because the news is what they care about. Leading with the easy answer reads as transactional. Correspondence-scoped: it needs a recipient, so it fires on email, Signal, and letters, and has no referent in a journal, a working note, or any document addressed to nobody. This is the one prose-mode pattern that does not carry into personal mode — a commit or PR review is not a reply to someone's news. + +See `voice/references/voice-profile.org` §47 for problem, basis, examples, and history. + ## Process 1. Read the input text carefully. Confirm the mode (general, prose, or personal) — invocation argument or context. If a file path was given, that file is the deliverable: the final text gets written back to it in step 7. -2. Walk patterns 1-31 in general mode; add the (prose + personal) patterns in prose mode; walk all 46 patterns in personal mode. +2. Walk patterns 1-31 in general mode; add the (prose + personal) patterns in prose mode, plus #47 when the piece is correspondence; walk patterns 1-46 in personal mode. 3. For each pattern, scan the text. If a match is found, rewrite it according to the pattern's rule. Patterns #39 and #45 emit flags without rewriting. 4. After walking all patterns, ensure the revised text: - Sounds natural when read aloud @@ -488,6 +494,7 @@ This skill draws from: - Garner, *Modern English Usage* — pattern #26 (word-pair preferences). - Craig's voice rules from `claude-rules/commits.md` (Voice and Focus section) — patterns #32-42, split across prose mode (his authored prose and email) and personal mode (publish artifacts). - Craig's directive, 2026-07-20 (archsetup session) — pattern #46 (comma budget), personal mode. +- Craig's edit of a Signal reply, 2026-07-23 (home session) — pattern #47 (recipient-priority ordering) and the #43 topic-vs-angle calibration, prose/correspondence. - Corpus measurement (2026-05-29 phases 1-2, documented in the profile) — patterns #43-45 and the calibration notes on #7, #13, #33. Key insight (Wikipedia, paraphrased): LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely text that applies to the widest variety of cases. Patterns #1-25 detect that signature. diff --git a/voice/references/voice-profile.org b/voice/references/voice-profile.org index 3907edf..3dfddf2 100644 --- a/voice/references/voice-profile.org +++ b/voice/references/voice-profile.org @@ -1444,11 +1444,13 @@ In a PR review finding: a sentence carrying more than one claim (chained through Prose and personal modes. General mode skips because third-party registers legitimately prefer multi-sentence paragraphs. *** Rule -A one-sentence paragraph is a finished thought, not a fragment. Break paragraphs after one complete thought when the next thought shifts angle, even if both are short. Never merge short paragraphs into multi-sentence ones in a "clean prose" pass. +A one-sentence paragraph is a finished thought, not a fragment. "Shifts angle" means shifts *topic*: break paragraphs at a topic boundary, even when both sides are one sentence. Within a single topic, consolidate its sentences into one paragraph even when each is complete, up to a ceiling of about five or six sentences, past which find a natural break. The never-merge instruction protects the break *between* topics; it never licenses fragmenting one topic across several paragraphs. *** Problem Most prose-style guides advise multi-sentence paragraphs, so a generic cleanup pass merges Craig's short paragraphs and erases a distinctive feature of his voice. This is a protective pattern: it guards an existing trait rather than correcting a defect. +The 2026-07-23 boundary refinement addresses the opposite failure, discovered the same day: reading "angle" at *sentence* granularity, so that three sentences all about one topic (a baking run, a mixer, tortillas) got split into three paragraphs as if each were a new angle. That fragments one topic and reads as a checklist rather than a person talking. Angle means topic. #43 governs the break between topics; consolidation fills in what happens within one, which the original rule never specified. The two are one rule seen from both sides, not a rule in tension with #47. + *** Basis Corpus-measured (2026-05-29). Single-sentence-paragraph rate: git commits 41.1%, personal email 57.4%, work email 44.5%, PR descriptions 74.4%, PR review comments 50.0%. Between 41% and 74% of Craig's paragraphs are exactly one sentence, depending on register. @@ -1470,6 +1472,7 @@ An edit pass that merged short paragraphs, or a draft whose paragraphs each stac *** History - 2026-05-29: surfaced by the Phase 1-2 corpus measurement as a "worth adding" trait; filed as suggested delta 4. - 2026-06-10: promoted from the suggested-deltas list into a numbered pattern. Craig's call, from the work-project session. +- 2026-07-23: boundary refined (angle means topic; within-topic consolidation to a ~5-6 sentence ceiling; never-merge reframed as across-topic protection). From a home session drafting a Signal reply, where the original rule was misread at sentence granularity. Paired with the new §47. ** §44 Parenthetical Asides Are Part of the Voice @@ -1562,3 +1565,49 @@ Count commas per sentence on the final text. A sentence at three or more gets re *** History - 2026-07-20: added at Craig's direction from the archsetup session. Scoped to personal mode; broaden to prose only if he asks. Added to the attestation high-recurrence set at birth — a mechanical count is cheap to receipt, and new discipline fails silently without one. + +** §47 Recipient-Priority Ordering + +*** Modes +Prose mode, and only when the piece is correspondence (email, Signal, a letter). It needs a recipient, so it has no referent in a journal, a working note, or any document addressed to nobody, and it does not carry into personal mode — a commit or PR review is not a reply to someone's news. General mode skips it with the rest of Craig's voice patterns. This is the one pattern narrower than a whole mode, and the only prose pattern personal mode does not also walk. + +*** Rule +In a reply, lead with what matters most to the recipient, not with what's easiest to answer or the order they wrote it. Their news outranks your logistics. A direct question they asked can sort below personal news they shared, because the news is what they care about. + +*** Problem +The easy draft answers the explicit question first and orders the rest as it arrived. That reads as transactional — logistics before the person. Ordering by what the recipient cares about is what makes a reply read as one person talking to another rather than a ticket being closed. Nothing else in the skill governs the *order* of a reply's contents; the other patterns act within a paragraph or a sentence. + +*** Basis +Craig's edit of a Signal reply to his sister, 2026-07-23 (home session). His framing: "start with what would be the most important things to her." + +*** Before (first draft — opens with the only explicit question, cooking split across three paragraphs) +#+begin_example +Yes, I do subscribe to MasterClass — happy to share what I've watched. + +That's amazing about the sourdough. English muffins from scratch is no joke. + +The home-roasted deli meat sounds incredible. + +A stand mixer would make the bread a lot easier — worth it if you're baking this much. + +And 30 pounds — that's huge. So happy for you. +#+end_example + +*** After (Craig's order — weight first, one cooking paragraph, then the question, then the close) +#+begin_example +Thirty-plus pounds — that is huge, and I'm so happy for you. That's real work. + +And the cooking. Sourdough, English muffins, tortillas, home-roasted deli meat from scratch — that's a whole kitchen you've built, and a stand mixer would make the bread much easier if you're baking at this volume, so I say go for it. I want to hear how the tortillas come out. + +Yes, I subscribe to MasterClass — I'll send you what I've been watching. + +I miss you and I love you. Send me a few times that work for a call. +#+end_example + +The cooking paragraph runs seven sentences, a hair over the §43 ceiling. Craig called it an exception rather than re-cut a message that had already gone out. The guard is the rule; this paragraph is one sentence over it; both facts stay in the record, because a real example at the boundary teaches it better than a clean one. + +*** Detection +A reply whose opening answers a logistical or yes/no question while the recipient's substantive news sits lower. Reorder so the news they'd most want acknowledged leads. + +*** History +- 2026-07-23: added from the home session drafting a Signal reply. The first handoff proposed two new patterns and flagged a conflict with §43; the superseding design resolved that the conflict was a misreading of §43 (angle = topic), leaving one genuinely new pattern here and a calibration to §43. Prose/correspondence-scoped per Craig — email and Signal are prose, not publish artifacts. |