autocoder/.claude/commands/review-pr.md

description

description
Review pull requests

Pull request(s): $ARGUMENTS

• If no PR numbers are provided, ask the user to provide PR number(s).
• At least 1 PR is required.

TASKS

1. Retrieve PR Details

   • Use the GH CLI tool to retrieve the details (descriptions, diffs, comments, feedback, reviews, etc)

2. Check for Merge Conflicts

   • After retrieving PR details, check whether the PR has merge conflicts against the target branch
   • Use gh pr view <number> --json mergeable,mergeStateStatus or attempt a local merge check with git merge-tree
   • If conflicts exist, note the conflicting files — these must be resolved on the PR branch before merging
   • Surface conflicts early so they inform the rest of the review (don't discover them as a surprise at merge time)

3. Assess PR Complexity

   After retrieving PR details, assess complexity based on:

   • Number of files changed
   • Lines added/removed
   • Number of contributors/commits
   • Whether changes touch core/architectural files

   Complexity Tiers

   Simple (no deep dive agents needed):

   • ≤5 files changed AND ≤100 lines changed AND single author
   • Review directly without spawning agents

   Medium (1-2 deep dive agents):

   • 6-15 files changed, OR 100-500 lines, OR 2 contributors
   • Spawn 1 agent for focused areas, 2 if changes span multiple domains

   Complex (up to 3 deep dive agents):

   • 15 files, OR >500 lines, OR >2 contributors, OR touches core architecture

   • Spawn up to 3 agents to analyze different aspects (e.g., security, performance, architecture)

4. Analyze Codebase Impact

   • Based on the complexity tier determined above, spawn the appropriate number of deep dive subagents
   • For Simple PRs: analyze directly without spawning agents
   • For Medium PRs: spawn 1-2 agents focusing on the most impacted areas
   • For Complex PRs: spawn up to 3 agents to cover security, performance, and architectural concerns

5. PR Scope & Title Alignment Check

   • Compare the PR title and description against the actual diff content
   • Check whether the PR is focused on a single coherent change or contains multiple unrelated changes
   • If the title/description describe one thing but the PR contains significantly more (e.g., title says "fix typo in README" but the diff touches 20 files across multiple domains), flag this as a scope mismatch
   • A scope mismatch is a merge blocker — recommend the author split the PR into smaller, focused PRs
   • Suggest specific ways to split the PR (e.g., "separate the refactor from the feature addition")
   • Reviewing large, unfocused PRs is impractical and error-prone; the review cannot provide adequate assurance for such changes

6. Vision Alignment Check

   • VISION.md protection: First, check whether the PR diff modifies VISION.md in any way (edits, deletions, renames). If it does, stop the review immediately — verdict is DON'T MERGE. VISION.md is immutable and no PR is permitted to alter it. Explain this to the user and skip all remaining steps.
   • Read the project's VISION.md, README.md, and CLAUDE.md to understand the application's core purpose and mandatory architectural constraints
   • Assess whether this PR aligns with the vision defined in VISION.md
   • Vision deviation is a merge blocker. If the PR introduces functionality, integrations, or architectural changes that conflict with VISION.md, the verdict must be DON'T MERGE. This is not negotiable — the vision document takes precedence over any PR rationale.

7. Safety Assessment

   • Provide a review on whether the PR is safe to merge as-is
   • Provide any feedback in terms of risk level

8. Improvements

   • Propose any improvements in terms of importance and complexity

9. Merge Recommendation

   • Based on all findings (including merge conflict status from step 2), provide a clear recommendation
   • If no concerns and no conflicts: recommend merging as-is
   • If concerns are minor/fixable and/or merge conflicts exist: recommend fixing on the PR branch first, then merging. Never merge a PR with known issues to main — always fix on the PR branch first
   • If there are significant concerns (bugs, security issues, architectural problems, scope mismatch) that require author input or are too risky to fix: recommend not merging and explain what needs to be resolved

10. TLDR

    • End the review with a ## TLDR section
    • In 3-5 bullet points maximum, summarize:
      • What this PR is actually about (one sentence)
      • Merge conflict status (clean or conflicting files)
      • The key concerns, if any (or "no significant concerns")
      • Verdict: MERGE / MERGE (after fixes) / DON'T MERGE with a one-line reason
    • This section should be scannable in under 10 seconds

    Verdict definitions:

    • MERGE — no issues, clean to merge as-is
    • MERGE (after fixes) — minor issues and/or conflicts exist, but can be resolved on the PR branch first, then merged
    • DON'T MERGE — needs author attention, too complex or risky to fix without their input

11. Post-Review Action

    • Immediately after the TLDR, provide a ## Recommended Action section
    • Based on the verdict, recommend one of the following actions:

    If verdict is MERGE (no concerns):

    • Merge as-is. No further action needed.

    If verdict is MERGE (after fixes):

    • List the specific changes that need to be made (fixes, conflict resolutions, etc.)
    • Offer to: check out the PR branch, resolve any merge conflicts, apply the minor fixes identified during review, push the updated branch, then merge the now-clean PR
    • Ask the user: "Should I check out the PR branch, apply these fixes, and then merge?"
    • Never merge first and fix on main later — always fix on the PR branch before merging

    If verdict is DON'T MERGE:

    • If the issues are contained and you are confident you can fix them: offer the same workflow as "MERGE (after fixes)" — check out the PR branch, apply fixes, push, then merge
    • If the issues are too complex, risky, or require author input (e.g., design decisions, major refactors, unclear intent): recommend sending the PR back to the author with specific feedback on what needs to change
    • Be honest about your confidence level — if you're unsure whether you can address the concerns correctly, say so and defer to the author