How Review Assist’s architecture catches bugs before code review

AI coding agents can produce a plausible pull request in minutes. The hard part is no longer generating the diff. It is recovering the reasoning behind it: what the agent believed, what it tried, what it verified, and where it is still uncertain.

Most AI code review tools begin after the change exists and inspect the diff as a finished artifact. Review Assist moves part of that scrutiny earlier. Its architecture creates a separate, cold reviewer while the coding session is still active, then refuses to publish the review document unless the evidence and the diff agree.

The architectural idea: separate explanation from evaluation

Review Assist uses two role-locked agents. The Author can read the local coding session and explain the decisions that produced the change. The Intent Reviewer can read the diff, but not the transcript. That boundary is deliberate.

If the same agent both implements and judges the work, it can repeat its own assumptions as if they were evidence. A cold reviewer has to reconstruct the change from what a human reviewer will actually see. Missing migrations, contradictory state, unverified behavior, and unexplained hunks become questions instead of being silently rationalized.

A two-sided interview turns claims into evidence

The reviewer records questions against the run and receives a question ID for each one. The author answers those IDs from its own role-scoped session. The reviewer then reads the answers back through the server. The resulting Intent Document can distinguish author-attested answers from text supplied by the reviewer.

This matters because traceability is more useful than confident prose. The review can show which assumptions came from the implementation session, which conclusions came from reading the diff, and which questions remain unresolved.

Repository rules arrive as bounded questions

Generic AI-powered code review cannot know every invariant your team learned from production incidents. Review Assist lets a repository carry those questions in a .reviewer/ folder: for example, whether a schema change includes its migration, whether a critical path has the required test, or whether churn in a sensitive directory is intentional.

Those files cannot override the protocol or weaken validation. They can only add or sharpen questions. That keeps repository-specific knowledge close to the code without turning untrusted pull-request content into instructions with unlimited authority.

Five deterministic gates catch drift before publication

The language-model review is not the final authority. Before Review Assist writes an Intent Document, the MCP server applies repository consent and runs five local checks:

• —Schema. The document matches the frozen Intent Document format.
• —Coverage. Every substantive diff hunk is anchored to the guided tour or named as unexplained.
• —Staleness. The document still describes the current change rather than an older commit.
• —Cross-references. IDs and links inside the document resolve consistently.
• —Secret redaction. Likely credentials or sensitive values do not leak into the committed document.

These checks convert review quality from a suggestion into a gate. A fluent explanation cannot compensate for an uncovered hunk, a stale head, or a malformed reference.

The feedback loop lands while the code can still change

The Intent Document is built for the eventual human reviewer, but Review Assist produces another output sooner: the cold reviewer’s closing report. It returns unanswered questions, anything marked not verified, and defects exposed while reading the diff.

That timing is the practical reason the architecture catches bugs early. Findings do not wait for someone to open the pull request. They return to the active coding session, where the implementation can be corrected and the checks rerun.

The architecture has already caught its own defects

During development, the cold-review pattern found a schema integration bug that 124 passing unit tests had missed: a real run summary contained more fields than the strict document schema allowed, so every submission would fail. The reviewer found it by tracing the actual data across component boundaries, not by inspecting an isolated function.

A later distillation found four defects in the repository-instructions feature before release, including inconsistent definitions of whether a .reviewer/ folder was present. These are exactly the bugs that hide between locally correct components.

What Review Assist does and does not replace

Review Assist does not replace tests, static analysis, security scanning, or human judgment. It addresses a different failure mode: loss of intent and weak challenge of an agent’s assumptions. Its automated code review architecture gives the human reviewer a verified map of the change and gives the coding session an earlier chance to fix what a cold reader cannot justify.

The result is a shorter path from “the agent says it is done” to “the change is ready to review.” Read the architecture, then let your next coding session produce a guided, verifiable review.