From 7059584f8168903b64b80d176bb608893e3606ab Mon Sep 17 00:00:00 2001 From: igerber Date: Sun, 8 Feb 2026 12:01:27 -0500 Subject: [PATCH 1/3] Add --updated flag to review-plan skill for re-reviewing revised plans When using /review-plan a second time after making revisions, the agent would short-circuit instead of performing a fresh review. The --updated flag forces a complete re-review and adds a Delta Assessment section comparing the revised plan against prior review feedback. Co-Authored-By: Claude Opus 4.6 --- .claude/commands/review-plan.md | 43 ++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/.claude/commands/review-plan.md b/.claude/commands/review-plan.md index 3bfe757..f50310c 100644 --- a/.claude/commands/review-plan.md +++ b/.claude/commands/review-plan.md @@ -1,6 +1,6 @@ --- description: Review a Claude Code plan file from a staff engineer perspective -argument-hint: "" +argument-hint: " [--updated]" --- # Review Plan @@ -9,16 +9,14 @@ Review a Claude Code plan file from a staff engineer perspective and provide str ## Arguments -`$ARGUMENTS` should contain: +`$ARGUMENTS` may contain: - **Plan file path** (required): Path to the plan file, e.g., `~/.claude/plans/dreamy-coalescing-brook.md` +- `--updated` (optional): Signal that the plan has been revised since a prior review. Forces a fresh full review and includes a delta assessment of what changed. -If no path is provided, use AskUserQuestion to request it: -``` -Which plan file would you like me to review? - -Options: -1. Enter the path (e.g., ~/.claude/plans/plan-name.md) -``` +Parse `$ARGUMENTS` to extract: +- **--updated**: Check if the literal string `--updated` appears anywhere in `$ARGUMENTS`. Remove it to get the remaining text. +- **Plan file path**: The remaining non-flag text after stripping `--updated`. The flag may appear before or after the path. +- If no path remains after stripping the flag, use AskUserQuestion to request it (same fallback as today). ## Constraints @@ -38,6 +36,19 @@ If the file does not exist, report the error and stop: Error: Plan file not found at ``` +### Step 1b: Handle Re-Review (if `--updated`) + +If the `--updated` flag is present, this is a re-review of a revised plan. + +**You MUST perform a complete fresh review** — do not skip or abbreviate any steps. Treat the plan file contents as the authoritative source, not your memory of a prior version. + +After completing the standard 8-dimension review in Step 4, add a **Delta Assessment** section to the output (see Step 5 template for format). This section compares the revised plan against the prior review's feedback: +- Which previously-raised issues have been addressed? +- Which previously-raised issues remain unresolved? +- Are there any new issues introduced by the revisions? + +If no prior review is available in conversation context (e.g., the user passed `--updated` on the first invocation, or the context was compressed), skip the Delta Assessment section and add a note: "Delta assessment unavailable — no prior review found in conversation context. Full fresh review performed." + ### Step 2: Read CLAUDE.md for Project Context Read the project's `CLAUDE.md` file to understand: @@ -192,6 +203,19 @@ Cross-reference against the relevant CLAUDE.md checklists. List which checklist --- +## Delta Assessment (only include if `--updated` flag was provided) + +### Addressed +[List prior issues that have been resolved in the revised plan] + +### Unresolved +[List prior issues that remain. Include the original issue text for reference.] + +### New Issues +[List any new issues introduced by the revisions, or "None."] + +--- + ## Summary | Category | Issues | @@ -216,3 +240,4 @@ Cross-reference against the relevant CLAUDE.md checklists. List which checklist - The review is displayed directly in the conversation, not saved to a file - For best results, run this before implementing a plan to catch issues early - The 8 dimensions are tuned for plan-specific failure modes, not generic code review +- Use `--updated` when re-reviewing a revised plan to get a delta assessment of what changed since the prior review From c4ef7133922486dd767eeed21d9c3fa904c9a43b Mon Sep 17 00:00:00 2001 From: igerber Date: Sun, 8 Feb 2026 12:10:23 -0500 Subject: [PATCH 2/3] Address PR #133 review feedback for --updated flag Fix three issues raised by AI review: - Switch from substring to token-based --updated flag parsing to prevent false matches inside file paths - Replace "skip Delta Assessment" with "fill with unavailable message" to resolve contradiction with Step 5's "do NOT skip any section" rule - Restore explicit AskUserQuestion fallback prompt template Co-Authored-By: Claude Opus 4.6 --- .claude/commands/review-plan.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/.claude/commands/review-plan.md b/.claude/commands/review-plan.md index f50310c..ef5099d 100644 --- a/.claude/commands/review-plan.md +++ b/.claude/commands/review-plan.md @@ -14,9 +14,15 @@ Review a Claude Code plan file from a staff engineer perspective and provide str - `--updated` (optional): Signal that the plan has been revised since a prior review. Forces a fresh full review and includes a delta assessment of what changed. Parse `$ARGUMENTS` to extract: -- **--updated**: Check if the literal string `--updated` appears anywhere in `$ARGUMENTS`. Remove it to get the remaining text. -- **Plan file path**: The remaining non-flag text after stripping `--updated`. The flag may appear before or after the path. -- If no path remains after stripping the flag, use AskUserQuestion to request it (same fallback as today). +- **--updated**: Split `$ARGUMENTS` on whitespace and check if any token is exactly `--updated`. Remove that token to get the remaining text. +- **Plan file path**: The remaining non-flag tokens after removing `--updated`, joined back together. The flag may appear before or after the path. +- If no path remains after stripping the flag, use AskUserQuestion to request it: +``` +Which plan file would you like me to review? + +Options: +1. Enter the path (e.g., ~/.claude/plans/plan-name.md) +``` ## Constraints @@ -47,7 +53,7 @@ After completing the standard 8-dimension review in Step 4, add a **Delta Assess - Which previously-raised issues remain unresolved? - Are there any new issues introduced by the revisions? -If no prior review is available in conversation context (e.g., the user passed `--updated` on the first invocation, or the context was compressed), skip the Delta Assessment section and add a note: "Delta assessment unavailable — no prior review found in conversation context. Full fresh review performed." +If no prior review is available in conversation context (e.g., the user passed `--updated` on the first invocation, or the context was compressed), still include the Delta Assessment section but fill each subsection with: "Delta assessment unavailable — no prior review found in conversation context. Full fresh review performed." ### Step 2: Read CLAUDE.md for Project Context @@ -167,7 +173,7 @@ Plan-specific failure modes that wouldn't show up in a code review: ### Step 5: Present Structured Feedback -Present the review in the following format. Do NOT skip any section — if a section has no findings, write "None." for that section. +Present the review in the following format. Do NOT skip any section — if a section has no findings, write "None." for that section. The Delta Assessment section is only included when the `--updated` flag was provided (see Step 1b). ``` ## Overall Assessment From cbf53e9b14e9beae014468ef85812a42a7df233c Mon Sep 17 00:00:00 2001 From: igerber Date: Sun, 8 Feb 2026 12:27:07 -0500 Subject: [PATCH 3/3] Fix argument hint ordering in review-plan skill Move [--updated] before in the argument hint to match CLI conventions (flags before positional args) and align with the parsing instructions that already allow either ordering. Co-Authored-By: Claude Opus 4.6 --- .claude/commands/review-plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/commands/review-plan.md b/.claude/commands/review-plan.md index ef5099d..cff2244 100644 --- a/.claude/commands/review-plan.md +++ b/.claude/commands/review-plan.md @@ -1,6 +1,6 @@ --- description: Review a Claude Code plan file from a staff engineer perspective -argument-hint: " [--updated]" +argument-hint: "[--updated] " --- # Review Plan