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

---
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. **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)

3. **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

4. **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

5. **Vision Alignment Check**
   - Read the project's README.md and CLAUDE.md to understand the application's core purpose
   - Assess whether this PR aligns with the application's intended functionality
   - If the changes deviate significantly from the core vision or add functionality that doesn't serve the application's purpose, note this in the review
   - This is not a blocker, but should be flagged for the reviewer's consideration

6. **Safety Assessment**
   - Provide a review on whether the PR is safe to merge as-is
   - Provide any feedback in terms of risk level

7. **Improvements**
   - Propose any improvements in terms of importance and complexity

8. **Merge Recommendation**
   - Based on all findings, provide a clear merge/don't-merge recommendation
   - If all concerns are minor (cosmetic issues, naming suggestions, small style nits, missing comments, etc.), recommend **merging the PR** and note that the reviewer can address these minor concerns themselves with a quick follow-up commit pushed directly to master
   - If there are significant concerns (bugs, security issues, architectural problems, scope mismatch), recommend **not merging** and explain what needs to be resolved first

9. **TLDR**
   - End the review with a `## TLDR` section
   - In 3-5 bullet points maximum, summarize:
     - What this PR is actually about (one sentence)
     - The key concerns, if any (or "no significant concerns")
     - **Verdict: MERGE** / **MERGE (with minor follow-up)** / **DON'T MERGE** with a one-line reason
   - This section should be scannable in under 10 seconds

10. **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):**
    - Recommend merging as-is. No further action needed.

    **If verdict is MERGE (with minor follow-up):**
    - If the concerns are low-risk and straightforward to fix (e.g., naming tweaks, small refactors, missing type annotations, minor style issues, trivial bug fixes), recommend merging the PR now and offer to immediately address the concerns in a follow-up commit directly on the target branch
    - List the specific changes you would make in the follow-up
    - Ask the user: *"Should I merge this PR and push a follow-up commit addressing these concerns?"*

    **If verdict is DON'T MERGE:**
    - If the blocking concerns are still relatively contained and you are confident you can resolve them quickly (e.g., a small bug fix, a missing validation, a straightforward architectural adjustment), recommend merging the PR and immediately addressing the issues in a follow-up commit — but only if the fixes are low-risk and well-understood
    - 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