Review: Greptile (Codebase-Aware)

Greptile reviews PRs with full codebase understanding — it indexes the entire repository, not just the diff. This makes it uniquely capable of detecting cross-file impact: a change in one module that breaks an assumption in another module not present in the diff.

Complementary to the domain's diff-only specialized reviewers: use both together for the most complete picture.

What Greptile Adds Over Diff-Only Reviewers

Workflow

Greptile Review Progress:
- [ ] Step 1: Resolve repo name and PR number
- [ ] Step 2: Trigger Greptile code review via MCP
- [ ] Step 3: Poll until review is ready
- [ ] Step 4: Parse findings into unified format
- [ ] Step 5: Check custom context for known exceptions
- [ ] Step 6: Emit findings with STATUS

Input Contract

Step 1: Resolve Repo and PR

If repo is not provided, resolve from the current git remote:

git remote get-url origin
# Extract owner/repo from URL:
# https://github.com/owner/repo.git  →  owner/repo
# git@github.com:owner/repo.git      →  owner/repo

If pr_number is not provided and user said "review PR" without a number:

# Get current branch PR
gh pr view --json number,headRefName,baseRefName

Step 2: Trigger Greptile Review

Call the Greptile MCP tool:

mcp__greptile__trigger_code_review({
  name: "<owner/repo>",
  remote: "github",       // or "gitlab"
  prNumber: <number>,
  branch: "<PR branch>",           // optional
  defaultBranch: "<base branch>"   // optional
})

This returns a codeReviewId used to retrieve results.

Step 3: Poll for Results

Greptile reviews are async. After triggering:

mcp__greptile__get_code_review({ codeReviewId: "<id>" })

The response includes a status field:

• pending / in_progress — wait and retry (suggest ~10s intervals, up to 5 retries)
• completed — parse findings
• failed — emit STATUS: BLOCKED with error message

If still pending after retries, tell the user: "Greptile review is running — check back with get_code_review(<id>)."

Step 4: Parse Findings

Normalize each Greptile finding to the domain's unified format:

### [G-NNN] <title from Greptile>

- **Severity**: <map Greptile severity to blocker | major | minor | info>
- **File**: <path>:<line>
- **Source**: Greptile (codebase-aware)
- **Problem**: <Greptile's description>
- **Cross-file context**: <if Greptile identified impact in other files — describe them>
- **Fix**: <Greptile's suggestion>

Severity mapping from Greptile:

Use prefix G- for finding IDs to distinguish Greptile findings from domain reviewer findings (F-).

Step 5: Check Custom Context

After getting findings, check if Greptile has stored custom context for this repo:

mcp__greptile__get_custom_context({ ... })
// or search for relevant context:
mcp__greptile__search_custom_context({ query: "<topic of finding>" })

If custom context exists that explains or excuses a finding — mark the finding as info and note the exception.

Output Contract

STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED

## Greptile Review — PR #<N>

### Review Scope
- Repo: `<owner/repo>`
- PR: #<N>
- Remote: github | gitlab
- Review ID: `<codeReviewId>`

### Summary
<2-3 sentences: what Greptile found, cross-file impact summary if any.>

### Stats
- blocker (G-): N  |  major (G-): N  |  minor (G-): N  |  info (G-): N

### Findings

#### Cross-File Impact (Greptile-specific)
<G-NNN findings where Greptile identified impact beyond the diff, or "None detected.">

#### Other Findings
<G-NNN findings within the diff scope.>

### Greptile Review ID
`<codeReviewId>` — use this to re-fetch results or link in PR comments.

Job Context Awareness

When dispatched by review-orchestrator, the prompt MAY include:

JOB_NAME:     <job-name>
CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md

Read the context doc before reviewing. It may contain known exceptions or intentional patterns that Greptile would flag but are acceptable.

Red Flags

Orchestrated Review Contract

When dispatched by review-orchestrator, follow the provided reviewer-input.schema.json payload. Return a REVIEW_RESULT object compatible with skills/review-orchestrator/reviewer-finding.schema.json, then a concise markdown summary. Keep findings evidence-based, include concrete suggested_fix for every blocker/major, and return NEEDS_CONTEXT instead of guessing when required context is missing.