aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-05-22 14:13:37 -0500
committerCraig Jennings <c@cjennings.net>2026-05-22 14:13:37 -0500
commit977b420257bdf1545b1c58d5a6a7202b5f4ec53f (patch)
tree85834b4f30e4af7570c33d301c04813a6654f5ad
parente46174ae7ae443bbc94efcc5cc2059efa2cae5c0 (diff)
downloadrulesets-977b420257bdf1545b1c58d5a6a7202b5f4ec53f.tar.gz
rulesets-977b420257bdf1545b1c58d5a6a7202b5f4ec53f.zip
docs(commands): tighten respond-to-review PR-feedback workflow
Two audit-pass fixes to respond-to-review, plus a stale-reference tidy in respond-to-cj-comments. The Gather step fetched a flat comment list, which misses thread resolution and re-processes feedback that's already settled. It now pulls unresolved review threads via gh api graphql (skipping resolved ones), keeps REST only for top-level conversation comments, and resolves a thread only after the fix is verified. The commit guidance suggested "fix: Address review — [description]", which puts the review process into git log against commits.md and used a non-ASCII dash. It now names the actual fix and leaves the how-it-surfaced detail in the PR thread. respond-to-cj-comments lost a stale "humanizer" mention, since that skill is voice now. Two adjacent audit items came out moot: it no longer embeds an absolute path, and its humanizer/emacsclient fallback was overtaken by the /voice migration and the in-place VERIFY pattern.
-rw-r--r--.claude/commands/respond-to-cj-comments.md2
-rw-r--r--.claude/commands/respond-to-review.md10
2 files changed, 7 insertions, 5 deletions
diff --git a/.claude/commands/respond-to-cj-comments.md b/.claude/commands/respond-to-cj-comments.md
index 67e0497..46ff1bc 100644
--- a/.claude/commands/respond-to-cj-comments.md
+++ b/.claude/commands/respond-to-cj-comments.md
@@ -179,7 +179,7 @@ For **questions**:
For **writing destined for public channels** (commit messages, PR descriptions, PR comments, Slack or email messages, public docs):
-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).
+1. Invoke `/voice personal` on the draft. The skill walks 39 patterns covering the 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).
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`
diff --git a/.claude/commands/respond-to-review.md b/.claude/commands/respond-to-review.md
index d86b1ea..8821b1b 100644
--- a/.claude/commands/respond-to-review.md
+++ b/.claude/commands/respond-to-review.md
@@ -1,5 +1,5 @@
---
-description: Process pending review comments on a PR through five steps (Gather, Evaluate, Respond, Implement, Report). Each comment is verified against the actual codebase before action — restated in your own words, checked for accurate premise, YAGNI-tested if it suggests "more proper" architecture without current consumers, then categorized as correct-and-actionable, correct-but-out-of-scope, debatable, or incorrect. Disagreement is framed with code references rather than opinion. Implementation handles simple fixes first, tests each change individually, commits with conventional messages referencing the review. Final report lists what was implemented, what was deferred to follow-up issues, and what still needs discussion. Use when responding to PR review feedback. Do NOT use for proactively reviewing code (use `/review-code`), for the publish flow itself (use the Review-and-Publish steps in `commits.md`), or when the PR has no review comments yet.
+description: Process pending review comments on a PR through five steps (Gather, Evaluate, Respond, Implement, Report). Each comment is verified against the actual codebase before action — restated in your own words, checked for accurate premise, YAGNI-tested if it suggests "more proper" architecture without current consumers, then categorized as correct-and-actionable, correct-but-out-of-scope, debatable, or incorrect. Disagreement is framed with code references rather than opinion. Implementation handles simple fixes first, tests each change individually, commits with conventional messages that name the fix. Final report lists what was implemented, what was deferred to follow-up issues, and what still needs discussion. Use when responding to PR review feedback. Do NOT use for proactively reviewing code (use `/review-code`), for the publish flow itself (use the Review-and-Publish steps in `commits.md`), or when the PR has no review comments yet.
disable-model-invocation: true
---
@@ -19,8 +19,9 @@ If no PR number is given, check the current branch's open PR for pending review
### 1. Gather the Feedback
-- Fetch review comments using `gh api repos/{owner}/{repo}/pulls/{number}/comments` (for inline review comments) and `gh api repos/{owner}/{repo}/issues/{number}/comments` (for top-level PR conversation comments)
-- Read each comment in full. Group related comments — reviewers often raise connected issues across multiple comments.
+- Fetch *unresolved review threads*, not a flat comment list. Resolution state lives only in the GraphQL API: query `repository.pullRequest.reviewThreads` (with `isResolved` and each thread's comments) via `gh api graphql`, and skip threads already resolved so settled feedback isn't re-processed.
+- Also fetch top-level PR conversation comments via `gh api repos/{owner}/{repo}/issues/{number}/comments` — those aren't threaded and have no resolution state.
+- Read each thread in full and group related ones by the change they request — reviewers often split one concern across several comments.
### 2. Evaluate Each Item
@@ -47,7 +48,8 @@ For each review comment, before implementing anything:
- Address simple fixes first, complex ones after
- Test each change individually — don't batch unrelated fixes into one commit
- Run the full test suite after all changes
-- Commit with conventional messages referencing the review: `fix: Address review — [description]`
+- After a fix is verified, reply on its review thread and resolve it — resolve only after verification, never before, so an unverified change can't quietly close out feedback
+- Commit with conventional messages that name the actual fix (`fix: validate export filename`), not the review that prompted it. What changed and why goes in the commit; how it surfaced belongs in the PR thread, not `git log`.
### 5. Report