Skip to content

Architecture review (skill)

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.

Download SKILL.md — the skill, as in the repository.

When to use

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.

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.