Reviewer Skill

The reviewer skill is the VALIDATE step of the Archgate development workflow. It checks every code change against the project’s Architecture Decision Records (ADRs) and blocks anything that drifts from a documented decision. It runs after code is written and before it is committed.

What It Does

The reviewer gathers all the data it needs in a single archgate review-context call, then delegates verification to focused sub-agents — one per affected domain, plus an always-on General/Process sub-agent. Each sub-agent runs in its own context window so that reading every changed file never exhausts the parent agent’s context; only the concise compliance report flows back.

It enforces four things on every change:

• Domain-relevant ADRs were read before implementation
• Code complies with all applicable ADRs (the Do’s and Don’ts)
• No architectural drift from documented decisions
• File structure, naming conventions, and dependency boundaries are respected

Pre-validation requirement

The reviewer assumes the developer agent workflow, which requires ADRs to be read before writing code. It validates the result of that workflow — it is not a substitute for reading the ADRs up front.

How It Works

1. Gather context. It runs archgate review-context --run-checks, which returns every changed file, those files grouped by domain with the applicable ADR briefings (Decision plus Do’s and Don’ts), and the automated check summary — all in one JSON response. By default it inspects unstaged changes against the main branch; --staged is used only when files have been explicitly staged.

2. Short-circuit on automated failures. If the automated check summary reports a failure, the reviewer blocks immediately and reports the failures — it does not proceed to manual review until they are fixed. If there are no changed files, it reports approved with no review needed.

3. Launch domain sub-agents in parallel. For each affected domain it spawns a sub-agent (always including a General/Process sub-agent). Each receives its changed-file list and the relevant ADR briefings inline, reads each file, and verifies it against the Do’s and Don’ts. Sub-agents run on a lightweight model because this is checklist verification, not open-ended reasoning.

4. Aggregate the results. Once every sub-agent returns, the reviewer produces one compact compliance report.

Output Format

The skill returns a concise, structured verdict — APPROVED or BLOCKED — with a per-domain breakdown and counts of violations and warnings:

## Reviewer: APPROVED
- Automated checks: PASS (3/3)
- General/Process: PASS
- Backend: PASS_WITH_WARNINGS
- Violations: 0 | Warnings: 1
⚠ BE-002 src/api/handler.ts — Error responses use string messages instead of
  the error code enum. Not a violation but drifts from the recommended pattern.

The decision rules are strict:

• APPROVED — all automated checks pass and every domain returns PASS or PASS_WITH_WARNINGS. Every warning is listed so you can make an informed decision; warnings never block.
• BLOCKED — any automated check fails or any domain returns FAIL. Each violation is reported with its ADR ID, file path, line number where possible, what is wrong, and how to fix it.
• ESCALATE — the change exposes a gap the existing rules do not cover well. The reviewer flags it so the lessons-learned skill can capture it.

The report is deliberately minimal. ADR violations are hard blockers: the reviewer refuses to approve non-compliant code, references the violated ADR, and provides fix guidance.

How It Fits the Workflow

The reviewer is step 4 of the developer workflow:

UNDERSTAND → PLAN → WRITE → VALIDATE → CAPTURE
                            (reviewer)

The developer agent runs archgate check first for fast automated validation, then invokes the reviewer for the thorough, domain-aware pass. After the reviewer approves, control passes to the lessons-learned skill for the CAPTURE step. For minor follow-up tweaks the agent skips the reviewer and runs archgate check alone.

lessons-learned skill The CAPTURE step that runs after the reviewer approves.

Note

For the exact syntax and output of archgate review-context and archgate check, see the authoritative reference at cli.archgate.dev.