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.
Document control
| 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
1. Purpose, scope and method choice
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
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
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
4.1 Design overview
[One or two paragraphs: the design's responsibilities, its main
abstractions and how a user is expected to use it.]
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
| 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
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
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
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
// 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]
[Code or pseudo-code produced]
9. Issues and findings
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
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
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
| 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
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.