From 5bee32b3e11dfc8fa3eefa589a8fc18932abaa79 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Thu, 7 May 2026 09:32:39 -0500 Subject: 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. --- claude-rules/commits.md | 47 ++++++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 25 deletions(-) (limited to 'claude-rules') diff --git a/claude-rules/commits.md b/claude-rules/commits.md index d059b9c..b485506 100644 --- a/claude-rules/commits.md +++ b/claude-rules/commits.md @@ -249,45 +249,42 @@ enough to skip review" exemption on top of it. **For commit messages:** 1. Write the proposed message to `/tmp/commit-.md`. -2. Run the `humanizer` skill on the file. Always — commit messages get the same prose-review treatment as PR descriptions. -3. Apply the personal-style passes in order on the humanized output: (a) rewrite the body in first person as if it's coming from me — "I added a test for...", "I missed the X branch", "I kept Y because..." — instead of impersonal third-person ("Add...", "The change adds...", "This PR introduces..."). The subject line stays imperative per Conventional Commits. Skip the first-person rewrite only when the body is purely mechanical (a chore bump, a typo fix) and the subject alone carries the message; (b) rewrite dev-jargon fragments ("Empty X throws", "Hard throw not a clamp", "all green") as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling; (c) replace semicolons with either a period or a comma; (d) prefer contractions ("it's", "that's", "don't", "we're") over their expanded forms; (e) break up long sentences. Few engineers use semicolons in prose — they make the writing feel unnecessarily literary. Uncontracted English reads stiff in a short prose body unless a negation or emphasis needs the weight. A sentence that stacks three or four clauses with commas and conjunctions reads easier as two or three shorter ones. If you can split it on a conjunction ("so", "and", "but") without losing meaning, split it. Also re-check the colleague-tone framing in *Voice and Focus* — the message should read like one engineer talking to another. -4. Print the final draft inline in the terminal. Every line, exactly as it'll be committed. No truncation, no summary. Name the passes that ran (e.g. "humanizer + first-person + jargon + semicolons + contractions + sentence-split — all applied"). -5. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default — print first, edit only if asked. +2. Run `/voice personal` on the file. Always. The skill walks 39 patterns covering humanizer's signs of AI writing, universal good-writing rules (Strunk & White, Orwell, Plain English, Garner), and the personal voice patterns (first-person rewrite, semicolons → periods/commas, contractions, sentence-split on conjunctions, felt-experience cut, sentence-fragment rewrite, terse cut for rhetorical padding, public-artifact scope flag). The commit subject line stays imperative per Conventional Commits — `/voice personal` rewrites the body, not the subject. Skip the pass for purely mechanical commits (a chore version bump, a typo fix) where the subject alone carries the message. +3. Print the final draft inline in the terminal. Every line, exactly as it'll be committed. No truncation, no summary. State that the skill ran (e.g. "/voice personal — 39 patterns walked"). If pattern #39 (public-artifact scope) flagged anything, surface those warnings; the user resolves them manually. +4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default — print first, edit only if asked. - **Approve** → commit with `git commit -F /tmp/commit-.md`. - - **Request changes** → make them, re-run `humanizer`, re-apply the personal-style passes, re-print inline, ask again. + - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again. - **Open in editor** → only if the user asks. `emacsclient -n /tmp/commit-.md`. After the editor closes, re-read the file, re-print the contents inline, and ask again. **For PR descriptions:** 1. Write the title as line 1 and the body below it to `/tmp/pr-.md`. **Title format:** ` ()` — the ticket ID goes at the end in parentheses (e.g. `refactor: remove dead if-count-is-not-None check in admin (SE-289)`). If there is no ticket, omit the parenthetical. The body must also include a `Linear: []()` line so Linear's GitHub integration auto-cross-links the PR to the ticket. If there is no ticket, state that explicitly ("Linear: n/a") so reviewers know it was considered. -2. Run the `humanizer` skill on the file. -3. Apply the personal-style passes in order on the humanized output: (a) rewrite the body in first person as if it's coming from me — "I added X", "I missed Y", "I kept Z because..." — instead of impersonal third-person ("Add...", "The change adds...", "This PR introduces..."). The PR title stays imperative per Conventional Commits. Skip the first-person rewrite only when the body is purely mechanical and the title alone carries the message; (b) rewrite dev-jargon fragments as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling; (c) replace semicolons with periods or commas — few engineers use semicolons in prose, they make the writing feel unnecessarily literary; (d) prefer contractions ("it's", "that's", "don't", "we're") over their expanded forms — uncontracted English reads stiff in a short prose body; (e) break up long sentences. A sentence that stacks three or four clauses with commas and conjunctions reads easier as two or three shorter ones. If you can split it on a conjunction ("so", "and", "but") without losing meaning, split it. Also re-check the colleague-tone framing in *Voice and Focus*. -4. Print the final draft inline in the terminal. Title on line 1, blank line, then body — exactly as it'll be posted. Name the passes that ran. -5. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. - - **Approve** → continue to step 6. - - **Request changes** → make them, re-run `humanizer`, re-apply the personal-style passes, re-print inline, ask again. +2. Run `/voice personal` on the file. The PR title stays imperative per Conventional Commits — `/voice personal` rewrites the body, not the title. +3. Print the final draft inline in the terminal. Title on line 1, blank line, then body — exactly as it'll be posted. State that the skill ran. Surface any pattern #39 (public-artifact scope) warnings. +4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. + - **Approve** → continue to step 5. + - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again. - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr-.md`. After the editor closes, re-read the file, re-print inline, ask again. -6. Split the file on the first blank line and pass the title and body to `gh pr create --title "..." --body "$(tail -n +3 )"` (or a heredoc) so formatting is preserved. Add `--reviewer ` in the same call when you already know who should review. -7. Request reviewers on the new PR if you didn't pass `--reviewer` at create time. Use `gh pr edit --add-reviewer `. If the repo has a `CODEOWNERS` file, GitHub auto-suggests based on touched paths. Still issue the explicit request so the reviewer gets notified. Pick reviewers per the team's convention for the area touched (often documented in the per-repo `CLAUDE.md`). For follow-up PRs, consider tagging the parent PR's author if their context would help. PRs without a human reviewer request stall — "checks passed" is not a substitute for review. -8. After `gh pr create` returns a URL, post a comment on the linked Linear ticket with the PR URL (use the Linear MCP `save_comment` tool, or open the ticket manually if MCP is unavailable). This closes the ticket→PR direction of the cross-link. -9. Move the Linear ticket to the "Dev Review" status (use `save_issue` with the Dev Review state ID, or the Linear UI). The ticket should not remain "In Progress" once a PR is open against it. +5. Split the file on the first blank line and pass the title and body to `gh pr create --title "..." --body "$(tail -n +3 )"` (or a heredoc) so formatting is preserved. Add `--reviewer ` in the same call when you already know who should review. +6. Request reviewers on the new PR if you didn't pass `--reviewer` at create time. Use `gh pr edit --add-reviewer `. If the repo has a `CODEOWNERS` file, GitHub auto-suggests based on touched paths. Still issue the explicit request so the reviewer gets notified. Pick reviewers per the team's convention for the area touched (often documented in the per-repo `CLAUDE.md`). For follow-up PRs, consider tagging the parent PR's author if their context would help. PRs without a human reviewer request stall — "checks passed" is not a substitute for review. +7. After `gh pr create` returns a URL, post a comment on the linked Linear ticket with the PR URL (use the Linear MCP `save_comment` tool, or open the ticket manually if MCP is unavailable). This closes the ticket→PR direction of the cross-link. +8. Move the Linear ticket to the "Dev Review" status (use `save_issue` with the Dev Review state ID, or the Linear UI). The ticket should not remain "In Progress" once a PR is open against it. **For PR review comments and replies (review verdicts, threaded discussion, follow-up notes on someone else's PR or your own):** 1. Write the proposed comment to `/tmp/pr--comment.md` (or `/tmp/pr--comment.md` if the ticket ID is clearer). -2. Run the `humanizer` skill on the file. Always. -3. Apply the personal-style passes in order on the humanized output: (a) rewrite in first person as if it's coming from me — "I think...", "I tried X but...", "I'd rather..." — instead of impersonal third-person ("The change does...", "It seems..."). Comments are directed at a specific person, the voice should be mine, not a generated narrator's; (b) rewrite dev-jargon fragments as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling; (c) replace semicolons with periods or commas; (d) prefer contractions ("it's", "that's", "don't", "we're") over their expanded forms; (e) break up long sentences on conjunctions ("so", "and", "but"). The *Voice and Focus* rules — especially the colleague-tone framing — matter the most here. The comment is directed at a specific person who will reply, and the thread is public. -4. Print the final draft inline in the terminal. Name the passes that ran. -5. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. - - **Approve** → continue to step 6. - - **Request changes** → make them, re-run `humanizer`, re-apply the personal-style passes, re-print inline, ask again. +2. Run `/voice personal` on the file. Always. The *Voice and Focus* rules — especially the colleague-tone framing — matter the most here. The comment is directed at a specific person who will reply, and the thread is public. +3. Print the final draft inline in the terminal. State that the skill ran. Surface any pattern #39 warnings. +4. Ask: approve, request changes, or open in editor. Wait for an explicit answer. Do not open the file in `emacsclient` (or any editor) by default. + - **Approve** → continue to step 5. + - **Request changes** → make them, re-run `/voice personal`, re-print inline, ask again. - **Open in editor** → only if the user asks. `emacsclient -n /tmp/pr--comment.md`. After the editor closes, re-read the file, re-print inline, ask again. -6. Post with the `gh` command that matches the comment type: +5. Post with the `gh` command that matches the comment type: - Review-shaped comment (the reviewer's overall verdict on the PR): `gh pr review --comment --body-file /tmp/pr--comment.md` (use `--approve` or `--request-changes` in place of `--comment` when formally approving or blocking). - Issue-thread comment (general PR discussion, not a formal review): `gh pr comment --body-file /tmp/pr--comment.md`. - Inline code comment pinned to a specific line/hunk: no direct `gh` flag — use `gh api /repos///pulls//comments -F body=@/tmp/pr--comment.md -F commit_id=... -F path=... -F line=...`. -7. Verify the comment landed. `gh api /repos///pulls//reviews` for review-shaped comments, `gh api /repos///issues//comments` for issue-thread comments. -8. **Notify the PR author on Slack** (review-shaped comments only — `--approve` or `--request-changes`). After the review posts, send a one-line Slack message to channel `C0AM2MWHCJU` via the `slack-deepsat` MCP. No humanizer or personal-style passes — the message is short and templated. Two cases: +6. Verify the comment landed. `gh api /repos///pulls//reviews` for review-shaped comments, `gh api /repos///issues//comments` for issue-thread comments. +7. **Notify the PR author on Slack** (review-shaped comments only — `--approve` or `--request-changes`). After the review posts, send a one-line Slack message to channel `C0AM2MWHCJU` via the `slack-deepsat` MCP. No `/voice personal` pass — the message is short and templated. Two cases: - Approved: `<@author-slack-id> Approved PR #N.\n` - Changes requested: `<@author-slack-id> Changes Requested PR #N\n` Replace `#N` with the PR number and `` with the GHE URL of the PR. Always lead with an `<@author-slack-id>` mention so the engineer who owns the merge decision gets pinged — the message is useless without it. Resolve the Slack user ID via the slack-deepsat `users_search` tool using the PR author's name or email. The URL goes on its own line, immediately after the message. If the MCP doesn't have a post-message tool registered (for example, in a project where the Slack MCP is read-only), surface that to the user and skip the post — don't fall back to a different channel or asking the user to paste it. @@ -301,7 +298,7 @@ conversation (e.g. "commit this as `chore: bump version`", "reply just `/review-code` in Step 1 still runs when it applies; Phase 0 of that skill handles trivial diffs, and acknowledgment-only replies don't need it at all. -**Multi-pass gate.** Each of the three subflows above runs `humanizer` and five personal-style passes (first-person voice, jargon rewrite, semicolon swap, contractions, sentence split) before printing the draft. All six are mandatory — the printed draft must have been through every one. When the user asks mid-flow for "both passes" or "all the passes" or just "the humanizer step" on an in-progress draft, that means re-run *every* pass — not just the first or a representative subset. Always name the passes that ran when announcing the printed draft (e.g. "humanizer + first-person + jargon + semicolons + contractions + sentence-split — all applied"). Skipping a pass without flagging it is a defect. +**Single-skill gate.** Each of the three subflows above runs `/voice personal` before printing the draft. The skill walks 39 patterns in one editorial review — humanizer's 25 signs of AI writing plus 6 universal good-writing patterns plus 8 personal-only patterns. Running it is mandatory; the printed draft must have been through it. When the user asks mid-flow for "the voice pass" on an in-progress draft, that means re-run the full 39-pattern walk in personal mode — not a subset. Always state that the skill ran when announcing the printed draft (e.g. "/voice personal — 39 patterns walked"). Skipping the pass without flagging it is a defect. ### Hook-level authorization -- cgit v1.2.3