From 579475365693bb75c7d948b5261e65a736d15539 Mon Sep 17 00:00:00 2001 From: Jeremy Drouillard Date: Tue, 24 Mar 2026 15:44:06 -0700 Subject: [PATCH] Add session planning and comment guardrails to code-review-assist skill When invoked without a specific PR, the skill now scopes the session by discovering open PRs, unreviewed merges, and previously reviewed PRs with new activity (catches contributors who push updates without re-requesting review). Also codifies two comment workflow rules: all drafts must be presented before posting, and approvals default to no body unless asked. Co-Authored-By: Claude Opus 4.6 --- .claude/skills/code-review-assist/SKILL.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.claude/skills/code-review-assist/SKILL.md b/.claude/skills/code-review-assist/SKILL.md index e41bf54e49..ed7daf1463 100644 --- a/.claude/skills/code-review-assist/SKILL.md +++ b/.claude/skills/code-review-assist/SKILL.md @@ -13,6 +13,19 @@ Act as a senior review partner — not a replacement reviewer. Help the user und The `code-reviewer` agent runs autonomously and checks for best practices, security patterns, and conventions. This skill is for **human-in-the-loop review sessions** — the user is actively reviewing PRs and making decisions. Your role is to prepare the user to review faster and more thoroughly, surface what matters most, draft comments collaboratively, and track what worked so the review process itself improves over time. +## Session Planning + +When invoked without a specific PR, start by scoping the session: + +1. **Discover PRs**: Use GitHub to find (a) open PRs requesting the user's review, (b) PRs merged since their last review session that they haven't reviewed yet, and (c) open PRs the user has previously reviewed that have new pushes or comments since their last review (contributors may push updates without re-requesting review). +2. **Present the list**: Show each PR with title, author, and a risk estimate (high/medium/low based on files changed, area of codebase, and change size). +3. **Ask the user**: + - Which PRs to include — all open, all merged, or a subset? + - Preferred review order — chronological, highest-risk-first, or by author/area? +4. **Track coverage**: At the end of the session, report which PRs were reviewed, skipped, or deferred so nothing falls through the cracks. + +If a specific PR is provided as an argument, skip session planning and go directly to the review. + ## Instructions When the user shares a code change (diff, PR, or code snippet) for review, structure your response in the sections below. @@ -89,6 +102,8 @@ When drafting review comments, use [conventional comments](https://conventionalc Calibrate severity aggressively: a method that silently no-ops and breaks functionality for some implementations is a **blocker**, not a suggestion. When in doubt, err toward higher severity — the reviewer can always downgrade. +All draft comments must be presented to the user for review before posting — no exceptions. Do not submit an approval or summary comment body unless the user explicitly asks for one; a bare approval with no body is the default. + ## Code Suggestions When suggesting code changes in review comments, check `.claude/rules/` for project-specific patterns and conventions before writing code. Suggestions should follow the project's established style (e.g., the immediately-invoked function pattern for immutable assignment in Go). When requesting changes from external contributors, always provide concrete code examples showing the expected structure — don't just describe what you want in prose.