aboutsummaryrefslogtreecommitdiff
path: root/voice/references
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-06-10 10:12:22 -0500
committerCraig Jennings <c@cjennings.net>2026-06-10 10:12:22 -0500
commit571669583e634a90f9c96e7073d5e91658e1119c (patch)
tree4558945c8b812b4b075596382655af0190834ee9 /voice/references
parenta19db36005b527c51a55b0e6eb39a49ecd3b6d9f (diff)
downloadrulesets-571669583e634a90f9c96e7073d5e91658e1119c.tar.gz
rulesets-571669583e634a90f9c96e7073d5e91658e1119c.zip
feat(voice): expand skill to 45 patterns with attestation receipts and artifact budgets
Two patterns kept failing in practice despite being documented (#40 praise asymmetry and the #38 terse cut), so I made the walk verifiable and closed the content gap behind tangled review text. The high-recurrence set (#13, #37, #38, #40, #42) now gets per-pattern attestation receipts. The anti-AI audit runs after the terse pass so the audited text is the text that ships. Short personal-mode artifacts get a compact output format, and a write-back step puts the voiced text in the file the publish flow posts from. Four patterns are new: #42 finding stems (one claim per sentence in review findings), #43 single-sentence paragraph cadence, #44 parenthetical asides, #45 declarative register marker. #37 exempts verdict formulas. #40 covers verification narration. #13 and #33 carry the self-discipline framing. A per-artifact budgets table makes terse a checkable budget instead of an adjective. The profile gains paired entries with the approved worked examples, and commits.md plus no-approvals.org drop hardcoded pattern counts so the next addition doesn't re-drift them.
Diffstat (limited to 'voice/references')
-rw-r--r--voice/references/voice-profile.org177
1 files changed, 171 insertions, 6 deletions
diff --git a/voice/references/voice-profile.org b/voice/references/voice-profile.org
index ab37ba1..088f0eb 100644
--- a/voice/references/voice-profile.org
+++ b/voice/references/voice-profile.org
@@ -110,6 +110,8 @@ These two rules are still valuable. Em-dashes and semicolons both read cleaner w
* Suggested deltas
+*All six deltas landed 2026-06-10* via the voice-skill revision from the work-project session: 1 and 2 are in the §13/§33 rule lines and entries, 3 is the §7 soft-flag, 4-6 became patterns §43-§45. The list is kept as the record of what was proposed on 2026-05-29.
+
Six concrete edits to =voice/SKILL.md=, all of which can land independently:
1. *#13 (Em-Dash).* Drop the "LLMs use em dashes more than humans" framing in the personal-mode section. Restate the zero-tolerance rule as self-discipline ("Craig's published voice drops em-dashes by choice"), not habit-reflection. Cite: corpus rate 3.49/1000, AI-comparable.
@@ -134,7 +136,7 @@ Six concrete edits to =voice/SKILL.md=, all of which can land independently:
* 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.
+All patterns are entered below per the pairing rule above, §1 through §45, matching SKILL.md's numbering.
** §1 Undue Emphasis on Significance, Legacy, and Broader Trends
@@ -485,7 +487,7 @@ Prose + personal modes: zero-tolerance.
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.
+Craig's published voice drops em-dashes by choice: they read cleaner absent from short imperative-leaning prose and their overuse is a common AI tell (LLMs use em dashes more than the median human writer, mimicking "punchy" sales writing). The rule is chosen self-discipline, not a reflection of his pre-rule habit — the corpus shows he used them regularly in commit bodies.
*** Basis
Phase 1 corpus (git commits, 128k words): 3.49 em-dashes per 1000 words. Comparable to AI-generated prose. Phase 2 corpus reveals a sharp register split: personal email 0.28 per 1000, work email 2.05, PR descriptions 0.62, PR review comments 0.00. Em-dashes are concentrated in commit prose, almost absent from email and PR review prose. The zero-tolerance rule in prose and personal modes mostly enforces what is already true for non-commit registers. The rule still earns its place because commit prose is the high-volume register where the AI-tell em-dash habit shows up. Self-discipline, not habit-reflection, for the commit register specifically.
@@ -505,6 +507,7 @@ The term is primarily promoted by Dutch institutions, not by the people themselv
- 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.
+- 2026-06-10: the self-discipline reframing (a "Suggested deltas" item from 2026-05-29, never applied) moved from the findings section into the entry proper and into the SKILL.md rule line. Craig's call, from the work-project session.
** §14 Overuse of Boldface
@@ -1074,10 +1077,10 @@ Impersonal third-person construction in a publish-artifact body where first-pers
Prose and personal modes. General mode keeps semicolons because academic and literary registers use them legitimately.
*** Rule
-Replace semicolons with a period (split into two sentences) or a comma (when the clauses are tightly coupled) in Craig's authored prose: emails, documents, working notes, commit-message bodies, PR descriptions, PR review comments. A formal long-form document can keep the semicolon, but the default is to split.
+Replace semicolons with a period (split into two sentences) or a comma (when the clauses are tightly coupled) in Craig's authored prose: emails, documents, working notes, commit-message bodies, PR descriptions, PR review comments. A formal long-form document can keep the semicolon, but the default is to split. Chosen self-discipline, not habit-reflection.
*** Problem
-Craig's voice avoids semicolons. They make the writing feel unnecessarily literary. The period-split usually reads better, and dropping semicolons removes one common AI tell.
+Craig's published voice drops semicolons by choice. They make the writing feel unnecessarily literary, the period-split usually reads better, and dropping them removes one common AI tell. The rule overrides his pre-rule habit rather than codifying one — the corpus shows he used semicolons regularly in commit prose.
*** Basis
Corpus-measured across registers (2026-05-29): semicolons run 3.16 per 1000 words in git commits, 0.64 in personal email, 0.26 in work email, 0.62 in PR descriptions, 0.00 in PR review comments. Same register split as em-dashes (§13). Semicolons are concentrated in commit prose; conversational prose almost never uses them. The rule mostly enforces what is already true for non-commit registers. It earns its place because commit prose is the register where Craig's habit and the AI-tell pattern overlap.
@@ -1099,6 +1102,7 @@ Semicolons in prose Craig authors: emails, documents, working notes, commit-mess
- Original SKILL.md entry: semicolon to period or comma in Craig's authored prose.
- 2026-05-29 (commit =c3cf9a5=): basis note added with corpus measurement reframing the rule as self-discipline.
- 2026-05-29: migrated to this file as the canonical home per the pairing rule.
+- 2026-06-10: the self-discipline reframing (a "Suggested deltas" item from 2026-05-29, never applied) moved from the findings section into the entry proper and into the SKILL.md rule line. Craig's call, from the work-project session.
** §34 Contractions
@@ -1199,7 +1203,7 @@ Phrases that tell the reader how the change will feel or how often the writer wi
Prose and personal modes. General mode keeps the softer §30, which exempts more, because the strong "every sentence" rule is Craig's voice and should not be imposed on third-party text.
*** Rule
-Rewrite every sentence fragment inside a prose paragraph in Craig's authored text as a complete sentence with subject and verb. Bullets and headings can stay fragments.
+Rewrite every sentence fragment inside a prose paragraph in Craig's authored text as a complete sentence with subject and verb. Bullets and headings can stay fragments. Exemption: verdict formulas in PR review summaries ("Approving.", "Requesting changes.", "Approved.") are house style and stay — rewriting them imposes the rule where Craig's calibrated voice already decided otherwise.
*** Problem
Bullet shorthand leaking into running prose ("Two changes." "Fix incoming." "Body as decision log.") reads as bullet-list notes pasted into a paragraph. Every prose sentence needs a subject and a verb in prose and personal modes.
@@ -1223,6 +1227,7 @@ Sentence fragments inside prose paragraphs in any text Craig authors: an email,
*** History
- Original SKILL.md entry: sentence-fragment rewrite for Craig's authored prose.
- 2026-05-29: migrated to this file as the canonical home per the pairing rule.
+- 2026-06-10: verdict-formula exemption added. The skill survived in practice by being selectively ignored on "Approving." / "Requesting changes." / "Approved.", and selective ignoring is the same muscle that skips real patterns. Documenting the exception removes one standing occasion for judgment-override. Craig's call, from the work-project session.
** §38 Terse Cut — Omit Needless Words
@@ -1309,6 +1314,8 @@ On an approve summary: praise plus verdict, nothing else. Cut any clause that de
On a finding or change-request: always give the why, gently and briefly. Not "Move this to a helper." but "I'd pull this into one helper — three copies of the same rule means the next change has to touch all three, and missing one brings the bug back."
+Verification narration is the same defect as justified praise. "I traced X and it's safe because..." pads the compliment with the reviewer's homework. Tracing the code is the reviewer's job, not content for the comment — if verification found a problem, the problem gets the words; if it found nothing, it gets zero words.
+
*** Problem
Praise and correction call for opposite treatment. The author already knows why their good change is good, so justifying praise reads as flattery. Correction is the reverse. Behavior only changes when the reason lands, so a finding, change-request, or inline coaching note must always explain the why. And the why is delivered gently, the way a kind coach or mentor would.
@@ -1325,12 +1332,23 @@ Nice clean migration, the provider mocks and the Normal/Boundary/Error cases are
Clean migration. Approving. One note inline: I'd rename `x` to `provider` — it reads as a generic placeholder and the next person won't know it's the resolved provider without tracing it.
#+end_example
+*** Before (verification narration)
+#+begin_example
+All three fixes look right. I traced useMapActions and the unmount cleanup is safe because the hook returns a memoized object, and the provider wraps the whole app so neither call site lands on the no-op path.
+#+end_example
+
+*** After
+#+begin_example
+All three fixes are clean and well-aimed.
+#+end_example
+
*** Detection
-In a PR review summary or comment: a praise clause that explains why the good thing is good, or a finding or change-request that states what to fix without saying why.
+In a PR review summary or comment: a praise clause that explains why the good thing is good, a praise clause followed by the verification work that supports it, or a finding or change-request that states what to fix without saying why.
*** History
- Original SKILL.md entry: praise-versus-correction asymmetry for PR review.
- 2026-05-29: migrated to this file as the canonical home per the pairing rule.
+- 2026-06-10: verification-narration variant added after the third recurrence — a review draft praised a fix and then narrated the verification supporting the praise (the #236 draft). Added to the SKILL.md rule line and the high-recurrence attestation set. Craig's call, from the work-project session.
** §41 No Emphasis Formatting
@@ -1362,3 +1380,150 @@ Bold (=**...**=), italic (=*...*= or =_..._=), or underscore-wrapped words used
*** History
- Original SKILL.md entry: no emphasis formatting for Craig's authored prose.
- 2026-05-29: migrated to this file as the canonical home per the pairing rule.
+
+** §42 Finding Stems — One Claim Per Sentence
+
+*** Modes
+Personal mode only. General and prose skip because the rule assumes a PR review finding.
+
+*** Rule
+A PR review finding is built from clean stems, each a straightforward sentence carrying one claim: (1) where the bug is, (2) the way(s) to fix it, (3) why that's better. Cut context sentences that don't change what the author does next (ticket history, design archaeology). Rewrite the anti-pattern shapes: hedged gerund chains ("the real bug looks like the model emitting a partial set"), compressed trade-off clauses ("I'd rather X, or Y, than lose Z"), multi-claim sentences chained through so-clauses or "and", and fixes buried after a mid-sentence colon.
+
+*** Problem
+Craig named detangling overly complex or overly wordy Claude-drafted PR review text as THE key issue he fights in PR reviews, and the reason he gates every review draft. The tangles passed all 41 then-existing patterns — §38 shortens but doesn't untangle; a sentence can be terse and still carry three claims. §40 governs praise; this governs how finding text is constructed.
+
+*** Basis
+Observation-derived from PR #233 (2026-06-10): a review comment shipped with hedged gerund chains and compressed trade-off clauses that cleared the full walk. The three Before/After pairs below are Craig-approved rewrites from that PR.
+
+*** Before (multi-claim opener + context sentence)
+#+begin_example
+POST fixes the wipe but it's additive: it no-ops on an empty list and never removes, so "cancel all partners" and any de-selection silently stop working. PUT came from SE-195 so the confirm could reconcile the full set. The real bug is upstream: on a new tasking the confirm emits only the new provider, not the full set. Fix that, or merge with the mission's current providers before the PUT. Either way removal keeps working.
+#+end_example
+
+*** After
+#+begin_example
+POST is additive: it no-ops on an empty list and never removes. That breaks "cancel all partners" and any de-selection. The real bug is upstream: on a new tasking the confirm emits only the new provider, not the full set. Fix that, or merge with the mission's current providers before the PUT, and removal keeps working.
+#+end_example
+
+The SE-195 context sentence is cut because it doesn't change the author's next action.
+
+*** Before (hedged gerund chain + compressed trade-off — the calibration case Craig pulled up)
+#+begin_example
+The real bug looks like the model emitting a partial set on a new tasking. I'd rather fix what the confirm emits, or merge client-side before the PUT, than lose removal.
+#+end_example
+
+*** After (where / fix / payoff)
+#+begin_example
+The real bug is upstream: on a new tasking the confirm emits only the new provider, not the full set. Fix that, or merge with the mission's current providers before the PUT. Either way removal keeps working.
+#+end_example
+
+*** Before (claims joined with "and"; fix buried after a mid-sentence colon)
+#+begin_example
+The prefix check catches any message starting with "confirm ", and the options block exists so the LLM can resolve "number 2" style references. A typed "confirm number 2" loses the list it needs. The card click already sends a self-describing "confirm <id>": pass an explicit parameter through sendAgentMessage and strip only on that path.
+#+end_example
+
+*** After
+#+begin_example
+The prefix check strips the options block from any typed message starting with "confirm ", so "confirm number 2" loses the list the LLM needs to resolve it. Strip on the card-click path instead, with an explicit parameter passed through sendAgentMessage. The click already sends a self-describing "confirm <id>", so stripping is safe there.
+#+end_example
+
+*** Detection
+In a PR review finding: a sentence carrying more than one claim (chained through so-clauses, "and", or a mid-sentence colon hiding the fix), a hedged gerund chain where a direct claim belongs, a compressed trade-off clause, or a context sentence that doesn't change the author's next action.
+
+*** History
+- 2026-06-10: created from the PR #233 calibration session. Proposed in the work project's stems handoff, landed via the consolidated voice-skill revision. Included in the high-recurrence attestation set from day one. Craig's call.
+
+** §43 Single-Sentence Paragraph Cadence Is a Feature
+
+*** Modes
+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.
+
+*** 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.
+
+*** 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.
+
+*** Before (a cleanup pass merging short paragraphs)
+#+begin_example
+The build now finishes in half the time, and the cache no longer invalidates on every run, which means the CI queue clears faster too.
+#+end_example
+
+*** After
+#+begin_example
+The build now finishes in half the time.
+
+The cache no longer invalidates on every run, so the CI queue clears faster too.
+#+end_example
+
+*** Detection
+An edit pass that merged short paragraphs, or a draft whose paragraphs each stack multiple shifted angles that would read better broken apart.
+
+*** 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.
+
+** §44 Parenthetical Asides Are Part of the Voice
+
+*** Modes
+Prose and personal modes. General mode skips because third-party text owns its own aside conventions.
+
+*** Rule
+Parentheses for asides, clarifications, and scope-narrowing are Craig's voice. Don't strip them in a cleanup pass. They're also the preferred landing spot for em-dash replacements under §13.
+
+*** Problem
+Generic style passes treat parentheticals as clutter and strip them. For Craig they carry asides, clarifications, and scope-narrowing, and removing them flattens the voice. Protective pattern, like §43.
+
+*** Basis
+Corpus-measured (2026-05-29): 23.07 opening parens per 1000 words across the commit corpus. Heavy parenthetical use is distinctive and consistent.
+
+*** Before (a cleanup pass stripping the aside)
+#+begin_example
+The sync runs on every startup. It skips lockfiles. It also skips build output.
+#+end_example
+
+*** After
+#+begin_example
+The sync runs on every startup (skipping lockfiles and build output).
+#+end_example
+
+*** Detection
+An edit pass that removed parenthetical asides present in the source text, or an em-dash replacement under §13 where parentheses fit better than a comma or period.
+
+*** History
+- 2026-05-29: surfaced by the Phase 1-2 corpus measurement as a "worth adding" trait; filed as suggested delta 5.
+- 2026-06-10: promoted from the suggested-deltas list into a numbered pattern, with the §13 landing-spot note. Craig's call, from the work-project session.
+
+** §45 Declarative Register Marker
+
+*** Modes
+Prose and personal modes, advisory. Flag only; no auto-rewrite. General mode skips.
+
+*** Rule
+Craig's prose is declarative. When a draft contains a rhetorical question, flag it for a second look — it's usually AI rhetoric, not his register. Genuine questions to the reader (a review asking the author's intent, an email asking for a decision) stay.
+
+*** Problem
+AI drafts reach for rhetorical questions ("So what does this mean for the build?") as a transition device. Craig states things; he rarely asks them. A rhetorical question in his voice is a tell, but a genuine question is legitimate content, so the pattern flags rather than rewrites.
+
+*** Basis
+Corpus-measured (2026-05-29): 0.33 question marks per 1000 words across the commit corpus. His prose register is declarative.
+
+*** Before (rhetorical transition flagged)
+#+begin_example
+So what does this change for the deploy flow? The staging gate now runs before the canary, which means a bad build never reaches it.
+#+end_example
+
+*** After
+#+begin_example
+The staging gate now runs before the canary, so a bad build never reaches it.
+#+end_example
+
+*** Detection
+A question mark in a draft in Craig's voice. Flag it; keep genuine questions to the reader, rewrite rhetorical ones as declarative claims.
+
+*** History
+- 2026-05-29: surfaced by the Phase 1-2 corpus measurement as a register marker; filed as suggested delta 6.
+- 2026-06-10: promoted from the suggested-deltas list into a numbered advisory pattern. Craig's call, from the work-project session.