diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0bd34e58b..349eb1651 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -62,7 +62,7 @@ "name": "utils", "source": "./plugins/utils", "description": "A generic utilities plugin serving as a catch-all for various helper commands", - "version": "0.0.7" + "version": "0.0.8" }, { "name": "olm", diff --git a/PLUGINS.md b/PLUGINS.md index d46054f4b..dd7cb65ea 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -407,7 +407,7 @@ See [plugins/testing/README.md](plugins/testing/README.md) for detailed document A generic utilities plugin serving as a catch-all for various helper commands and agents **Commands:** -- **`/utils:address-reviews` `[PR number (optional - uses current branch if omitted)]`** - Fetch and address all PR review comments +- **`/utils:address-reviews` `[PR number (optional - uses current branch if omitted)] [--preview]`** - Fetch and address all PR review comments - **`/utils:auto-approve-konflux-prs` ``** - Automate approving Konflux bot PRs for the given repository by adding /lgtm and /approve - **`/utils:find-konflux-images` ``** - Find and verify Konflux-built container images from a GitHub PR - **`/utils:generate-test-plan` `[GitHub PR URLs]`** - Generate test steps for one or more related PRs diff --git a/docs/data.json b/docs/data.json index 725b98d9f..8f63e9cf6 100644 --- a/docs/data.json +++ b/docs/data.json @@ -817,7 +817,7 @@ { "commands": [ { - "argument_hint": "[PR number (optional - uses current branch if omitted)]", + "argument_hint": "[PR number (optional - uses current branch if omitted)] [--preview]", "description": "Fetch and address all PR review comments", "name": "address-reviews", "synopsis": "" @@ -876,7 +876,7 @@ "hooks": [], "name": "utils", "skills": [], - "version": "0.0.7" + "version": "0.0.8" }, { "commands": [ diff --git a/plugins/utils/.claude-plugin/plugin.json b/plugins/utils/.claude-plugin/plugin.json index bb74703d1..0a82c868c 100644 --- a/plugins/utils/.claude-plugin/plugin.json +++ b/plugins/utils/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "utils", "description": "A generic utilities plugin serving as a catch-all for various helper commands and agents", - "version": "0.0.7", + "version": "0.0.8", "author": { "name": "github.com/openshift-eng" } diff --git a/plugins/utils/commands/address-reviews.md b/plugins/utils/commands/address-reviews.md index 0f6ec7f77..d95bb36b4 100644 --- a/plugins/utils/commands/address-reviews.md +++ b/plugins/utils/commands/address-reviews.md @@ -1,13 +1,13 @@ --- description: Fetch and address all PR review comments -argument-hint: "[PR number (optional - uses current branch if omitted)]" +argument-hint: "[PR number (optional - uses current branch if omitted)] [--preview]" --- ## Name utils:address-reviews ## Synopsis -/utils:address-reviews [PR number (optional - uses current branch if omitted)] +/utils:address-reviews [PR number (optional - uses current branch if omitted)] [--preview] ## Description This command automates the process of addressing PR review comments by fetching all comments from a pull request, categorizing them by priority (blocking, change requests, questions, suggestions), and systematically addressing each one. It intelligently filters out outdated comments, bot-generated content, and oversized responses to optimize context usage. The command handles code changes, posts replies to reviewers, and maintains a clean git history by amending relevant commits rather than creating unnecessary new ones. @@ -109,11 +109,25 @@ This command automates the process of addressing PR review comments by fetching ### Step 3: Address Comments +#### Interactive Preview (`--preview`) + +When `--preview` is passed, preview each comment before acting: + +1. Show the reviewer's comment +2. Show your proposed action: code change diff, explanation, or decline reasoning +3. Show the draft reply you plan to post +4. **Wait for user approval** before proceeding — the user can: + - **Approve** as-is + - **Edit** the proposed reply or approach + - **Skip** the comment entirely + +This applies to all comment types below. Without `--preview`, act autonomously. + #### Grouped Comments When multiple comments relate to the same concern/fix: - Make the code change once -- Reply to EACH comment individually (don't copy-paste, tailor each reply) +- Track replies for EACH comment individually (posted in Step 4 — don't copy-paste, tailor each reply) - Optional reference: `Done. (Also addresses feedback from @user)` #### Code Change Requests @@ -122,7 +136,7 @@ When multiple comments relate to the same concern/fix: **b. If requested change is valid**: - Plan and implement changes -- Commit and Push **(ALL sub-steps are MANDATORY — do not skip any)** +- Commit locally **(do NOT push yet — all pushes are batched in Step 4)** 1. **Review changes**: `git diff` 2. **Sync with remote first**: `git pull --rebase origin ` to ensure local branch is up to date. If the branch is behind or diverged, you MUST rebase before committing. @@ -139,48 +153,66 @@ When multiple comments relate to the same concern/fix: - **When unsure**: Amend (keep git history clean) - **Multiple commits**: Use `git rebase -i origin/main` to amend the specific relevant commit - 5. **Create commit AND push (both required)**: + 5. **Create commit locally**: - Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format - Always include body explaining "why" - - **Amend**: `git commit --amend --no-edit && git push --force-with-lease` (or update message if scope changed) - - **New commit**: Standard commit with message, then `git push` - - **⚠️ A commit without a push is incomplete. You MUST push.** + - **Amend**: `git commit --amend --no-edit` (or update message if scope changed) + - **New commit**: Standard commit with message - 6. **Verify push succeeded (MANDATORY before replying)**: - - Run `git log -1 --format='%H'` locally and `git ls-remote origin ` to confirm the remote has your commit - - **If they differ**: The push failed or was never executed. Do NOT post a "Done" reply. Diagnose and retry, or report the failure to the user. - - **If uncommitted changes remain** (`git status`): The commit failed. Fix it first. - - **⚠️ NEVER post a "Done" or "Fixed" reply unless the push is verified on the remote.** Posting false claims of completion erodes reviewer trust and wastes human reviewers' time. - -- **Concise Reply template**: `Done. [1-line what changed]. [Optional 1-line why]` - - Max 2 sentences + attribution footer -- Post reply: - ``` - gh api repos/{owner}/{repo}/pulls//comments//replies -f body="" - ``` - If fails: `gh pr comment --body="@ "` +- Track what was done for each comment (change description, comment ID, author) so replies can be posted in Step 4 **c. If declining change**: -- **Reply with technical explanation** (3-5 sentences): +- **Prepare technical explanation** (3-5 sentences): - Why current implementation is correct - Specific reasoning with file:line references -- Use same posting method as (b) +- Track for reply in Step 4 **d. If unsure**: Ask user for clarification #### Clarification Requests -- Provide clear, detailed answer (2-4 sentences) +- Prepare clear, detailed answer (2-4 sentences) - Include file:line references when applicable -- Post using same method as code changes +- Track for reply in Step 4 #### Informational Comments - No action unless response is courteous +### Step 4: Post Replies and Push + +After ALL comments from Step 3 are processed, post replies and push in this order: + +#### 4a. Post all replies + +For each comment addressed in Step 3, post the reply: + +- **Concise Reply template**: `Done. [1-line what changed]. [Optional 1-line why]` + - Max 2 sentences + attribution footer +- Post reply: + ``` + gh api repos/{owner}/{repo}/pulls//comments//replies -f body="" + ``` + If fails: `gh pr comment --body="@ "` + **All replies must include**: `---\n*AI-assisted response via Claude Code*` -### Step 4: Summary +#### 4b. Push once + +After all replies are posted, push all committed changes in a single push: + +```bash +git push --force-with-lease +``` + +#### 4c. Verify push + +- Run `git log -1 --format='%H'` locally and `git ls-remote origin ` to confirm the remote has your commit +- **If they differ**: The push failed or was never executed. Diagnose and retry. +- **If uncommitted changes remain** (`git status`): The commit failed. Fix it before pushing. +- **If push cannot be verified**: Report the failure to the user. Do not silently proceed — replies have already been posted claiming changes were made. + +### Step 5: Summary Show user: - Total comments found (raw count from API) @@ -229,4 +261,5 @@ Where `` is one of: `issue_comment`, `review_thread`, or `review_comment` ## Arguments: -- $1: [PR number to address reviews (optional - uses current branch if omitted)] \ No newline at end of file +- $1: [PR number (optional - uses current branch if omitted)] +- --preview: Preview each comment's proposed action and reply before proceeding \ No newline at end of file