review

Architecture Designer — Review and Revision Workflow

This skill reviews an existing architecture (from a document, the codebase, or both), presents findings, and guides the user through a structured revision process that creates a new versioned document.

Scripts directory: see "Path resolution" at the bottom of this file.

References directory: this skill has none of its own — every design/references/... pointer below resolves into the sibling design skill's references/ directory, per "Path resolution" at the bottom of this file.

---

Before starting — load and validate session context

Check for docs/architecture-designer/session.json:

• If the file exists: read it in full, then run python3 <scripts_dir>/validate-session.py and show its output — this is a hard gate; do not proceed to Step 1 until it reports SESSION CHECK PASSED. See design/references/session-schema.md section "Session completeness gate" for what the script checks and how to resolve a failure (e.g. running /architecture-designer:design to fill the gaps). The session contents are the original requirements baseline the architecture-reviewer and any revision agents review against.

• Also check for an interrupted revision in progress: if session.json contains a progress key whose lastCompletedStep is anything before step11 (a document save) and its owner is "review", a previous revision session died mid-pipeline. Apply design/references/session-schema.md section "Resuming Steps 6a–13 via progress" to resume Step 4's revision flow from where it left off instead of restarting Step 4a — including validating any recorded reviewCycles verdicts' hashes and checking docs/architecture-designer/last-review.md for an unresolved fixer cycle. If progress.owner is instead "design" (or absent) with lastCompletedStep before step11, this is an original design pipeline that never finished — not a review revision — since review never touches progress before step 4b and no revision document was ever produced to revise. Do not attempt to resume Step 4 from this state (there is no revision scope, no document to list in Step 2a). Instead tell the user: "It looks like a previous /architecture-designer:design session didn't finish (no architecture document was ever saved). Run /architecture-designer:design to complete it before reviewing." and stop here rather than proceeding to Step 1.