Analyze

Analyze Changes (Server-Side via MCP)

Perform a three-level code review analysis using pair-review's built-in analysis engine. Unlike the code-critic:analyze skill (which spawns analysis agents directly within the coding agent's context), this skill delegates all analysis work to the pair-review server via MCP tool calls. Use this skill when the pair-review MCP server is connected; use code-critic:analyze when it is not.

Prerequisites: The pair-review MCP server must be connected with the start_analysis, get_ai_analysis_runs, and get_ai_suggestions tools available.

1. Gather context

Determine what is being reviewed:

• Local changes: Run git rev-parse HEAD to get the HEAD SHA, and use the current working directory as the path.
• PR changes: Determine the repository (owner/repo) and PR number. If the user provides a PR URL, extract these from it. If available, run gh pr view --json number,headRepository or similar.
• If the user specifies a particular scope, use that.

Collect:

• Whether this is local or PR mode
• For local: the absolute path and HEAD SHA
• For PR: the owner/repo string and PR number

2. Start analysis

Call the start_analysis MCP tool with the appropriate parameters:

For local mode:

{
  "path": "/absolute/path/to/repo",
  "headSha": "abc123...",
  "tier": "balanced",
  "skipLevel3": false,
  "customInstructions": "optional instructions"
}

For PR mode:

{
  "repo": "owner/repo",
  "prNumber": 42,
  "tier": "balanced",
  "skipLevel3": false,
  "customInstructions": "optional instructions"
}

Pass the tier, skipLevel3, and customInstructions arguments from the skill invocation.

The tool returns immediately with { analysisId, runId, reviewId, status: "started" }.

3. Poll for completion

Analysis typically takes 1-5 minutes depending on the size of the changes and the tier.

Poll using get_ai_analysis_runs with limit: 1 and the review coordinates from step 1. Wait approximately 10 seconds between polls.

For local mode:

{
  "path": "/absolute/path/to/repo",
  "headSha": "abc123...",
  "limit": 1
}

For PR mode:

{
  "repo": "owner/repo",
  "prNumber": 42,
  "limit": 1
}

Verify that runs[0].id matches the runId returned from step 2 to ensure you are polling the correct analysis (another tab or user could have triggered a concurrent run).

Check the status field in runs[0]:

• "running": Analysis is still in progress — keep polling
• "completed": Analysis finished — proceed to fetch results using the same runId
• "failed": Analysis failed — report the failure to the user

Keep polling until status is completed or failed. Report progress to the user between polls.

Error handling

• If start_analysis returns an error, report it to the user with the error message. Common causes: the PR has not been loaded in pair-review yet, the worktree is missing, or invalid parameters.
• If polling shows status: "failed", report the failure to the user. The error field in the run object contains the failure reason.
• If get_ai_suggestions returns an empty list after a completed analysis, this means no issues were found -- report a clean result.

4. Fetch results

Once the analysis is complete, call get_ai_suggestions to retrieve the curated suggestions.

Pass the runId from step 2's start_analysis response (same value used for polling):

{
  "runId": "the-runId-from-step-2"
}

If runId is unavailable, fall back to resolving by review coordinates:

For local mode:

{
  "path": "/absolute/path/to/repo",
  "headSha": "abc123..."
}

For PR mode:

{
  "repo": "owner/repo",
  "prNumber": 42
}

This returns the final orchestrated suggestions from the latest analysis run.

5. Report

Present the curated suggestions to the user, organized by file. For each suggestion show:

• File and line reference
• Type (bug, improvement, security, performance, praise, etc.)
• Title and description
• Confidence level

Group suggestions by file for easy navigation. Highlight critical issues (bugs, security) prominently.

If no suggestions were found, report that the analysis completed cleanly.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.