Skip to content

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 sectionWhereRequired
titlefront matterrequired
statusfront matterrequired
versionfront matterrequired
datefront matterrequired
ownerfront matterrequired
Reviewsectionrequired
Question and decisionsectionrequired
System and boundarysectionrequired
Inputs and accesssectionrequired
Permissions and handlingsectionrequired
Agreementsectionrequired

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.

example-architecture-review-scope.md
---
title: Architecture review scope — Example shop
status: agreed
version: 0.1.0
date: 2026-04-02
owner: 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.

architecture-review-scope.md
---
title: Architecture review scope — [system]
status: draft # draft | agreed
version: 0.1.0
date: YYYY-MM-DD
owner: [decision owner]
---
# Architecture review scope — [system]
<!-- 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. -->
## 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 decision
behind 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] |