Speckit Review Run

Comprehensive PR Review

Run a comprehensive pull request review using multiple specialized agents, each focusing on a different aspect of code quality.

Review Aspects (optional): "$ARGUMENTS"

Review Workflow:

1. Load Configuration

   • Read the project config file at .specify/extensions/review/review-config.yml (if it exists).
   • If the file does not exist, fall back to the defaults.agents section in the extension's extension.yml.
   • Extract the agents map — each key (code, comments, tests, errors, types, simplify) is a boolean toggle.
   • Agents set to false MUST be excluded from this run. Do not launch them.

2. Determine Review Scope

   • Parse arguments to see if user requested specific review aspects.
   • If specific aspects were requested, run exactly those — config toggles do not apply (explicit user request overrides config).
   • Default (no arguments): Run all applicable reviews that are enabled in config.

3. Available Review Aspects:

   • comments - Analyze code comment accuracy and maintainability
   • tests - Review test coverage quality and completeness
   • errors - Check error handling for silent failures
   • types - Analyze type design and invariants (if new types added)
   • code - General code review for project guidelines
   • simplify - Simplify code for clarity and maintainability
   • all - Run all applicable reviews (default)

4. Identify Changed Files

   • If the user provided a file list or explicit instructions on how to retrieve files (e.g., only staged, only unstaged, a specific folder, etc.), follow those instructions directly.
   • Otherwise, you MUST execute the .specify/scripts/bash/detect-changed-files.sh with --json to detect changed files. Do not attempt to detect changes by running git commands directly, reading git state manually, or using any other method — always delegate to the script.
     • The script automatically picks the best detection mode:
       • Mode A (feature branch): diffs the current branch against the default branch (main/master) from the merge-base, plus any staged and unstaged changes.
       • Mode B (working directory): falls back to staged + unstaged changes when there is no feature branch (e.g., working directly on the default branch).
     • JSON output: {"branch", "default_branch", "mode", "changed_files": [...]}
   • Note: The folder containing the script may be excluded from version control or hidden by search indexing. You must still locate and execute it — do not skip it or substitute your own file-detection logic.

5. Determine Applicable Reviews

   Based on changes and config toggles (skip any agent where agents.<name> is false):

   • Always applicable (if enabled): /speckit.review.code (general quality)
   • If test files changed (if enabled): /speckit.review.tests
   • If comments/docs added (if enabled): /speckit.review.comments
   • If error handling changed (if enabled): /speckit.review.errors
   • If types added/modified (if enabled): /speckit.review.types
   • After passing review (if enabled): /speckit.review.simplify (polish and refine)
   • If an agent is disabled by config, note it in the final summary (e.g., "simplify: skipped (disabled in config)").

6. Launch Review Agents

   Sequential approach (one at a time):

   • Easier to understand and act on
   • Each report is complete before next
   • Good for interactive review

   Parallel approach (user can request):

   • Launch all agents simultaneously
   • Faster for comprehensive review
   • Results come back together

7. Aggregate Results

   After agents complete, summarize:

   • Critical Issues (must fix before merge)
   • Important Issues (should fix)
   • Suggestions (nice to have)
   • Positive Observations (what's good)

8. Provide Action Plan

   Organize findings:

   # PR Review Summary
   
   ## Critical Issues (X found)
   - [agent-name]: Issue description [file:line]
   
   ## Important Issues (X found)
   - [agent-name]: Issue description [file:line]
   
   ## Suggestions (X found)
   - [agent-name]: Suggestion [file:line]
   
   ## Strengths
   - What's well-done in this PR
   
   ## Recommended Action
   1. Fix critical issues first
   2. Address important issues
   3. Consider suggestions
   4. Re-run review after fixes