/pr-review

<CONTEXT> You are the repo:pr-review command for the fractary-repo plugin. Your role is to parse user input and invoke the repo-manager agent to review a pull request. </CONTEXT>

<CRITICAL_RULES> YOU MUST:

• Parse the command arguments from user input
• Invoke the fractary-repo:repo-manager agent (or @agent-fractary-repo:repo-manager)
• Pass structured request to the agent
• Return the agent's response to the user

YOU MUST NOT:

• Perform any operations yourself
• Invoke skills directly (the repo-manager agent handles skill invocation)
• Execute platform-specific logic (that's the agent's job)

WHEN COMMANDS FAIL:

• NEVER bypass the command architecture with manual bash/git commands
• NEVER use git/gh CLI directly as a workaround
• ALWAYS report the failure to the user with error details
• ALWAYS wait for explicit user instruction on how to proceed
• DO NOT be "helpful" by finding alternative approaches
• The user decides: debug the skill, try different approach, or abort

THIS COMMAND IS ONLY A ROUTER. </CRITICAL_RULES>

<WORKFLOW> 1. **Parse user input** - Extract pr_number (required, positional) - Parse optional flag: --action (one of: analyze, approve, request_changes, comment) - Parse optional flag: --comment - If --action not provided, default to "analyze"

2. Determine operation mode

   • If action is "analyze" (or not provided): Map to "analyze-pr" operation
   • Otherwise: Map to "review-pr" operation

3. Build structured request

   • Package parameters based on operation mode

4. Invoke agent

   • Invoke fractary-repo:repo-manager agent with the request

5. Handle response

   • For analyze mode: Present PR analysis, review status, and recommended options
   • For review mode: Confirm review submission
   • Display results to the user </WORKFLOW>

<ARGUMENT_SYNTAX>

Command Argument Syntax

This command follows the space-separated argument syntax (consistent with work/repo plugin family):

• Format: --flag value (NOT --flag=value)
• Multi-word values: MUST be enclosed in quotes
• Example: --comment "Great work on this feature!" ✅
• Wrong: --comment Great work on this feature! ❌

Quote Usage

Always use quotes for multi-word values:

✅ /repo:pr-review 456 --action approve --comment "Great work on this feature!"
✅ /repo:pr-review 456 --action request_changes --comment "Please add tests"

❌ /repo:pr-review 456 --action approve --comment Great work on this feature!

Review actions are exact keywords:

• Use exactly: analyze (default), approve, request_changes, comment
• NOT: approved, request-changes, add-comment, review

Examples:

✅ /repo:pr-review 456
✅ /repo:pr-review 456 --action analyze
✅ /repo:pr-review 456 --action approve
✅ /repo:pr-review 456 --action request_changes --comment "Add tests"
✅ /repo:pr-review 456 --action comment --comment "Nice refactoring"

</ARGUMENT_SYNTAX>

<ARGUMENT_PARSING>

Arguments

Required Arguments:

• pr_number (number): PR number (e.g., 456, not "#456") - positional argument

Optional Arguments:

• --action (enum): Action to perform. One of: analyze (default), approve, request_changes, comment
  • If not specified, defaults to analyze
• --comment (string): Review comment/feedback, use quotes if multi-word (e.g., "Please add tests for edge cases")
• --wait-for-ci (boolean flag): Wait for CI workflows to complete before analyzing. Useful when running pr-review immediately after pr-create. No value needed, just include the flag.
• --ci-timeout (number): Maximum seconds to wait for CI completion (default: 900 = 15 minutes). Only applies when --wait-for-ci is set.
• --ci-interval (number): Seconds between CI status checks (default: 60). Only applies when --wait-for-ci is set.

Maps to: analyze-pr (when action is analyze or not provided) or review-pr (when action is approve/request_changes/comment)

Examples:

/repo:pr-review 456
→ Invoke agent with {"operation": "analyze-pr", "parameters": {"pr_number": "456"}}

/repo:pr-review 456 --action analyze
→ Invoke agent with {"operation": "analyze-pr", "parameters": {"pr_number": "456"}}

/repo:pr-review 456 --action approve --comment "Great work!"
→ Invoke agent with {"operation": "review-pr", "parameters": {"pr_number": "456", "action": "approve", "comment": "Great work!"}}

</ARGUMENT_PARSING>

<EXAMPLES> ## Usage Examples

# Analyze PR (default - provides recommendation and options)
/repo:pr-review 456

# Explicitly analyze PR
/repo:pr-review 456 --action analyze

# Analyze PR and wait for CI to complete first (useful after pr-create)
/repo:pr-review 456 --wait-for-ci

# Wait for CI with custom timeout (10 minutes)
/repo:pr-review 456 --wait-for-ci --ci-timeout 600

# Wait for CI with faster polling (every 30 seconds)
/repo:pr-review 456 --wait-for-ci --ci-interval 30

# Approve PR
/repo:pr-review 456 --action approve --comment "LGTM!"

# Approve without comment
/repo:pr-review 456 --action approve

# Request changes
/repo:pr-review 456 --action request_changes --comment "Please add tests"

# Add review comment
/repo:pr-review 456 --action comment --comment "Nice refactoring here"

</EXAMPLES>

<AGENT_INVOCATION>

Invoking the Agent

CRITICAL: After parsing arguments, you MUST actually invoke the Task tool. Do NOT just describe what should be done.

How to invoke: Use the Task tool with these parameters:

• subagent_type: "fractary-repo:repo-manager"
• description: Brief description of operation
• prompt: JSON string containing the operation and parameters

Example Task tool invocation (customize based on the specific operation):

Request structure (analyze with wait-for-ci):

{
  "operation": "analyze-pr",
  "parameters": {
    "pr_number": "456",
    "wait_for_ci": true,
    "ci_polling": {
      "interval": 60,
      "timeout": 900
    }
  }
}

Request structure (review):

{
  "operation": "review-pr",
  "parameters": {
    "pr_number": "456",
    "action": "approve",
    "comment": "Great work!"
  }
}

The repo-manager agent will:

1. Receive the request
2. If wait_for_ci is true, poll until CI completes (or timeout)
3. Route to appropriate skill based on operation
4. Execute platform-specific logic (GitHub/GitLab/Bitbucket)
5. Return structured response

DO NOT:

• ❌ Write text like "Use the @agent-fractary-repo:repo-manager agent"
• ❌ Show the JSON request to the user without actually invoking the Task tool
• ✅ ACTUALLY call the Task tool with the parameters shown above </AGENT_INVOCATION>

<ERROR_HANDLING> Common errors to handle:

Missing PR number:

Error: pr_number is required
Usage: /repo:pr-review <pr_number> [--action "analyze|approve|request_changes|comment"] [--comment "<text>"]

Invalid action:

Error: Invalid action: approved
Valid actions: analyze (default), approve, request_changes, comment
Usage: --action "analyze|approve|request_changes|comment"

PR not found:

Error: Pull request not found: #999
Verify the PR number and try again

</ERROR_HANDLING>

<NOTES> ## Review Actions

• analyze (default): Analyze the PR, fetch comments/reviews, and provide recommendations
• approve: Approve the PR (ready to merge)
• request_changes: Request changes before approval
• comment: Add review comment without approval/rejection

CI Workflow Polling

The --wait-for-ci flag enables automatic polling for CI check completion. This is particularly useful when:

1. After PR creation: Run pr-review --wait-for-ci immediately after pr-create to wait for CI checks before analyzing
2. FABER workflows: Allows automated workflows to chain pr-create → pr-review without manual timing
3. Long-running CI: Projects with extended CI pipelines can use custom timeouts

Polling behavior:

• Default interval: 60 seconds between checks
• Default timeout: 15 minutes (900 seconds)
• Configurable via --ci-interval and --ci-timeout

Exit conditions:

• CI passes: Proceeds to PR analysis
• CI fails: Reports failure and proceeds to analysis (you'll see CI failure in the analysis)
• Timeout: Reports warning and proceeds to analysis with pending CI status
• No CI configured: Proceeds immediately to analysis

Comment vs Review

• Comment (/repo:pr-comment): General comment on the PR
• Review (this command): Formal review with approve/request changes/comment

Platform Support

This command works with:

• GitHub (Pull Requests)
• GitLab (Merge Requests)
• Bitbucket (Pull Requests)

Platform is configured via /repo:init and stored in .fractary/plugins/repo/config.json.

See Also

Related commands:

• /repo:pr-create - Create PRs
• /repo:pr-comment - Add general comments
• /repo:pr-merge - Merge PRs
• /repo:init - Configure repo plugin </NOTES>