docs(commits): add Voice and Focus, expand humanizer checklist

Added a new Voice and Focus section between Commit Message Format and Review and Publish. It covers three rules that kept coming up in practice. Write in the user's voice — first person fits, and "This PR introduces X" reads as press-release self-narration. Focus on what was wrong and what was corrected, not the mechanics. Don't stack three or more type signatures or API names in a single sentence.

Also extended the post-humanizer checklist in both the commit-message and PR-description flows. Items (c) "prefer contractions" and (d) "break up long sentences" now sit alongside the existing (a) "rewrite dev-jargon" and (b) "replace semicolons". Uncontracted English reads stiff in short prose, and stacked-clause sentences read easier split on a conjunction.

1 files changed, 29 insertions, 2 deletions

diff --git a/claude-rules/commits.md b/claude-rules/commits.md
index b8707c1..0c17e9d 100644
--- a/claude-rules/commits.md
+++ b/claude-rules/commits.md
@@ -59,6 +59,33 @@ surfaced," "flagged by reviewer"). Reviewers and future archaeologists
 want the what and the why; how you got there belongs in the PR
 discussion, not the commit.
 
+## Voice and Focus
+
+Applies to commit bodies, PR descriptions, and any longer-form prose in
+PR comments.
+
+Write in the user's voice. First person when it fits ("I added X", "I
+retyped Y") reads like a person making a change. "This PR introduces X"
+or "This change restores Y" read as press-release self-narration. The
+commit *is* the change — don't announce it. When another author's prior
+work is the subject, name them ("Kostya's PR #116 did X"); otherwise
+skip the self-reference.
+
+Focus on what was wrong and what was corrected. Not the mechanics.
+Readers skimming `git log` or a PR want the before-state, the
+after-state, and the reason. They don't need a TypeScript-variance
+lesson, a compiler-inference walkthrough, or a trip through an API's
+internals. Keep the "why" to one sentence unless a subtle invariant
+genuinely needs more.
+
+Don't stack technical terms. A sentence that chains three or more type
+signatures, API names, or compiler concepts reads as a jargon wall.
+Break it into shorter sentences and translate to reader-facing
+language. "The mock returns `Promise<Mission>`, so the resolver's
+argument is `Mission`, not `unknown`" beats the full inference chain
+that produces that signature. Keep the terms a reader will grep for,
+drop the ones that name compiler internals.
+
 ## Review and Publish
 
 Commits and PRs are team-visible, permanent, and hard to amend once shared
@@ -96,7 +123,7 @@ enough to skip review" exemption on top of it.
 
 1. Write the proposed message to `/tmp/commit-<short-slug>.md`.
 2. Open it in the user's editor (e.g. `emacsclient -n /tmp/commit-<short-slug>.md`).
-3. Run the `humanizer` skill on the file. Always — commit messages get the same prose-review treatment as PR descriptions. After humanizing, re-scan the output and (a) 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, and (b) replace semicolons with either a period or a comma. Few engineers use semicolons in prose. They make the writing feel unnecessarily literary.
+3. Run the `humanizer` skill on the file. Always — commit messages get the same prose-review treatment as PR descriptions. After humanizing, re-scan the output and (a) 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, (b) replace semicolons with either a period or a comma, (c) prefer contractions ("it's", "that's", "don't", "we're") over their expanded forms, and (d) 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.
 4. Stop and tell the user the draft is open for review. Wait for explicit approval.
 5. After approval, commit with `git commit -F /tmp/commit-<short-slug>.md`.
 
@@ -107,7 +134,7 @@ enough to skip review" exemption on top of it.
    ticket and PR are cross-linked. If there is no ticket, state that
    explicitly ("Linear: n/a") so reviewers know it was considered.
 3. Open it in the user's editor (e.g. `emacsclient -n /tmp/pr-<ticket-or-slug>.md`).
-4. Run the `humanizer` skill on the file. After humanizing, re-scan for dev-jargon fragments and rewrite them as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling. Replace semicolons with periods or commas. Few engineers use semicolons in prose.
+4. Run the `humanizer` skill on the file. After humanizing, re-scan for dev-jargon fragments and rewrite them as plain, brief, complete sentences a low- or mid-level engineer who is not a native English speaker can read without stumbling. Replace semicolons with periods or commas. Few engineers use semicolons in prose. Prefer contractions ("it's", "that's", "don't", "we're") over their expanded forms. Uncontracted English reads stiff in a short prose body. 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.
 5. Stop and tell the user the draft is open for review. Wait for explicit approval.
 6. After approval, split the file on the first blank line and pass the title
    and body to `gh pr create --title "..." --body "$(tail -n +3 <file>)"` (or