---
name: architecture-review
description: Run an evidence-based architecture review of an existing or proposed system — own product, inherited client site, or a design before approval — following the UASK Engineering Hub playbook arch.architecture-review. Use when asked to review, audit or assess an architecture, take over an inherited site, judge whether an upgrade or rebuild is needed, check a blueprint before it is approved, or review the documents of a design that is partly built.
license: CC-BY-4.0
metadata:
  hub-id: arch.architecture-review
  hub-version: 0.2.2
---

# Architecture review

This skill tells an agent how to apply the playbook `arch.architecture-review`. The playbook holds the rules
(`arch.architecture-review#R1` … `#R18`) and the stages; this file only says how to carry them out. When the two
seem to differ, the playbook wins.

## Read first

| What | Id or path |
|---|---|
| The playbook | `arch.architecture-review` — in the Hub repository `content/playbooks/architecture-review.md`; in a consumer project under `.uask/hub/` |
| Diagram rules | `arch.c4-model` |
| Decision records | `arch.adr` |
| Backups, when the system holds data | `ops.backups` |
| Acceptance criteria, when documents are reviewed | `req.acceptance-criteria` |
| How much of this the project needs | `mgmt.governance-tiers` |
| Interfaces and websites | `hif.evaluation`, `hif.web-audit-playbook` |
| Operating systems | `scf.constitution`, `scf.evaluation` |
| Templates | `templates/architecture-review-scope.md`, `templates/architecture-review-report.md` |

Put the review files where the project's `AGENTS.md` says; if it says nothing, use
`docs/reviews/<review id>/` with `scope.md`, `report.md` and the diagram sources.

## Steps

1. **Scope (stage 1).** Copy the scope template and fill it from the request. If a brief names the decision
   owner, the question, the system boundary and the access, use it as the scope: copy it into section 2 of the
   report, fill the missing fields (horizon, recipients, timebox) with stated defaults, and mark the scope "taken
   from the brief, not confirmed by the decision owner" (`#R1`). Otherwise ask the decision owner for the missing
   fields and stop until they answer. Never mark a scope agreed yourself. Before a launch, set the horizon to the
   launch plus an observation window and state its length.
2. **Evidence (stage 2).** Work read-only (`#R2`): read the repository, configuration and copies; do not run
   scanners or load tests against a live system unless the scope records written permission. Give every piece an
   evidence id in report appendix A as you go; one id may stand for a whole file, cited as `E-12:340`. Never print
   or store secret values (`#R11`): when a file contains one, record the file and the type of secret only. Where a
   document quotes a number from a result, recount it from the result file (`#R17`). Write the questions only the
   system experts can answer into appendix C, with the addressee and the finding each affects. For documents under
   review, start the claims register (`#R16`).
3. **As-is views and inventory (stage 3).** Draw the Context and Container views from what you found, as diagram
   code next to the report (`#R3`, `arch.c4-model`). Build the component inventory (`#R4`) from manifests and lock
   files (`composer.lock`, `package-lock.json`, the platform's extension list, the runtime's version output); look up
   support status at `https://endoflife.date/api/<product>.json` and known exploited vulnerabilities in the CISA KEV
   catalogue; if you have no network access, write "not checked" in the row and list it in section 2, never drop
   the row. Mark each component installed, planned or not confirmed. For an inherited system, diff vendor code
   against a pristine download of the same release. If the documents already hold diagrams, check them against
   `arch.c4-model` and draw only the missing views — for a replacement, the sequence of the switch-over and its
   rollback. For a replacement or migration also fill the inventory of external interfaces and environment, using
   the checklist in `templates/prd.md` (`#R18`).
4. **Scenarios (stage 4).** Draft the business goals and five to fifteen scenarios with measurable response
   measures (`#R5`); propose a ranking and get the decision owner's agreement before the analysis. If that is not
   possible, mark the ranking "proposed, not agreed" and mark any response measure you supply as a proposal.
5. **Analysis (stage 5).** For each scenario ranked high on importance, trace it through the views and record the
   verdict, risks, non-risks, sensitivity and trade-off points. List the decisions you found and compare them with
   the ADR log (`#R9`). Cite rule ids of the Hub items and standards that apply. Measure where it is cheap. For
   documents under review, complete the traceability table and the table of acceptance criteria with method,
   environment, expected result, who performs it and whether it can be performed there (`#R16`).
6. **Findings (stage 6).** Write each finding with all fields of `#R6` — category (including `inconsistency` and
   `scope-gap` for document defects), basis and, for an assumption, the check; grade it with the table in `#R7`,
   where likelihood is that of the harm, not of the defect. Tell the
   decision owner about a Critical finding immediately, with a mitigation (`#R8`). Group risks into themes (`#R10`).
7. **Independent check.** When you designed or built the system yourself (`#R13`), hand the evidence index and the
   scenarios — not your findings — to a separate agent session or person, ask it to grade the Critical and High
   areas, and reconcile the two reads in the report.
8. **Target and roadmap (stage 7).** Only when the question asks for change: to-be views and a staged roadmap where
   every stage ships and rolls back on its own (`#R14`).
9. **Report (stage 8).** Fill the report template; write section 1 last, in plain language for the decision owner.
   Present it and record a decision per finding of Medium or higher (`#R15`). You record decisions; you do not make
   them.
10. **Follow-up (stage 9).** Open an issue per finding to fix or defer, titled `[<review id> F-nn] <title>` with
    label `architecture-review` and a link back to the finding; draft retrospective ADRs with status `proposed`;
    set the next review date in report section 12.

## Before handing the report over

- Every finding has an evidence id, a basis (evidence or assumption) and a severity that matches the `#R7` table.
- Every number the documents quote from a result was recounted from the result file (`#R17`).
- `grep` the review folder for secret patterns (keys, tokens, passwords, connection strings) and find none. If the
  report leaves the project, also search it for personal names, e-mail addresses, telephone numbers and the
  client's names, and remove or generalise them.
- Section 2 lists what was not examined and every assumption (`#R12`).
- Every Critical finding was already reported when it was found (`#R8`).
- Diagrams have a title and a key (`arch.c4-model`).
- Section 1 answers the question from the scope in one or two sentences.

## Outputs

`scope.md` (agreed), `report.md` (status `final`), diagram sources, issues labelled `architecture-review`, ADR
drafts with status `proposed`.
