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

Capability	Diff-only reviewers	Greptile
Logic bugs in changed code	✓	✓
Cross-file impact analysis	✗	✓
Codebase-wide pattern violations	✗	✓
Detecting broken callers (downstream breakage)	✗	✓
Understanding project conventions from history	✗	✓
Custom context (team-documented exceptions)	✗	✓

---

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

Field	Required	Description
pr_number	YES	Pull request or merge request number
repo	YES	Full repo name: owner/repo (e.g., MrCipherSmith/goodai-base)
remote	No	github (default) or gitlab
branch	No	PR branch name. Auto-detected if not provided.
base_branch	No	Base/default branch. Auto-detected if not provided.
context_doc	No	Path to job context doc — read before reviewing

---

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
# [email protected]: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:

Greptile level	Domain severity
critical / error	blocker
warning	major
suggestion / info	minor
comment / note	info

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

Rationalization	Why it is wrong
"Greptile found nothing, so the PR is safe"	Greptile complements diff-only reviewers; use both
"I'll skip polling and just return pending"	Always poll at least 3 times before giving up — async reviews take time
"The custom context says this is fine, so I'll suppress the finding entirely"	Document the exception as info, don't silently drop the finding
"Greptile's severity maps directly to domain severity"	Always re-evaluate — Greptile's "warning" may be a blocker given the codebase context