> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/code-review.md).

# Code review

Who reviews a pull request, what they check, and how a review thread ends.

Owner: Jeremy

This page covers pull requests in our code repositories.

## Rules

* Before you request a review, run Claude's `/code-review` and [`/security-review`](/engineering/development-process/how-to-build/coding-standards/architecture/security.md#did-it-work) in a new session.
* The [Code Owner](/engineering/product-engineer/code-owner.md) reviews and approves. If you are the Code Owner, another person takes their place.
* A pull request still waiting for review at the next [written standup](/culture/our-week.md#the-written-standup) goes into that standup.
* A review covers the [changelog](/engineering/development-process/how-to-ship/changelog.md) entry as well as the code.
* The author answers every review comment in its own thread, and the answer says what they did: fixed, fixed later, or not fixed with a reason the Code Owner accepts.

## AI reviews

**CodeRabbit reviews automatically once a pull request is open. Claude reviews only when you start it.** Anthropic describes [how it reviews code with Claude](https://claude.dev/blog/solving-code-review-at-anthropic/). Unlike Anthropic, we need an approval from a person other than the author. Vanta, our ISO 27001 tool, flags every merged pull request without one.

## What the Code Owner checks

**The Code Owner reads every line of:**

* a [one-way door](/engineering/development-process/how-to-build.md#one-way-doors),
* a change to CI workflows,
* a security change, such as cryptography,
* a new pattern or abstraction. New code copies the patterns already there, so a bad one spreads fast.

**For other changes, they rely on tests and CI** and read only the untested parts. Making sure those tests exist is [their job](/engineering/product-engineer/code-owner.md): better tests mean faster merges.

**Every review checks against the** [**spec**](/engineering/development-process/how-to-build.md#before-you-write-code)**,** [**rollout ticket**](/engineering/development-process/how-to-build/tickets/rollout.md)**,** [**Code quality**](/engineering/development-process/how-to-build/coding-standards/code-quality.md)**,** [**Security**](/engineering/development-process/how-to-build/coding-standards/architecture/security.md) **and** [**Changelog**](/engineering/development-process/how-to-ship/changelog.md)**.** Report a security problem as [Security](/engineering/development-process/how-to-build/tickets/security.md) in Tickets describes. As [Mark Jason Dominus puts it](https://mathstodon.xyz/@mjd/115096720350507897), "the primary purpose of code review is to find code that will be hard to maintain."

**The changelog entry is read as the affected user would read it**, and it is the reviewer's last chance to catch an entry that names the wrong feature or promises something the release does not yet give them.

**A review asks for simpler code with the same features. Whether to build fewer features was decided at the** [**bet**](/engineering/development-process/how-to-decide-what-to-build.md#the-bet)**; raise that in the product meeting, not in the pull request.**

**A change with several Code Owners is split into** [**stacked pull requests**](/engineering/development-process/how-to-build.md#stacked-pull-requests)**, one per Code Owner.** The [Product Owner](/engineering/product-engineer/product-owner.md) may review the product direction.

## Review threads

**If a finding is one case of a pattern, name the pattern in a single thread.** Link any [Coding standards](/engineering/development-process/how-to-build/coding-standards.md) rule it breaks.

**A misread is a finding.** If a reviewer misreads the code or finds it hard to read, the author changes the code instead of explaining it in the thread.

**Fixed: link the commit. Fixed later: link the follow-up** [**stacked pull request**](/engineering/development-process/how-to-build.md#stacked-pull-requests) **or the ticket.** A finding you are not fixing in this pull request becomes a ticket: [Security](/engineering/development-process/how-to-build/tickets/security.md) if it is a security issue, otherwise [Bugs](/engineering/development-process/how-to-build/tickets/bugs.md) if a user can run into it today, otherwise [tech debt](/engineering/development-process/how-to-build/tickets/tech-debt.md). Whoever raised a finding resolves its thread. The author resolves CodeRabbit's.

**If the author and a reviewer disagree, the Code Owner decides.** If the Code Owner is one side, engineering questions go to the CTO and product questions to the [product meeting](/culture/our-week.md#product-meeting). Write the outcome of a meeting or pairing into the thread.

**The Code Owner can approve with findings open** when they trust the author to answer them. If the author then changes more than asked, they request a new review.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://engineering.umh.app/engineering/development-process/how-to-build/code-review.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.