> For the complete documentation index, see [llms.txt](https://pharaoh.so/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharaoh.so/docs/guides/review-pull-requests.md).

# Review Pull Requests

Code review from a diff alone misses the structural questions: Is the new code wired up? What does it break downstream? Does it duplicate something that already exists? Pharaoh turns PR review into a structural analysis - not just "does this code look right" but "does this code fit the architecture."

## The workflow

### 1. Get full context on the changed modules

Ask your AI tool:

```
Review this PR - check the auth and api modules, search for any existing validation functions, and check blast radius on the UserService class.
```

This triggers `pharaoh_recon`, which runs codebase map + module context + function search + blast radius in one batched call. You get the full architectural context for the PR in a single response.

### 2. Verify new code is wired in

Ask your AI tool:

```
Are the new exports from auth/middleware.ts reachable from any entry point?
```

This triggers `check_reachability` (Pro). New exports that aren't connected to any HTTP handler, cron job, or CLI command are dead on arrival - they compile, they pass tests, but they never run in production.

### 3. Score regression risk

Ask your AI tool:

```
What's the regression risk for the functions changed in this PR?
```

This triggers `get_regression_risk`. Each function gets a risk score based on:

* **Complexity** - cyclomatic complexity of the function
* **Caller count** - how many other functions depend on it
* **Churn** - how often it's been modified recently
* **Exposure** - whether it's connected to entry points

High-complexity functions with many callers that have been recently changed are where regressions land.

### 4. Check for duplication

Ask your AI tool:

```
Does similar validation logic already exist anywhere in the codebase?
```

This triggers `search_functions`. If the PR adds a `validateEmailFormat` and the codebase already has `isValidEmail` in a shared utils module, that's a merge-blocking finding.

## What to look for

* **Unreachable exports** - the most common structural defect in PRs. Code that compiles and passes tests but is never called from any production path. This happens when someone adds a function and forgets to register it with a router, export it from a barrel file, or call it from a handler.
* **High regression risk scores** - functions in the diff with HIGH risk deserve line-by-line review. Functions with LOW risk and no callers outside their own module are safe to approve quickly.
* **Duplicate functions** - the PR adds something that already exists. This isn't just style - duplicate logic means duplicate bugs and divergent behavior over time.
* **Missing blast radius awareness** - the PR modifies a shared function but only updates one caller. If `get_blast_radius` shows 8 callers and the PR touches 2, ask what happens to the other 6.

## Tips

* Start every PR review with `pharaoh_recon`. It gives you the same context the PR author had (or should have had) when writing the code.
* Check reachability on every new export. The fastest way to catch "compiles but doesn't run" defects is to ask whether new code is connected to anything.
* For PRs that span multiple repos, use `get_cross_repo_audit` to check for structural drift - cases where the same pattern is implemented differently across repos.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pharaoh.so/docs/guides/review-pull-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.