diff options
Diffstat (limited to 'claude-rules')
| -rw-r--r-- | claude-rules/commits.md | 47 |
1 files changed, 22 insertions, 25 deletions
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-<short-slug>.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-<short-slug>.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-<short-slug>.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-<ticket-or-slug>.md`. **Title format:** `<conventional-commit subject> (<TICKET-ID>)` — 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: [<TICKET-ID>](<linear-url>)` 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-<ticket-or-slug>.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 <file>)"` (or a heredoc) so formatting is preserved. Add `--reviewer <user[,user...]>` 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 <N> --add-reviewer <user>`. 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 <file>)"` (or a heredoc) so formatting is preserved. Add `--reviewer <user[,user...]>` 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 <N> --add-reviewer <user>`. 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-<N>-comment.md` (or `/tmp/pr-<ticket>-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-<N>-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 <N> --comment --body-file /tmp/pr-<N>-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 <N> --body-file /tmp/pr-<N>-comment.md`. - Inline code comment pinned to a specific line/hunk: no direct `gh` flag — use `gh api /repos/<owner>/<repo>/pulls/<N>/comments -F body=@/tmp/pr-<N>-comment.md -F commit_id=... -F path=... -F line=...`. -7. Verify the comment landed. `gh api /repos/<owner>/<repo>/pulls/<N>/reviews` for review-shaped comments, `gh api /repos/<owner>/<repo>/issues/<N>/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/<owner>/<repo>/pulls/<N>/reviews` for review-shaped comments, `gh api /repos/<owner>/<repo>/issues/<N>/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<pr-url>` - Changes requested: `<@author-slack-id> Changes Requested PR #N\n<pr-url>` Replace `#N` with the PR number and `<pr-url>` 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 |