# Intermediate Design Review (ARID): [Design or component name]

> Plan and report of an active review of an intermediate design
> following Active Reviews for Intermediate Designs (ARID), described by
> Paul C. Clements of the Software Engineering Institute (SEI), Carnegie
> Mellon University, in technical note CMU/SEI-2000-TN-009 (August
> 2000). ARID combines scenario-based evaluation in the style of the
> ATAM with active design reviews: instead of asking reviewers whether a
> design looks right, it asks the engineers who will use the design to
> solve real problems with it. This template covers the rehearsal phase
> (reviewers, design briefing, seed scenarios, materials), the review
> meeting (scenario brainstorm, prioritisation, application), the issue
> log, the exit decision and follow-up. Replace every `[bracketed]`
> value and every row marked *Example*.

<!--
Guidance: How to use this template
- Use ARID when a design is detailed enough to be used (interfaces,
  services, an SDK, a module contract) but not yet fully documented or
  frozen. For a whole-system architecture with business trade-offs, use
  the ATAM (`architecture/atam-evaluation`) instead.
- Fill sections 1 to 5 during the rehearsal phase, before the meeting.
  Fill sections 6 to 9 during and immediately after the review meeting.
- The reviewers are the design's future users: application developers,
  integrators, test engineers. Not managers, not the designer's peers
  reviewing from a distance.
- The value comes from reviewers writing code or pseudo-code against the
  interfaces. A review in which reviewers only discuss the slides is
  not an ARID.
- Related documents: Low-level design (`architecture/low-level-design`),
  Software design description (`architecture/software-design-description`),
  Interface control document (`architecture/interface-control-document`),
  Microservice specification (`architecture/microservice-spec`), QAW
  workshop report (`architecture/qaw-workshop-report`), Architecture
  review request (`architecture/architecture-review-request`).
-->

## Document control

<!-- Guidance: Identify the design under review, its version at the time of review and who facilitates. The review applies to that version only; a significant design change after the review needs a new review or a delta review. -->

| Field | Value |
|---|---|
| Document ID | [ARD-001] |
| Design under review | [Component, service, library or interface set] |
| Design version reviewed | [Document or repository tag] |
| Lead designer | [@designer] |
| Facilitator | [@facilitator] |
| Review date | YYYY-MM-DD |
| Version | [0.1] |
| Status | [Planned / Rehearsed / Reviewed / Closed] |
| Owner | [@facilitator] |
| Approvers/reviewers | [@lead-designer], [@engineering-manager], [@architecture-lead] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Lead designer | [@name] | [Accept findings / Dispute, with reason] | YYYY-MM-DD |
| Engineering manager | [@name] | [Approve follow-up plan] | YYYY-MM-DD |
| Architecture lead | [@name] | [Proceed / Proceed with conditions / Redesign] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | Review plan drafted |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Rehearsal held; seed scenarios revised, briefing shortened |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Review held; issue log and exit decision recorded |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* All severity 1 issues closed; review closed |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Purpose, scope and method choice](#1-purpose-scope-and-method-choice)
2. [Roles and participants](#2-roles-and-participants)
3. [Phase 1: Rehearsal](#3-phase-1-rehearsal)
4. [Design briefing summary](#4-design-briefing-summary)
5. [Seed scenarios](#5-seed-scenarios)
6. [Phase 2: Review meeting](#6-phase-2-review-meeting)
7. [Scenario brainstorm and prioritisation](#7-scenario-brainstorm-and-prioritisation)
8. [Scenario application log](#8-scenario-application-log)
9. [Issues and findings](#9-issues-and-findings)
10. [Summary and exit decision](#10-summary-and-exit-decision)
11. [Follow-up and traceability](#11-follow-up-and-traceability)
12. [Review effectiveness](#12-review-effectiveness)
13. [Glossary and references](#13-glossary-and-references)

## 1. Purpose, scope and method choice

<!-- Guidance: State what the design is for, which parts are in scope and why ARID is the right review. Pitfall: reviewing a design that is either too early (no interfaces yet, so nothing to apply) or too late (code already written, so findings are expensive). -->

### 1.1 Purpose of the review

[One paragraph: what the design provides, who will build on it, which
decision the review feeds (proceed to detailed specification, release
the interface to consumers, choose between two designs).]

*Example:* The payments team has designed a provider adapter layer
(strategy AS-04 from the CBAM, `architecture/cbam-analysis`) that every
new payment provider integration must use. Six teams will write
adapters against it over the next year. The review checks that the
port interfaces, error model and contract test kit are usable and
sufficient before the interfaces are frozen and documented in the
interface control document.

### 1.2 Scope

| In scope | Out of scope |
|---|---|
| *Example:* `PaymentProviderPort` interface and its operations | Internal implementation of the core payments engine |
| *Example:* Error and retry model exposed to adapters | Provider commercial terms |
| *Example:* Contract test kit and its fixtures | Deployment pipeline for adapters |
| *Example:* Configuration and secrets injection for adapters | Fraud and risk scoring |
| [Item] | [Item] |

### 1.3 Why ARID

| Question | Answer for this design | Points to |
|---|---|---|
| Are the interfaces defined well enough to write calling code? | [Yes / No] | ARID if yes; wait if no |
| Is the main concern usability and fitness of the design for its users? | [Yes / No] | ARID |
| Is the main concern system-wide trade-offs between quality attributes? | [Yes / No] | ATAM (`architecture/atam-evaluation`) |
| Is a formal conformance assessment against a standard needed? | [Yes / No] | ISO/IEC/IEEE 42030 evaluation (`architecture/architecture-evaluation-42030`) |
| Is the design already implemented and in use? | [Yes / No] | Code review or architecture health check (`architecture/architecture-health-check`) |
| Is the budget about a day of reviewer time, not a multi-week evaluation? | [Yes / No] | ARID |

### 1.4 Review objectives and exit criteria

| ID | Objective | Exit criterion |
|---|---|---|
| OBJ-01 | *Example:* Confirm reviewers can implement a typical adapter with the interfaces as designed | All top-priority scenarios solved or blocked only by logged issues |
| OBJ-02 | *Example:* Confirm the error model lets adapters express every provider failure | No unresolved severity 1 issue in the error model |
| OBJ-03 | *Example:* Confirm the contract test kit covers the agreed behaviour | Reviewers can write a passing and a failing test for each scenario |
| [OBJ-nn] | [Objective] | [Measurable criterion] |

## 2. Roles and participants

<!-- Guidance: ARID needs a facilitator who is not the designer, a scribe, the lead designer and about a dozen reviewers drawn from the design's future users. Keep managers as observers if they attend; their presence should not change what reviewers say. -->

### 2.1 Roles

| Role | Responsibility |
|---|---|
| Facilitator | Plans the review with the designer, runs both phases, keeps the group on task, ensures reviewers write code rather than critique slides |
| Scribe | Records scenarios, votes, the code or pseudo-code produced, every issue and every question, with the time it arose |
| Lead designer | Briefs the design, answers questions during application, does not defend or redesign during the meeting |
| Questioners (optional) | Facilitation team members who probe areas reviewers skip, such as error paths and concurrency |
| Reviewers | Future users of the design who propose scenarios and solve them using the design |
| Observers (optional) | Managers or other stakeholders who watch without voting |

### 2.2 Participants

| Name | Role | Team | Represents |
|---|---|---|---|
| [@name] | Facilitator | [Team] | Independent of the design |
| [@name] | Scribe | [Team] | |
| [@name] | Lead designer | [Team] | Design owner |
| [@name] | Reviewer | *Example:* Card acquiring team | Next adapter to be built |
| [@name] | Reviewer | *Example:* Wallets team | Asynchronous provider flows |
| [@name] | Reviewer | *Example:* QA guild | Contract test kit users |
| [@name] | Reviewer | *Example:* SRE | Operability of adapters in production |
| [@name] | Reviewer | [Team] | [Perspective] |

### 2.3 RACI

| Activity | Facilitator | Lead designer | Scribe | Reviewers | Engineering manager |
|---|---|---|---|---|---|
| Select reviewers | A | R | I | I | C |
| Prepare design briefing | C | A, R | I | I | I |
| Prepare seed scenarios | A | R | I | C | I |
| Run review meeting | A, R | R | R | R | I |
| Record issues | A | C | R | C | I |
| Resolve issues | I | A, R | I | C | C |
| Approve follow-up plan | C | R | I | I | A |

R: responsible, A: accountable, C: consulted, I: informed.

## 3. Phase 1: Rehearsal

<!-- Guidance: The rehearsal phase covers steps 1 to 4. The facilitator and lead designer meet, usually for half a day, to choose reviewers, shape the briefing, write seed scenarios and prepare materials. A short dry run of the briefing with the facilitator catches most presentation problems. -->

### 3.1 Step plan

| Step | Activity | Output | Owner | Done |
|---|---|---|---|---|
| 1 | Identify the reviewers | Reviewer list in section 2.2, invitations sent | Facilitator, lead designer | [Yes / No] |
| 2 | Prepare the design briefing | Briefing of about two hours covering the design's purpose, interfaces, data, error handling and a worked example; summary in section 4 | Lead designer | [Yes / No] |
| 3 | Prepare seed scenarios | Seed set in section 5 | Lead designer, facilitator | [Yes / No] |
| 4 | Prepare materials | Briefing copies, interface listings, seed scenarios, a shared workspace or repository branch for code, review agenda | Facilitator | [Yes / No] |

### 3.2 Reviewer selection criteria

- Choose people who will write code against the design within the next
  few months.
- Cover every kind of consumer: synchronous and asynchronous callers,
  test authors, operations staff who will troubleshoot it.
- Prefer reviewers who have not seen the design in detail; they find
  what the documentation leaves out.
- Keep the group small enough to work (around a dozen) and large enough
  to produce varied scenarios.
- Confirm each reviewer can attend the whole meeting. Partial attendance
  produces partial scenarios.

### 3.3 Materials checklist

| Item | Format | Ready |
|---|---|---|
| Design briefing slides or document | [Format] | [Yes / No] |
| Interface listings with signatures, types and error codes | [Format] | [Yes / No] |
| Example usage of the main operation | [Format] | [Yes / No] |
| Seed scenario cards | [Format] | [Yes / No] |
| Workspace for reviewer code (branch, sandbox, shared document) | [Location] | [Yes / No] |
| Issue capture sheet (section 9 layout) | [Location] | [Yes / No] |
| Room or call, timer, voting method | [Details] | [Yes / No] |

### 3.4 Rehearsal outcome

| Observation | Change made |
|---|---|
| *Example:* Briefing spent 40 minutes on internal engine design | Cut to 5 minutes; focus on the port |
| *Example:* No seed scenario exercised asynchronous callbacks | Added SEED-04 |
| *Example:* Error codes listed without meaning | Designer added one-line meaning per code |
| [Observation] | [Change] |

## 4. Design briefing summary

<!-- Guidance: Summarise what was presented so that the issue log can be read later without the slides. List each interface or element with an ID, because scenarios and issues refer to them. Keep the full design in its own document and link it. -->

### 4.1 Design overview

[One or two paragraphs: the design's responsibilities, its main
abstractions and how a user is expected to use it.]

```mermaid
flowchart LR
  Core["Payments core"] -->|calls| Port["PaymentProviderPort"]
  Port --> A1["Card adapter"]
  Port --> A2["Wallet adapter"]
  Port --> A3["Bank transfer adapter"]
  A1 --> P1["Provider API"]
  A2 --> P2["Provider API"]
  A3 --> P3["Provider API"]
  Kit["Contract test kit"] -.verifies.-> A1
  Kit -.verifies.-> A2
  Kit -.verifies.-> A3
```

### 4.2 Elements under review

| ID | Element | Kind | Description | Design document reference |
|---|---|---|---|---|
| IF-01 | *Example:* `authorise(request)` | Operation | Requests authorisation of an amount; returns an outcome or a typed error | [Section or file] |
| IF-02 | *Example:* `capture(authorisationId, amount)` | Operation | Captures all or part of an authorised amount | [Section or file] |
| IF-03 | *Example:* `refund(captureId, amount)` | Operation | Refunds all or part of a captured amount | [Section or file] |
| IF-04 | *Example:* `onProviderEvent(event)` | Callback | Delivers asynchronous provider notifications to the core | [Section or file] |
| IF-05 | *Example:* `ProviderError` | Type | Error taxonomy: retryable, declined, invalid, unknown | [Section or file] |
| IF-06 | *Example:* `AdapterConfig` | Type | Credentials reference, endpoints, timeouts, feature flags | [Section or file] |
| IF-07 | *Example:* Contract test kit | Tooling | Fixtures and assertions every adapter must pass | [Section or file] |
| [IF-nn] | [Element] | [Operation / Type / Event / Tooling] | [Description] | [Reference] |

### 4.3 Assumptions stated by the designer

| ID | Assumption |
|---|---|
| ASM-01 | *Example:* Every provider returns a stable reference per authorisation |
| ASM-02 | *Example:* Idempotency is the core's responsibility, not the adapter's |
| [ASM-nn] | [Assumption] |

## 5. Seed scenarios

<!-- Guidance: Seed scenarios show reviewers what a good scenario looks like and guarantee that the most important uses get tested even if brainstorming drifts. Write them as tasks a user would perform with the design, not as quality goals. Pitfall: seeds so detailed that reviewers simply copy them instead of proposing their own. -->

| ID | Scenario (task for the reviewer) | Elements exercised | Why it matters |
|---|---|---|---|
| SEED-01 | *Example:* Implement a card authorisation that the provider declines for insufficient funds | IF-01, IF-05 | Most common non-success path |
| SEED-02 | *Example:* Capture 60 percent of an authorised amount, then capture the rest two days later | IF-02 | Split shipments in retail |
| SEED-03 | *Example:* Handle a provider timeout during capture without double capture | IF-02, IF-05, ASM-02 | Money integrity |
| SEED-04 | *Example:* Process a delayed asynchronous settlement notification that arrives before the capture response | IF-04 | Out-of-order events |
| [SEED-nn] | [Task] | [IF IDs] | [Reason] |

## 6. Phase 2: Review meeting

<!-- Guidance: The review meeting covers steps 5 to 9 and normally takes most of a working day. Keep the agenda visible and protect the scenario application time: it is the part that finds issues. -->

### 6.1 Agenda

| Step | Activity | Time box | Lead |
|---|---|---|---|
| 5 | Present the ARID method: purpose, rules of the day, how issues are recorded | 15 minutes | Facilitator |
| 6 | Present the design: briefing from section 4, reviewers ask clarifying questions only | 1 to 2 hours | Lead designer |
| 7 | Brainstorm and prioritise scenarios: seeds shown, new scenarios proposed, votes cast | 45 minutes | Facilitator |
| 8 | Apply the scenarios: reviewers write code or pseudo-code using the design for each top scenario in priority order | 3 to 4 hours | Facilitator, reviewers |
| 9 | Summarise: read back the issue list, ask reviewers how the design and the review worked, thank participants | 30 minutes | Facilitator |

### 6.2 Ground rules

- Clarifying questions during the briefing are welcome; design debates
  wait for scenario application.
- The designer answers "how would I do this with the design?" but does
  not change the design during the meeting.
- When a reviewer cannot proceed, the scribe records an issue and the
  group moves on; nobody fixes the design in the room.
- Code does not have to compile. It must be specific enough that
  another engineer could check it against the interfaces.
- Every question the designer has to answer from memory is a candidate
  documentation issue.

## 7. Scenario brainstorm and prioritisation

<!-- Guidance: Reviewers propose scenarios that represent work they expect to do with the design. Merge duplicates, then vote: a common rule is a number of votes per reviewer equal to about 30 percent of the scenario count, rounded up. Work top-down in step 8 until time runs out. -->

Review scenarios use IDs `RVS-nn` (review scenario), distinct from the
`ARS-` requirement IDs of the Architecture Requirements Specification
(`architecture/architecture-requirements-specification`). Each of the [n]
reviewers received [v] votes for [m] scenarios.
*Example:* 12 reviewers, 7 scenarios, 3 votes each (30 percent of 7,
rounded up), 36 votes in total.

| ID | Scenario | Proposed by | Seed or new | Votes | Priority |
|---|---|---|---|---|---|
| RVS-01 | *Example:* SEED-03 capture timeout without double capture | Lead designer | Seed | 9 | 1 |
| RVS-02 | *Example:* Rotate provider credentials without restarting the adapter | SRE reviewer | New | 7 | 2 |
| RVS-03 | *Example:* SEED-04 out-of-order settlement notification | Lead designer | Seed | 6 | 3 |
| RVS-04 | *Example:* Add a provider that supports authorisation only, no partial capture | Wallets reviewer | New | 5 | 4 |
| RVS-05 | *Example:* Write a contract test proving a declined response maps to the declined error class | QA reviewer | New | 4 | 5 |
| RVS-06 | *Example:* SEED-02 split capture | Lead designer | Seed | 3 | 6 |
| RVS-07 | *Example:* Report adapter latency per operation to monitoring | SRE reviewer | New | 2 | 7 |
| [RVS-nn] | [Scenario] | [@name] | [Seed / New] | [n] | [n] |

*Example:* Reviewers voted two new scenarios (RVS-02, RVS-04) into the
top four. Neither was covered by the seeds, which shows the seeds were
biased toward the happy path of the transaction lifecycle.

## 8. Scenario application log

<!-- Guidance: For each scenario, record who drove the solution, the code or pseudo-code produced, the elements used, and where reviewers got stuck. Paste or link the code; it is evidence. Stop a scenario when it is solved or when blocking issues are recorded. -->

### 8.1 Summary

| Scenario | Driver | Elements used | Outcome | Issues raised | Time spent |
|---|---|---|---|---|---|
| RVS-01 | *Example:* [@reviewer] | IF-02, IF-05 | Blocked | ARI-001, ARI-002 | 50 minutes |
| RVS-02 | *Example:* [@reviewer] | IF-06 | Solved with workaround | ARI-003 | 30 minutes |
| RVS-03 | *Example:* [@reviewer] | IF-04 | Solved | ARI-004 | 40 minutes |
| RVS-04 | *Example:* [@reviewer] | IF-01, IF-02 | Blocked | ARI-005 | 35 minutes |
| RVS-05 | *Example:* [@reviewer] | IF-05, IF-07 | Solved | ARI-006 | 25 minutes |
| RVS-06 | *Example:* [@reviewer] | IF-02 | Not reached | None | 0 |
| [RVS-nn] | [@name] | [IF IDs] | [Solved / Solved with workaround / Blocked / Not reached] | [ARI IDs] | [Duration] |

### 8.2 Application detail

Record one block per scenario applied.

**RVS-01** *(Example)*: capture timeout without double capture

```text
// Reviewer pseudo-code written against the design during the review
result = port.capture(authId, amount)          // IF-02
on ProviderError.retryable:                     // IF-05
    // Question: may the core retry, or must the adapter check first?
    // Design is silent on whether capture is idempotent at the provider.
    retry? -> unknown, issue ARI-001
on timeout:
    // No error class distinguishes "timed out, outcome unknown"
    // from "failed, safe to retry". Issue ARI-002.
```

Observations: [what reviewers understood, where they hesitated, which
documentation they asked for].

**[RVS-nn]**: [scenario title]

```text
[Code or pseudo-code produced]
```

Observations: [Notes].

## 9. Issues and findings

<!-- Guidance: Log every issue in the reviewers' terms, with the scenario that exposed it. Classify it so the designer can plan the fix. Do not filter during the meeting; the designer triages afterwards. -->

### 9.1 Classification

| Category | Meaning |
|---|---|
| Missing | The design lacks an element, operation, type or rule that a scenario needs |
| Ambiguous | The design can be read in more than one way and reviewers disagreed |
| Incorrect | Using the design as specified gives the wrong result |
| Hard to use | The scenario can be solved, but only with effort or code that users are likely to get wrong |
| Documentation | The design works, but its description does not say how |
| Question | Open question for the designer, not yet classified |

| Severity | Meaning | Required before freeze |
|---|---|---|
| 1 | Blocks a top-priority scenario or risks data or money integrity | Fix and re-review the affected scenario |
| 2 | Scenario solvable only with a workaround or likely misuse | Fix or document the accepted workaround |
| 3 | Clarity or convenience improvement | Plan; may follow the freeze |

### 9.2 Issue log

| ID | Scenario | Element | Category | Severity | Description | Owner | Status |
|---|---|---|---|---|---|---|---|
| ARI-001 | *Example:* RVS-01 | IF-02 | Ambiguous | 1 | Design does not say whether capture may be retried; reviewers wrote three different retry policies | [@designer] | Open |
| ARI-002 | *Example:* RVS-01 | IF-05 | Missing | 1 | No error class for "outcome unknown"; adapters cannot signal it, so the core may double capture | [@designer] | Open |
| ARI-003 | *Example:* RVS-02 | IF-06 | Hard to use | 2 | Credentials read once at start-up; rotation needs restart or custom reload code | [@designer] | Open |
| ARI-004 | *Example:* RVS-03 | IF-04 | Documentation | 3 | Ordering guarantee of callbacks not stated; reviewers inferred "none" correctly | [@designer] | Open |
| ARI-005 | *Example:* RVS-04 | IF-02 | Missing | 2 | No way for an adapter to declare unsupported operations; reviewers threw generic errors | [@designer] | Open |
| ARI-006 | *Example:* RVS-05 | IF-07 | Hard to use | 3 | Test kit fixtures hard-code currency; non-EUR providers need copies | [@designer] | Open |
| [ARI-nnn] | [RVS-nn] | [IF-nn] | [Category] | [1 / 2 / 3] | [Description] | [@owner] | [Open / In progress / Closed / Rejected] |

### 9.3 Assumptions challenged

| Assumption | Challenge | Outcome |
|---|---|---|
| *Example:* ASM-02 idempotency is the core's job | RVS-01 showed the core cannot be idempotent without an "outcome unknown" signal from the adapter | Assumption revised; linked to ARI-002 |
| [ASM-nn] | [Challenge] | [Kept / Revised / Withdrawn] |

## 10. Summary and exit decision

<!-- Guidance: Step 9 ends the meeting with a read-back of issues and a short feedback round. After the meeting, the designer triages issues and the architecture lead records the decision against the exit criteria in section 1.4. -->

### 10.1 Results against objectives

| Objective | Result | Evidence |
|---|---|---|
| OBJ-01 | *Example:* Partly met: 3 of 5 applied scenarios solved, 2 blocked | Section 8.1 |
| OBJ-02 | *Example:* Not met: severity 1 gap in the error model | ARI-002 |
| OBJ-03 | *Example:* Met with friction | ARI-006 |
| [OBJ-nn] | [Met / Partly met / Not met] | [Reference] |

### 10.2 Reviewer feedback

| Question | Summary of answers |
|---|---|
| Was the design briefing enough to start writing code? | [Answers] |
| Which part of the design was hardest to use? | [Answers] |
| What would you change about the review itself? | [Answers] |

### 10.3 Decision

| Field | Value |
|---|---|
| Decision | [Proceed to freeze / Proceed after severity 1 fixes and delta review / Redesign] |
| Conditions | *Example:* ARI-001 and ARI-002 closed; RVS-01 re-applied by two reviewers |
| Decided by | [@architecture-lead] |
| Date | YYYY-MM-DD |
| Delta review date | YYYY-MM-DD |

## 11. Follow-up and traceability

<!-- Guidance: Every issue ends closed with a link to the change that closed it, or rejected with a reason the reviewers accepted. Turn design decisions made in response to issues into ADRs. Keep the trace from scenario to element to issue to change, so the next review can check it. -->

### 11.1 Action plan

| Action | Closes | Owner | Due | Status |
|---|---|---|---|---|
| *Example:* Add `ProviderError.outcomeUnknown` and define core reconciliation behaviour | ARI-002 | [@designer] | YYYY-MM-DD | [Status] |
| *Example:* State capture retry rule in the interface contract; add ADR | ARI-001 | [@designer] | YYYY-MM-DD | [Status] |
| *Example:* Add `capabilities()` operation for unsupported operations | ARI-005 | [@designer] | YYYY-MM-DD | [Status] |
| *Example:* Add credential reload hook to `AdapterConfig` | ARI-003 | [@designer] | YYYY-MM-DD | [Status] |
| [Action] | [ARI IDs] | [@owner] | YYYY-MM-DD | [Status] |

### 11.2 Traceability matrix

| Scenario | Elements | Issues | Design change | ADR | Verified by |
|---|---|---|---|---|---|
| RVS-01 | *Example:* IF-02, IF-05 | ARI-001, ARI-002 | Error model v2 | ADR-031 | Delta review, contract test CT-14 |
| RVS-02 | *Example:* IF-06 | ARI-003 | Reload hook | ADR-032 | Contract test CT-15 |
| RVS-04 | *Example:* IF-01, IF-02 | ARI-005 | Capability declaration | ADR-033 | Contract test CT-16 |
| [RVS-nn] | [IF IDs] | [ARI IDs] | [Change] | [ADR ID] | [Evidence] |

Record new or changed ADRs in the architecture decision log
(`architecture/architecture-decision-log`). Where a scenario expresses a
quality that should stay true after release, such as "adapters never
call providers directly from the core", add a fitness function
(`architecture/fitness-functions`).

## 12. Review effectiveness

<!-- Guidance: Measure the review so the next one is better. Track how many issues it found, how serious they were and how many issues surfaced later that the review should have caught. -->

| Metric | Value | Comment |
|---|---|---|
| Reviewer hours spent | *Example:* 12 reviewers x 7 hours = 84 | |
| Scenarios proposed / applied | *Example:* 7 / 5 | RVS-06 and RVS-07 not reached |
| Issues by severity (1 / 2 / 3) | *Example:* 2 / 2 / 2 | |
| Issues per applied scenario | *Example:* 6 / 5 = 1.2 | |
| Issues found later in implementation that a scenario would have exposed | [n, after 3 months] | Escaped issues |
| Lead time from review to interface freeze | [Days] | |

Lessons for the next review:

- [Lesson, for example "seed at least one operations scenario".]
- [Lesson.]

## 13. Glossary and references

<!-- Guidance: Define the review terms as used here and list the sources consulted with the date you checked them. -->

### 13.1 Glossary

| Term | Meaning in this document |
|---|---|
| Intermediate design | A design detailed enough to use (interfaces, types, rules) but not yet fully specified or implemented |
| Active review | A review in which reviewers must use the design to complete tasks, rather than comment on it |
| Rehearsal phase | Preparation by facilitator and lead designer: reviewers, briefing, seed scenarios, materials |
| Review phase | Meeting in which the method and design are presented and scenarios are brainstormed, prioritised and applied |
| Seed scenario | A scenario prepared in advance as an example and to guarantee coverage |
| Scenario application | Writing code or pseudo-code that solves a scenario using only the design as presented |
| Delta review | A short follow-up review limited to scenarios affected by design changes |

### 13.2 References

| Reference | Version or date checked | Use |
|---|---|---|
| Clements, P. C. *Active Reviews for Intermediate Designs*. Technical note CMU/SEI-2000-TN-009, Software Engineering Institute, sei.cmu.edu | August 2000, checked YYYY-MM-DD | Phases, steps and roles of the method |
| Clements, P., Kazman, R., Klein, M. *Evaluating Software Architectures: Methods and Case Studies*, Addison-Wesley, 2002 | Background reading (inspiration only) | Context among SEI evaluation methods |
| Parnas, D. L., Weiss, D. M. *Active Design Reviews: Principles and Practices*, Proceedings of ICSE 8, 1985 | Background reading | Origin of the active review idea |
| Architecture evaluation (ATAM) template (`architecture/atam-evaluation`) | This collection | Scenario-based evaluation for whole architectures |
| [Design document reviewed] | [Version] | Subject of the review |

## Standard and licence note

Based on Active Reviews for Intermediate Designs (ARID) as described
by Paul C. Clements in Software Engineering Institute technical note
CMU/SEI-2000-TN-009 (August 2000): the rehearsal and review phases,
their nine steps (identify reviewers, prepare the design briefing,
prepare seed scenarios, prepare materials, present the method, present
the design, brainstorm and prioritise scenarios, apply the scenarios,
summarise) and the roles of facilitator, scribe, lead designer and
reviewers. This template is original text written for this collection
and reproduces no text from SEI publications or from books on the
method; the worked example is invented and marked *Example*. Check the
SEI digital library for the current version of the technical note
before use. Carnegie Mellon, SEI and ATAM may be trademarks or service
marks of Carnegie Mellon University; this template is not affiliated
with or endorsed by the SEI. Template licence: MIT.