Architecture review scope
Used in the playbook Architecture review, stage 1.
Download architecture-review-scope.md — the source, as in the repository.
How to use
The template's own instructions:
Playbook arch.architecture-review, stage 1, rule R1. One page. The decision owner agrees it before any evidence is gathered. Replace every [bracketed] value; delete these comments when the scope is agreed.
Fields
Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).
| Field or section | Where | Required |
|---|---|---|
title | front matter | required |
status | front matter | required |
version | front matter | required |
date | front matter | required |
owner | front matter | required |
| Review | section | required |
| Question and decision | section | required |
| System and boundary | section | required |
| Inputs and access | section | required |
| Permissions and handling | section | required |
| Agreement | section | required |
Example
A filled-in copy for an invented product, templates/examples/architecture-review-scope.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.
---title: Architecture review scope — Example shopstatus: agreedversion: 0.1.0date: 2026-04-02owner: Alex Doe, owner---
# Architecture review scope — Example shop
## Review
| Field | Value ||---|---|| Review id | AR-2026-04-example-shop || Variant | inherited system || Decision owner | Alex Doe, owner — agrees this scope, ranks scenarios, decides on findings || Reviewer | the lead agent || Independent reviewer | a separate agent session — re-checks Critical and High findings (R13) || System experts | the shop's previous developer; the hosting provider || Report goes to | Alex Doe || Timebox | 3 days, from 2026-04-06 to 2026-04-08 || Planning horizon | six months — the horizon for the likelihood in severity (R7) || Scope status | agreed by the decision owner on 2026-04-02 (R1) |
## Question and decision
- **Question:** Can the shop be upgraded to the current platform version without a rebuild?- **Decision it informs:** upgrade in place, or quote a rebuild- **Known business goals and constraints:** budget of 10 agent-days; no downtime during the spring sale- **Known concerns:** the platform's runtime is out of support
## System and boundary
- **In scope:** production and staging web shop, its database, the payment and delivery integrations.- **Out of scope:** visual design (see HIF), content, third-party SaaS internals.
## Inputs and access
| Input | Where | Access | Granted by | Status ||---|---|---|---|---|| Repository | the client's Git host | read | Alex Doe | works || Copy of files and database | a dump taken by the host's backup tool | read | hosting provider | requested || Hosting control panel | the provider | read-only user | hosting provider | works || Interviews | the previous developer | written answers | Alex Doe | requested |
## Permissions and handling
- **Live system:** read-only (R2). Active testing permitted: no.- **Secrets:** stored only in the project's secret store; never in the report, issues or chat (R11).- **Personal data:** present in the database copy; kept on the review machine, deleted on 2026-04-30.
## Agreement
| Decision owner | Date | Note ||---|---|---|| Alex Doe | 2026-04-02 | agreed |Completion checks
A copy is complete when:
- every required field and section above is present, in the same order, and no bracketed placeholder is left;
- the template's comments are deleted from the copy;
- the exit criteria of stage 1 of the playbook Architecture review are met;
- the owner has approved it, where the playbook asks for approval. Only the owner sets
approved.
Source
templates/architecture-review-scope.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.
---title: Architecture review scope — [system]status: draft # draft | agreedversion: 0.1.0date: YYYY-MM-DDowner: [decision owner]---
# Architecture review scope — [system]
<!-- Playbook arch.architecture-review, stage 1, rule R1. One page. The decision owner agrees it before anyevidence is gathered. Replace every [bracketed] value; delete these comments when the scope is agreed. -->
## Review
| Field | Value ||---|---|| Review id | AR-YYYY-MM-[system] || Variant | [own product / inherited system / proposed design / documents of a design under construction] || Decision owner | [name, role] — agrees this scope, ranks scenarios, decides on findings || Reviewer | [person or agent] || Independent reviewer | [person or separate agent session] — re-checks Critical and High findings (R13) || System experts | [maintainers, hosting provider, client staff] || Report goes to | [names] || Timebox | [n] days, from YYYY-MM-DD to YYYY-MM-DD || Planning horizon | [until release X.0 / six months / before a launch: until the launch plus [n] weeks of observation] — the horizon for the likelihood in severity (R7) || Scope status | [agreed by the decision owner on YYYY-MM-DD / taken from the brief [link], not confirmed by the decision owner — missing fields filled with the defaults stated here] (R1) |
## Question and decision
<!-- One question the review answers and the decision that waits for the answer. A review without a decisionbehind it turns into an opinion survey. -->
- **Question:** [Can the shop be upgraded to platform version N without a rebuild?]- **Decision it informs:** [upgrade in place, or quote a rebuild]- **Known business goals and constraints:** [budget, deadline, regulations, hosting limits]- **Known concerns:** [what prompted the review]
## System and boundary
- **In scope:** [systems, containers, environments — for example production and staging web shop, database, payment and delivery integrations]- **Out of scope:** [for example visual design (see HIF), content, third-party SaaS internals]
## Inputs and access
<!-- Read-only access only (R2). Each input becomes one or more evidence ids during stage 2. -->
| Input | Where | Access | Granted by | Status ||---|---|---|---|---|| Repository | [URL] | read | [name] | [requested / works] || Decision records, blueprint | [path] | read | | || Copy of files and database | [how the copy is taken without touching the live system] | read | | || Hosting or control panel | [provider] | read-only user | | || Logs and metrics | [where] | read | | || Interviews | [who] | written answers | | |
## Permissions and handling
- **Live system:** read-only (R2). Active testing permitted: [no / yes — what, when, written permission reference].- **Secrets:** stored only in [the project's secret store]; never in the report, issues or chat (R11).- **Personal data:** [present / not present] in copies; copies kept at [where], deleted on [date].
## Agreement
| Decision owner | Date | Note ||---|---|---|| [name] | YYYY-MM-DD | [agreed / agreed with changes] |