AI review

AI review has a model read your design doc and tell you what's wrong with it. It reads the whole doc, checks it against the rest of your organization's documentation and the code in your repositories, and records findings you can resolve, dismiss or post as comments. You can keep talking to it about the doc for as long as the review exists.

AI review is in early access. Email hello@archdocs.io to turn it on for your organization. It needs AI credits, so it's available on Team and above.

A review is advice. It never approves a variation, marks one ready or counts toward required approvals. Only people do that.

Start a review

1. Open the design doc and select AI review in the header.
2. Select New review.
3. Choose Review the doc, or Try to break this plan to look for concrete ways the change could fail (see Try to break this plan).
4. Pick a model. Search by name or provider and compare the credit rates. You can only pick models your organization allows from providers it has turned on.
5. Optionally add a Focus, such as "API boundaries" or "migration safety". The reviewer still reads the whole doc. The focus tells it where to spend more attention.
6. Check the repositories. The list starts with the repos linked to this doc. Change a ref or add another connected repo if your organization allows it. Choose Docs only, no code to review without reading code.
7. Select Start review.

Starting a review needs docs:write and ai:use. Anyone with docs:read can open the panel and read reviews.

The panel opens beside the doc on wide screens and as a side sheet on narrow ones. Findings appear as the reviewer records them.

What the reviewer reads

Every review starts from the whole design doc. That includes every variation, open questions, the work log and comment threads. You can see this doc, so the reviewer reads it with your access.

The reviewer first tests the doc's premise and looks for better approaches before checking the details. It is told to recommend a better design when the evidence supports one, including an approach that contradicts an approved spec or plan. An approval does not prove the design is right.

To check the doc against everything else, the reviewer can search and read other design docs, ADRs, objects, diagrams and their dependencies. These lookups only return records visible to the whole organization. Private docs and docs in someone's My docs never reach the reviewer unless they're the doc under review.

Code comes from the repositories on the review. A repo counts as linked when the doc has a code location in it, a pull request linked from it, or a catalog object that points to it. Each repo is pinned to a commit when the review starts, so every finding cites code you can open at that exact commit. Reading code needs the GitHub integration connected to the repositories.

If the reviewer needs a repo that isn't on the review, it asks. A card in the conversation names the repo and why it wants it. Select Allow for this review to add it, or Not now to keep going without it.

Where the code goes

Repositories are never cloned onto a shared server. Each review gets its own short-lived sandbox, a container kept apart from the servers that run ArchDocs. No two reviews share a sandbox, and sandboxes have no open ports.

ArchDocs clones the pinned commits into the sandbox with a GitHub token limited to those repos with read access. The token is revoked as soon as the clone finishes. After that the reviewer can only run a fixed set of read commands. It can search code, read specific lines of a file, list files and compare two commits. It can't run your code, install anything or open a shell.

A sandbox is deleted after 10 minutes without activity, and always within an hour of being created. Deleting a review deletes its sandbox too.

The code excerpts the reviewer read are saved with the review. That's how a conversation can continue after the sandbox is gone. When you come back and the reviewer needs more code, it gets a fresh sandbox at the same commits.

Web research

When web research is available, the reviewer can search the web and read public pages through Cloudflare to check facts, current limits and prior art. Findings cite the pages it used.

Queries are written as general technical questions. The reviewer is told never to include customer or company names, people's names, internal identifiers, secrets or code in a search. Searches go through Cloudflare to a search provider.

Admins can turn web research off under Settings > AI. Research is billed with the review's credits. When web research is unavailable, the reviewer is told to say which claims it could not verify.

Findings

Each finding has one of five kinds.

• Premise means an assumption behind the design is wrong, unproven or out of date.
• Better approach means another solution would work better, with an explanation of its trade-offs.
• Risk means the design could fail, break something or cause harm in a specific way.
• Gap means something the change needs is missing from the doc.
• Inconsistency means the doc contradicts itself, the code, an ADR or another doc.

Premise and better approach findings are listed first.

Each finding has a severity of High, Medium or Low. It explains the problem and shows its evidence. Code evidence names the repo, file and line range, and links to that range on GitHub at the pinned commit. Evidence from another doc or record links to it in ArchDocs. When a finding is about a specific passage, hover it to highlight that passage in the doc.

Filter the list by Open, Resolved and Dismissed. Each finding has these actions.

The header's AI review button shows the number of open findings across all of this doc's reviews.

Try to break this plan

Choose Try to break this plan at the top of the New review dialog, or from the button in the review panel, when you want the reviewer to look for concrete ways the change could fail. It does everything a normal review does. It still reads the whole doc, tests the premise and looks for a better approach, and then it works harder on failure.

For each concern it names what is at risk (a requirement, a commitment or an assumption, marked as inferred when the doc never states it), builds the sequence of events that would break it, and looks for anything that would stop that sequence before it reports. If a safeguard already prevents the failure, the concern is dropped or downgraded. A break review that finds nothing it can support says so. It does not invent a finding to have one.

It looks across plans, not just at this one. The reviewer lists other design docs that change the same catalog objects, so it can catch two changes that are each fine alone and unsafe together. It cites the other plan's exact version. When it can't tell whether both will be live at the same time, that becomes a condition of the finding. A shared service name alone is never treated as a conflict.

It also looks at the steps between states, such as mixed versions during a rollout, queued messages and rollbacks that restore old code over new data. It follows identity and tenant context past the first permission check, and it asks whether the evidence on the doc actually tests the claim it's cited for.

Reading a failure finding

A finding from a break review can carry a failure scenario. The card leads with At risk, the property the failure breaks, followed by the numbered steps of the failure. Involves lists the plans and components in the scenario, each marked current or proposed. A label says how well supported the scenario is. Possible failure, needs facts means it depends on things the reviewer couldn't confirm. Source-backed conflict means it rests on sources the reviewer read or on an exact comparison of stated values.

Open Why the reviewer thinks so for the preconditions (observed or assumed), the safeguards it checked, the gaps in the evidence, the consequence and the mitigations with their trade-offs. Neither label means the failure has happened. A source-backed conflict shows that stated constraints don't fit together, not that an incident will occur.

Test it and report back

Most failure findings include a Check, a test someone can run. It lists the pinned sources, setup, steps, the invariant that should hold and the signal that it didn't. Select Copy as task to copy it as markdown for an engineer, a coding agent or a CI job. The reviewer never runs your code itself.

When the check has run, select Attach result on the finding. Record whether the failure reproduced, didn't reproduce or was inconclusive, and the repository, commit and environment it ran against. A failed reproduction can be real counterevidence or a test that missed a precondition, so say which. The result is saved as a test entry in the doc's work log and linked from the finding, as reported activity. It doesn't change the finding's status or count as verification evidence for acceptance criteria. Agents can attach results with attach_ai_finding_result.

The card then shows Check attempted with the outcome. If the result ran against a different commit than the finding cites, the card says so.

When sources change

Each finding remembers the versions of the docs and the commits it cited. When one of them changes, the finding shows Sources changed, needs reassessment with what changed. On a re-review the reviewer rechecks those findings and says whether each still holds, changed or no longer applies. Earlier text, evidence and results stay in the finding's history, and an old result never vouches for newer code.

Evidence the reviewer read

A finding can only cite what the reviewer actually read in that review, meaning the lines of code it opened at that commit, the records it opened and the pages it read. A search result alone doesn't count. ArchDocs checks this when the finding is recorded and stamps each citation with the version it read. This applies to every review, not just break reviews.

When a review hit its turn or length limit, couldn't read a repository, lost web research, had tool calls fail, or was stopped or interrupted, the Findings tab says Review incomplete and lists why, instead of showing an empty list as if nothing were wrong. Send a follow-up or select Re-review to continue.

Keep the conversation going

The Conversation tab holds everything said in the review. Ask why it raised something, push back, or ask it to look at a part of the doc again. The review keeps its context between visits, so you can return days later and pick up where you left off.

Coming back after a break starts a new session in the conversation, with a short note on what changed in the doc since the last one. The reviewer keeps reading the same commits it read before, so its earlier findings still line up with the code.

When the doc has changed since the review last read it, the panel says which variation changed and shows Re-review. A re-review reads the doc again, moves each repo to the latest commit on its branch and compares it with the commits from last time. The reviewer then adds new findings and marks earlier ones it now sees as fixed. A finding someone dismissed stays dismissed.

You can switch models from the chip in the composer. Select Stop to end a response early.

If a model declines to continue, the conversation says so. Pick another model, such as Claude Opus 4.8, and send your message again.

Choose a model and who controls providers

AI review offers every current text model from Anthropic, OpenAI and Google that can use tools. The searchable picker groups models by provider and shows each model's credit rate compared with Claude Sonnet 5.5.

Anthropic is on by default. Turning a provider on lets it read this organization's docs and the code a review pulls in. Admins with org:manage can turn providers on or off and choose which models are allowed under Choose models in Settings > AI. Turned-off models do not appear in the picker and cannot be used by anyone, including automatic reviews and agents.

Open Settings > AI to change these settings. They save as you change them.

• Turn each provider on or off and choose which models are allowed.
• Choose code access, either Linked repos, and members can add more (the default) or Linked repos only.
• Allow or turn off web research.
• Set up automatic reviews.
• Let agents start reviews over MCP.

Each provider row links to that provider's own data handling terms.

Credits

Free includes 10 design docs. Your organization gets one free AI review per design doc, up to 10 reviews in total. A member must start the review in the app. Deleting a review or its design doc never gives a free slot back. Automatic reviews and reviews started over MCP aren't available on Free.

Free reviews always use Claude Sonnet 5.5. You can choose either review lens. Web research and code access work as they do on paid plans, within the free review's budget. Anthropic must be enabled in your organization's AI settings.

A free review covers the first turn only, with a $1.50 limit on model and web research costs. When it reaches that limit, the turn stops. The review is marked incomplete and includes a short notice. After the first turn, the conversation is read-only. Follow-ups, Discuss and Re-review need a paid plan. If you upgrade to Team, you can continue the same conversation, and later turns use AI credits.

ArchDocs pays for free reviews. Free organizations have no AI credits, and a free review doesn't charge credits. ArchDocs still records its usage and cost.

On paid plans, a review uses AI credits from your organization's shared balance, the same pool as Ask AI and diagram generation. Each turn is charged from that model's own per-token prices for input, output and cached tokens. The same review costs more credits on a higher-rate model. A long review of a large doc with a lot of code also costs more than a short one.

Team stops new turns when the included credits run out. Business and Enterprise continue into billed overage up to any cap you've set.

Automatic reviews

An organization can start a review on its own when a design doc reaches a milestone. In Settings > AI, pick a model under Automatic reviews and turn on either trigger or both.

Automatic reviews use linked repos only and are attributed to the person who triggered them. Each variation version triggers at most one automatic review per trigger. If the organization is out of credits, no review starts and ArchDocs leaves a note on the doc saying it was skipped, in the work log when the doc has one and as a comment otherwise.

AI reviews over MCP

Agents connected through the MCP server can read reviews with list_ai_reviews and get_ai_review, so an agent working on a doc can pick up open findings. These need docs:read.

Starting a review with start_ai_review is off by default. Turn on Agents may start AI reviews over MCP in Settings > AI to allow it. The agent's user needs docs:write and ai:use, and the review is charged to the organization's credits like any other. The tool returns a link to the review, and the review keeps running after the tool returns. Pass lens: "break" to start a Try to break this plan review. An agent that ran a finding's check can report the outcome with attach_ai_finding_result, which needs docs:write and records the result in the work log. See the tool reference for inputs.