Adr review

ADR Review

A single Architecture Decision Record (ADR) review. Used both for the initial set produced by apex:architecture-design and for every amendment / supersession after the architecture is frozen.

When to invoke

• Authoring an ADR from one of apex:architecture-design's 7 passes
• Authoring an amendment ADR when a feature crosses the existing architecture boundary
• Reviewing someone else's ADR before approving
• Auditing the ADR set for completeness

Pairs with apex:architecture-design (the producer) and apex:design-feature Pass 4 (the trigger for amendments — when a feature doesn't fit the existing architecture, you write an amendment ADR before designing the feature against the new shape).

ADR canonical structure

The blank form is templates/adr.md — an author starts from that file; the skeleton below is the same structure, restated here as what this review audits against.

# ADR-NNNN: <Decision title>

**Status:** Proposed | Accepted | Superseded by ADR-MMMM | Deprecated
**Date:** YYYY-MM-DD
**Deciders:** <names / roles>
**Tags:** persistence | auth | tenancy | observability | ...

## Context

<What's the problem? What constraints apply? What's been tried? What's
already in place? Cite specific files / data / PRs if relevant.>

## Decision

<The decision, stated in one paragraph. Should be readable in isolation.>

## Alternatives considered

1. <Alt 1> — pro / con / why not
2. <Alt 2> — pro / con / why not
3. <Alt 3> — pro / con / why not

## Consequences

### Positive
- <What this decision enables>

### Negative
- <What this decision makes harder or impossible>

### Security implications
- <Effect on attack surface, trust boundaries, data classification — REQUIRED>

### Cost / operational implications
- <Cloud cost, ops burden, vendor lock-in>

### Reversibility
- <How hard is it to undo this? Estimate in days/weeks/months.>

## Compliance / references

- Supersedes: ADR-XXXX (if any)
- Related: ADR-YYYY, ADR-ZZZZ
- External: <RFCs, docs, spec links>

The 5-element audit

Element 1 — Context: is the problem actually stated?

Check: The Context section says what's the problem and why now, not what's the decision. Distinguishes constraints (immutable) from preferences (mutable).

Pass condition: A reader new to the project can understand the problem from Context alone.

Adversarial counter-pass: Find a constraint listed as Context that's actually a preference (e.g. "must be JSON-over-HTTP" — is that a hard requirement or a comfort zone?). Find a preference listed as Context that's actually a constraint. Get the categorization right; it changes the alternatives space.

Element 2 — Decision: stated unambiguously, in one paragraph

Check: A single paragraph someone could quote verbatim. No "we will use Postgres, or possibly MySQL." No "we'll figure out tenancy in phase 2."

Pass condition: Decision is grep-able and quotable in code review.

Adversarial counter-pass: Try to misread the decision. If "we use JWT for auth" is ambiguous about where tokens live (cookie / localStorage / header), the decision is under-specified. Fix it.

Element 3 — Alternatives: ≥2 real alternatives, not strawmen

Check: At least 2 alternatives that someone reasonable might have picked. Each with one-line pro, one-line con, one-line "why not."

Pass condition: A skeptical reviewer can't immediately think of a 3rd alternative you didn't consider.

Adversarial counter-pass: Find a strawman alternative (one obviously dismissed for shallow reasons — "we considered raw socket I/O" when the project is a CRUD web app). Strawmen weaken the ADR; replace with the real contender you didn't list.

Element 4 — Consequences: enumerated, including the unhappy ones

Check: Both Positive AND Negative. Plus Security implications (mandatory), Cost (mandatory for cloud / vendor decisions), Reversibility (mandatory — how hard is undo?).

Pass condition: The Negative + Security sections each have ≥1 substantive bullet. "No downsides" = the ADR is lying or hasn't thought hard enough.

Adversarial counter-pass: Name a consequence the ADR doesn't list. Especially: a downstream feature this decision makes harder, a class of bug this decision enables, a vendor lock-in this introduces, a security property this weakens.

Element 5 — Status field: present and current

Check: Status is one of Proposed / Accepted / Superseded by ADR-MMMM / Deprecated. Has a date. If amending an existing ADR, the old one is marked Superseded with a forward link.

Pass condition: Status reflects the current state. No stale "Proposed" ADRs that have been live for months.

Adversarial counter-pass: Find an ADR in this PR's diff whose Status hasn't been updated since the decision was finalized. (Common: ADR shipped as "Proposed", implementation lands, no one bumps to "Accepted".)

Adversarial pair pattern

For high-stakes ADRs (auth model, tenancy, persistence, deploy shape — anything from apex:architecture-design Passes 2 / 3 / 4), dispatch the review as two parallel agents via apex:adversarial-pair (apex's canonical dispatch mechanic):

• Cooperative agent — runs the 5 elements in steelman mode. Confirms the decision is defensible.
• Adversarial agent — runs the same in attack mode. Each counter-pass becomes the lens. Finds missing alternatives, hidden constraints, under-stated consequences, residual security risks.

Both agents work with the same ADR text. Reconcile their findings.

Pass/fail summary

The ADR passes if all 5 elements meet their conditions AND adversarial findings are addressed, and this is review round 1 or 2 for this ADR (see below). Fail any → revise before committing the ADR. ADRs are durable institutional memory — bad ADRs misinform every future amendment.

Bound the loop — an ADR bounces at most TWICE

This skill sends ADRs back to their author (apex:architecture-design's passes, or whoever wrote the amendment), so it has the same unbounded shape as apex:design-review and apex:prd-review: revise → review → revise. An ADR is prose; Element 3 in particular ("a skeptical reviewer can't think of a 3rd alternative") is unfalsifiable by construction — round N+1 can always name one more alternative. The second review is the cap. Note the round number in the review output.

• Round 2's surviving findings do not trigger a round 3. Accept the ADR with them recorded — in the ADR's own Consequences → Negative section (a named residual risk is exactly what that section is for) or as a linked open issue. An ADR that records a known-open trade-off is more honest than one polished until the objection stops being written down.
• The escalation exception is a stop, not a round 3. These ADRs carry decisions code cannot cheaply falsify, so a substantive unresolved finding against the auth / tenancy / data-classification / persistence ADRs (architecture-design Passes 2 / 3 / 7) at round 2 — a trust-boundary break, a key-custody violation, a tenancy model that makes cross-tenant leaks one bug away — means escalate to the architecture owner and hold the freeze. Don't author another round, and don't accept it as a residual risk either.
• Element 5 (Status) never counts as a round. Bumping Proposed → Accepted or adding a Superseded by link is bookkeeping, not a review finding.

As with apex:copilot-review-loop's 5-round cap, this is about loop termination, not about lowering the quality bar. See apex:apex-flow §12 for the cross-skill rule.

Hand-off

Once the ADR passes:

• It's committed to docs/adr/ (or your project's chosen path)
• The ADR set's README.md index is updated
• Downstream gates (apex:design-feature, apex:prd-review, apex:threat-model, apex:security-review) reference the ADR's decision as a constraint they must respect
• An amendment ADR also updates the superseded one's Status field