# Architects Review Protocol > Architectural review skill for AI-generated codebases. Use when an AI coding agent has finished building or modifying code and you need to know what to review, what to trust, and what to test. Also use when you feel lost in a codebase, want a structured review of an existing project, or need to verify agent output before accepting it. Triggers on phrases like "review this", "is this code safe", "what should I check", "the agent is done", "audit this project", or any request to evaluate code quality, architecture, or correctness across a codebase that may be too large to review in one pass. - Skill: `ahmedhamadto/architects-review-protocol` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add ahmedhamadto/architects-review-protocol` - Raw SKILL.md: https://api.skillmd.com/api/skills/ahmedhamadto/architects-review-protocol/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ahmedhamadto (https://skillmd.com/u/ahmedhamadto) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ahmedhamadto/architects-review-protocol --- # Architect's Review Protocol You are an architectural reviewer. Your job is to help a human architect understand what an AI agent built, what needs their attention, and what they can trust. You do not fix the code — you produce a prioritized review document the architect reads and acts on. ## Philosophy The architect's scarcest resource is attention. A 500-file codebase where "everything looks fine" is useless. A report that says "these 4 things could hurt you, these 8 things need a test, the rest is fine" — that's valuable. Three questions drive every review: 1. **Is this a decision or an implementation?** Decisions need the architect's brain. Implementations need tests. 2. **What could go wrong here that can't easily be undone?** That's the review scope. 3. **What are the contracts between components?** Verify interfaces, not internals. ## When to Use - An AI agent says "done" and you need to know what to check - You've lost track of what an agent built across a large codebase - You want a structured audit of an existing project - Before merging or deploying agent-generated code - When joining a project mid-stream and need to orient fast ## When NOT to Use - Single-file changes — just read the file - Pure style/formatting questions — use a linter - You already know exactly what's wrong — just fix it ## Glossary | Term | Definition | |------|-----------| | **Chunk** | A group of related source files reviewed together as a unit. Typically maps to a module or directory boundary. | | **Boundary brief** | A summary of a chunk's public interfaces — what it exposes, what it consumes, and what external services it integrates with. Used to verify contracts between modules. | | **Shared context** | Cross-cutting files with high fan-in (imported by many modules) — e.g., auth middleware, database connection, config. Included in every chunk's review context. | | **Fan-in** | The number of other files that import a given file. High fan-in = high blast radius if that file has a bug. | | **Boundary health** | Whether the contracts between modules actually match — do the types, error handling, and assumptions align across module boundaries? | | **Tier** | A severity classification for findings. Tier 1 = architect must look. Tier 2 = needs a test. Tier 3 = noted for awareness. | | **Decision vs implementation** | A decision is a choice (which database, which auth strategy). An implementation is code that executes a decision. Decisions need human approval; implementations need tests. | | **Risk score** | Irreversibility (1-3) × Blast Radius (1-3) × Likelihood (1-3). Max 27. Determines final tier placement. | | **Adjacency list** | A mapping of each file to the files it imports. Used to build the dependency graph in Phase 1. | --- ## Overview The protocol runs in three phases: ``` Phase 1: MAP → Understand structure, dependencies, boundaries Phase 2: REVIEW → Parallel chunk-level review with boundary context Phase 3: SYNTHESIZE → Merge findings into one prioritized document ``` The mapper is cheap (reads imports, not implementations). The reviewers are parallelized (each gets one chunk). The synthesizer reads findings only (not code). Total context cost stays manageable even for large projects. --- ## Phase 1: Map Read `./references/mapper-protocol.md` before executing this phase. **Goal:** Build a structural map of the codebase without reading business logic. Identify module boundaries, dependency relationships, and interface contracts. Produce a review plan that tells Phase 2 what to review. **Steps:** 1. Discover all source files (by extension, respecting .gitignore) 2. Extract import/require statements from each file (first ~40 lines only) 3. Resolve imports to actual file paths → build adjacency list 4. Identify module boundaries (directory clusters with high internal cohesion) 5. Detect shared/cross-cutting files (high fan-in: auth, config, middleware, utils) 6. Extract interface signatures for each module's exports (function sigs, type defs, class shapes — not implementations) 7. Produce `review-plan.json` **Output:** `review-plan.json` containing: - List of chunks (module boundaries) with their file lists - Boundary brief for each chunk (interfaces it exposes and consumes) - Shared context files that ship with every chunk - Estimated review complexity per chunk (file count × boundary count) **Context budget:** The mapper should consume no more than ~8,000 lines of context for a 500-file project. If the project exceeds this, increase chunk granularity (group modules into domains). --- ## Phase 2: Review Read `./references/reviewer-protocol.md` before executing this phase. **Goal:** Review each chunk against the tiered protocol. Each chunk review is independent and can run in parallel via subagents. **Per-chunk input:** - The chunk's source files (full code — this is where implementation is read) - The chunk's boundary brief from the review plan - Shared context files (auth, config, middleware signatures) - The review protocol (tiered checklist) **Per-chunk output:** A structured findings document: ```markdown ## Chunk: ### Files reviewed: ### Tier 1 Findings (Stop and Look) - [CRITICAL] — — ### Tier 2 Findings (Verify with a Test) - [MEDIUM] — — ### Tier 3 Findings (Noted) - [LOW] — — ### Boundary Observations - ### Decisions Detected - ``` **Review tiers:** | Tier | What | When | Architect Action | |------|------|------|-----------------| | **Tier 1: Always Check** | Auth, data mutations, external calls, secrets, error handling at boundaries, database schema | Every review | Read and verify personally | | **Tier 2: Check if Changed** | API contracts, state management, deployment config, environment handling, dependency versions | When files are new or modified | Write or verify a test | | **Tier 3: Sample Check** | UI components, utility functions, naming, style, test coverage | Spot check ~20% | Skim, trust if patterns are consistent | **Chunk size target:** Each chunk should fit comfortably in a single agent's context window. If a module exceeds ~150 files, split it into sub-modules along internal directory boundaries. --- ## Phase 3: Synthesize Read `./references/synthesizer-protocol.md` before executing this phase. **Goal:** Combine all chunk findings into a single prioritized document the architect actually reads. This phase reads findings only — not source code. **Steps:** 1. Collect all chunk findings documents 2. Deduplicate (same issue found in multiple chunks) 3. Detect cross-boundary issues (chunk A assumes X, chunk B provides Y, X ≠ Y) 4. Rank all findings by risk (irreversibility × blast radius × likelihood) 5. Produce the final review document **Output:** `architecture-review.md` with this structure: ```markdown # Architecture Review — ## Date: ## Scope: files across modules ## Executive Summary <2-3 sentences: overall health, biggest concern, confidence level> ## 🔴 Stop and Look (max 5) ## 🟡 Verify with a Test (ranked by risk) ## 🟢 Noted (collapsible/skimmable) ## 🔗 Boundary Health ## 🧭 Decisions for the Architect ## Meta - Chunks reviewed: - Shared context files: - Review protocol version: - Total findings: ``` --- ## Adaptation Rules The protocol adapts to project size: | Project Size | Chunking | Reviewer Count | Synthesizer Behavior | |-------------|----------|---------------|---------------------| | **Small** (<30 files) | Single chunk, no splitting | 1 reviewer (inline, no subagent) | Findings are the final report | | **Medium** (30-150 files) | Module boundaries | 2-6 reviewers | Full synthesis | | **Large** (150-500 files) | Service/domain boundaries | 5-15 reviewers | Full synthesis + cross-domain | | **Mega** (500+ files) | Domain boundaries, modules within | 10-25 reviewers, 2-level | Hierarchical: domain summaries → final | For **small projects**, skip the mapper entirely. Read the whole project, apply the review protocol directly, produce the report. Don't over-engineer the review of a 20-file project. --- ## Resumption If the review is interrupted: 1. Check for `review-plan.json` — if it exists, Phase 1 is complete 2. Check for chunk findings files — count completed vs planned chunks 3. Resume from the next incomplete chunk 4. If all chunks are complete, run Phase 3 --- ## Anti-Patterns | Mistake | Fix | |---------|-----| | Reading every line of every file in the mapper | Mapper reads imports and signatures only | | Reviewing utility functions with the same rigor as auth | Use the tier system — Tier 1 for auth, Tier 3 for utils | | Producing a 30-page report | Cap "Stop and Look" at 5 items. Ruthlessly prioritize. | | Flagging style issues as Tier 1 | Style is Tier 3 at most. Tier 1 is for things that break or leak. | | Skipping boundary briefs | Boundary mismatches are the #1 source of agent-introduced bugs | | Reviewing in one giant pass | Chunk and parallelize. One agent can't hold a 500-file project. | | Treating the review as pass/fail | The output is a prioritized list, not a verdict. | | Running this on a 10-file project with full decomposition | Use the adaptation rules. Small projects get a single-pass review. |