diff options
| author | Craig Jennings <c@cjennings.net> | 2026-05-07 09:32:39 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-05-07 09:32:39 -0500 |
| commit | 5bee32b3e11dfc8fa3eefa589a8fc18932abaa79 (patch) | |
| tree | 2829a7ad66b2c30ed38014b03de2117eb7bc8137 /.claude | |
| parent | fd3eda377aee1e797fa4bcf975d656ec25d66bd0 (diff) | |
| download | rulesets-5bee32b3e11dfc8fa3eefa589a8fc18932abaa79.tar.gz rulesets-5bee32b3e11dfc8fa3eefa589a8fc18932abaa79.zip | |
chore: migrate humanizer callers to /voice personal
I switched the three publish subflows in commits.md (commit messages, PR descriptions, PR review comments) from "run humanizer; apply five personal-style passes in order" to a single "run /voice personal" invocation. The new skill walks 39 patterns in one editorial review and absorbs the five passes wholesale, plus four more personal-style additions (felt-experience cut, fragment-in-prose rewrite, terse cut, public-artifact scope flag) and six universal good-writing patterns. The numbered steps in each subflow collapse from 5 to 4 (commits) and 9 to 8 (PRs) since the dedicated personal-style step folds into the voice invocation.
The Multi-pass gate paragraph becomes a Single-skill gate. The mid-flow "all the passes" prompt now means re-run the full 39-pattern walk in personal mode rather than reapplying six discrete steps.
I also updated respond-to-cj-comments.md to invoke /voice personal for public writing and /voice general for the lighter pass on internal notes when wanted, and updated start-work.md's Phase 7 summary to match.
The humanizer skill itself stays in place for now. The next commit removes it.
Diffstat (limited to '.claude')
| -rw-r--r-- | .claude/commands/respond-to-cj-comments.md | 30 | ||||
| -rw-r--r-- | .claude/commands/start-work.md | 4 |
2 files changed, 8 insertions, 26 deletions
diff --git a/.claude/commands/respond-to-cj-comments.md b/.claude/commands/respond-to-cj-comments.md index 35977d1..ba36f6c 100644 --- a/.claude/commands/respond-to-cj-comments.md +++ b/.claude/commands/respond-to-cj-comments.md @@ -1,5 +1,5 @@ --- -description: Scan a target file for inline `cj:` annotations (Craig's in-line questions and instructions; multi-line continuations recognized across most comment markers) and process each via subagent-delegated accuracy. Each item is classified instruction / question / both, then dispatched to an instruction subagent (proposes a file:line patch) or a question subagent (researches with explicit scope, reports answer + evidence + confidence). Main thread reviews proposals before editing — subagents don't write to the source file. Org-mode TODO parents flip to DOING; new content lands under timestamped subheadings one level deeper. Public-facing writing (commits, PRs, Slack, email, public docs) gets a humanizer pass plus `commits.md` voice rules; private writing skips humanizer. Summary lists handled instructions, answered questions with evidence + confidence, follow-ups, unresolved items, and an explicit clean / N-remain verdict. Long summaries (>6-8 items or >500 words) write to `/tmp/` and open in `emacsclient -n`. File paths render as clickable absolute org-mode links. Use when a file accumulates inline `cj:` comments. Do NOT use for general code review (`/review-code`), new work without inline comments, or trivial items. +description: Scan a target file for inline `cj:` annotations (Craig's in-line questions and instructions; multi-line continuations recognized across most comment markers) and process each via subagent-delegated accuracy. Each item is classified instruction / question / both, then dispatched to an instruction subagent (proposes a file:line patch) or a question subagent (researches with explicit scope, reports answer + evidence + confidence). Main thread reviews proposals before editing — subagents don't write to the source file. Org-mode TODO parents flip to DOING; new content lands under timestamped subheadings one level deeper. Public-facing writing (commits, PRs, Slack, email, public docs) gets `/voice personal`; private writing skips the voice pass. Summary lists handled instructions, answered questions with evidence + confidence, follow-ups, unresolved items, and an explicit clean / N-remain verdict. Long summaries (>6-8 items or >500 words) write to `/tmp/` and open in `emacsclient -n`. File paths render as clickable absolute org-mode links. Use when a file accumulates inline `cj:` comments. Do NOT use for general code review (`/review-code`), new work without inline comments, or trivial items. disable-model-invocation: true --- @@ -112,27 +112,9 @@ For **questions**: For **writing destined for public channels** (commit messages, PR descriptions, PR comments, Slack or email messages, public docs): -1. Invoke `/humanizer` on the draft. -2. Apply these voice and attribution rules to the writing you produced (adapted from `/home/cjennings/code/rulesets/claude-rules/commits.md`): +1. Invoke `/voice personal` on the draft. The skill walks 39 patterns covering humanizer's signs of AI writing, universal good-writing rules (Strunk & White, Orwell, Plain English, Garner), and personal voice patterns (first-person rewrite, semicolons → periods/commas, contractions, sentence-split, felt-experience cut, sentence-fragment rewrite, terse cut, public-artifact scope flag). - **No AI attribution, anywhere.** Never include AI, LLM, Claude, or Anthropic attribution in any public-facing text. That means: - - No `Co-Authored-By: Claude` (or Claude Code, or any AI) trailers - - No "Generated with Claude Code" footers or equivalents - - No emojis implying AI authorship - - No references to Claude, Anthropic, LLM, or "AI tool" as a credited contributor - - Strip any attribution a tool or template inserts by default - - **First person where it fits.** When the subject is Craig or a decision he made, use "I". When the subject is a team decision or shared rationale, "we" fits. Name other authors when crediting their work ("Kostya's PR #116 did X"). Avoid third-person press-release voice ("This PR introduces X", "This change restores Y") unless the code or system is the actor. - - **Brief. Terse is fine.** A one-sentence body beats a paragraph saying the same thing. If the subject line covers it, skip the body entirely. Cut every clause that restates what the diff, the card, or the surrounding context already shows. Length isn't a proxy for care. Rhetorical padding ("worth noting", "it's important to understand") always comes out. - - **Kind.** Text directed at a specific person: acknowledge them when it fits, without pouring it on. Frame disagreement as your read ("I think...", "my read was...", "did you mean X?"). Leave room for the other person to have seen something you didn't. A polite question beats a defensive explanation. - - **Plain English.** Complete sentences a low- or mid-level engineer who isn't a native speaker can read without stumbling. Replace semicolons with periods or commas. Prefer contractions ("it's", "that's", "don't", "we're"). Split long sentences on conjunctions ("so", "and", "but") when meaning survives the split. No em-dashes, use regular dashes instead. Em-dashes break in GitHub, Linear, and Slack. - - **Don't stack jargon.** A sentence that chains three or more type signatures, API names, or compiler concepts reads as a wall. Break it into shorter sentences. Keep the terms a reader will grep for, drop the ones that name compiler internals. - -3. Scan the output for AI-attribution tells. If you catch yourself having written any of these, stop, delete, and rewrite: +2. Scan the output for AI-attribution tells. If you catch yourself having written any of these, stop, delete, and rewrite: - `Co-Authored-By: Claude` - `Generated with Claude Code` (with or without the robot emoji) - "Created with Claude Code" @@ -142,7 +124,7 @@ For **writing destined for public channels** (commit messages, PR descriptions, If the writing will be *posted* (not just saved as a draft), follow the Review and Publish flow in `commits.md` — draft to `/tmp/`, open in `emacsclient -n`, wait for Craig's explicit approval before posting. -**Private writing** (todo.org entries, session-context.org, scratch notes, internal rulesets) skips the humanizer pass. Voice rules still apply where relevant, but the overhead of a draft-and-approve cycle is not warranted. +**Private writing** (todo.org entries, session-context.org, scratch notes, internal rulesets) skips `/voice personal`. Use `/voice general` for the AI-detection + universal-good-writing passes when relevant, but the overhead of a draft-and-approve cycle is not warranted for internal notes. ### 5. Report @@ -201,14 +183,14 @@ Confirm the cleanup by re-scanning the file after removals. If any `cj:` line su - **Don't guess.** If a question needs verification and verification isn't possible, say so. Surface unknowns rather than fabricate. - **Preserve the file.** Don't reformat surrounding lines. Don't reorder tasks. Touch only what the comment asks for, plus the comment's own removal. - **The user reads the summary, not the process log.** Write summaries that are directly useful. -- **Public writing gets humanizer + commits.md. Private writing doesn't.** Don't over-process internal notes. +- **Public writing gets `/voice personal`. Private writing doesn't.** Don't over-process internal notes. ## Anti-patterns - Handling complex `cj:` items inline in the main thread instead of subagenting. - Batching unrelated `cj:` comments into one giant subagent prompt. - Removing a `cj:` comment before the user has seen the answer in the summary. -- Skipping the humanizer + commits.md pass on public-facing writing because it "looked fine already." +- Skipping the `/voice personal` pass on public-facing writing because it "looked fine already." - Guessing on a question instead of spawning a research subagent. - Letting a subagent edit the source file directly — review surface loss. diff --git a/.claude/commands/start-work.md b/.claude/commands/start-work.md index bf32801..2224490 100644 --- a/.claude/commands/start-work.md +++ b/.claude/commands/start-work.md @@ -236,9 +236,9 @@ If deviations are significant, the user may want to loop back and revise the app Follow `commits.md` exactly. Summary of the flow: 1. Run `/review-code --staged` before each commit, or `/review-code` on the whole branch before the PR. Block on Critical or Important findings. -2. Draft the commit message to `/tmp/commit-<slug>.md`. Run `humanizer`. Apply the plain-English pass. Replace semicolons. Stop for approval. +2. Draft the commit message to `/tmp/commit-<slug>.md`. Run `/voice personal`. Stop for approval. 3. After approval, commit. -4. Draft the PR body to `/tmp/pr-<ticket-or-slug>.md`. Body must include a `Linear:` or equivalent cross-link line. Run `humanizer`. Apply the plain-English pass. Replace semicolons. Stop for approval. +4. Draft the PR body to `/tmp/pr-<ticket-or-slug>.md`. Body must include a `Linear:` or equivalent cross-link line. Run `/voice personal`. Stop for approval. 5. After approval, push and run `gh pr create`. 6. Post the PR URL back to the Linear ticket, GitHub issue, or todo.org entry. 7. Move the Linear or GitHub status to **Dev Review**. Todo.org has no equivalent. Leave the todo.org entry as `DOING` until the PR merges. |
