| name | architecture-review |
| description | Validates the architecture against all PRDs. Builds a traceability matrix from PRD requirements to ADRs, identifies coverage gaps, detects cross-ADR conflicts, and produces a PASS/CONCERNS/FAIL verdict. Run after Required ADRs are written; rerun whenever PRDs change. Read-only — never edits files. |
| argument-hint | [no arguments] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Task |
| model | opus |
Architecture Review
Holistic check that every PRD requirement is covered by an ADR, that ADRs do not contradict each other, that the framework knowledge-cutoff risk is honored across all decisions, and that no architectural stance is silently broken.
Read-only. Outputs a structured verdict and traceability matrix.
Purpose / When to Run
Run when:
- All P0 ADRs from the architecture's Required list are written
- A batch of PRDs changed (after
/propagate-design-change)
- Before kicking off the first sprint
- Before a major release
Run in a fresh session — independent of any authoring context.
Inputs
docs/architecture/architecture.md- All
docs/architecture/ADR-*.md
- All
design/prd/*.md
design/systems-index.mddocs/framework-reference/<framework>/docs/architecture/architecture-registry.yaml if present
Outputs
- A printed report including a traceability matrix and verdict
- No file writes
Phase 1: Pre-checks
- Confirm
docs/architecture/architecture.md exists. Fail otherwise.
- Confirm at least 1 ADR with
Status: Accepted exists. If none, run anyway but in degraded mode.
If running degraded, label the report header: "Degraded — no Accepted ADRs yet. This pass identifies coverage gaps only."
Phase 2: Build the Traceability Index
For each PRD:
- Extract all TR-IDs from Section 3 Detailed Requirements (
TR-<system>-NNN)
- Identify which ADRs reference each TR-ID by grepping
docs/architecture/ADR-*.md for the TR-ID
Build a matrix:
| PRD | TR-ID | Requirement summary | Covered by | ADR Status |
|-----|-------|---------------------|------------|------------|
| auth.md | TR-auth-001 | OAuth login | ADR-0003 | Accepted |
| auth.md | TR-auth-002 | Token refresh | ADR-0003 | Accepted |
| auth.md | TR-auth-003 | Biometric unlock | — | UNCOVERED |
| paywall.md | TR-paywall-001 | Receipt validation | ADR-0009 | Proposed |
Categorize each row:
- COVERED — Accepted — TR-ID has at least one ADR with Status: Accepted addressing it
- COVERED — Proposed — TR-ID has an ADR but the ADR is still Proposed
- UNCOVERED — TR-ID has no ADR reference
- OVER-COVERED — TR-ID has multiple Accepted ADRs that may conflict
Phase 3: Cross-ADR Conflict Detection
For each pair of Accepted ADRs in the same domain, scan for:
- State ownership conflicts — ADR-A claims
current_user ownership; ADR-B also writes to it
- Interface contradictions — ADR-A defines event
userLoggedIn; ADR-B uses user_logged_in for the same thing
- Performance budget contradictions — ADR-A claims 200ms cold start; ADR-B implies an SDK that adds 300ms
- Deprecated-API references — any ADR using an API listed in
docs/framework-reference/<framework>/breaking-changes.md as deprecated
Each conflict becomes a finding.
Phase 4: Architecture Doc Cross-Check
Verify every cross-cutting concern in architecture.md Sections 4-19 has either:
- An Accepted ADR, OR
- A pointer to a planned/Proposed ADR, OR
- An explicit deferral with reason ("not in v1")
Flag bare descriptions without ADRs in the architecture doc:
- "We use Sentry" with no ADR → MEDIUM finding (decision recorded only in arch doc, not as a tracked ADR)
Phase 5: Framework Knowledge-Cutoff Audit
Read docs/framework-reference/<framework>/VERSION.md for the risk level.
If MEDIUM/HIGH:
- For every ADR, check the
Framework Compatibility table
- Flag any ADR with empty or "Unknown" Verification Required for a HIGH-risk domain → HIGH finding
- Flag any ADR using post-cutoff APIs that are not listed in Framework Compatibility → HIGH finding
Phase 6: Mobile Cross-Cutting Checks
These checks are mobile-specific and often skipped. Each absence is a finding.
- Account deletion — App Store guideline 5.1.1(v) and Play policy require an in-app deletion path. Is there a PRD or ADR addressing this?
- App Tracking Transparency (iOS) — if any tracking is described, is there an ADR for the ATT prompt timing and copy?
- Play Data Safety / iOS Privacy nutrition labels — is there a PRD section or ADR governing what data is collected and how it is declared?
- Push token rotation — does the push ADR address rotation?
- Receipt validation — for any IAP, is server-side validation specified?
- Background task limits — does the background ADR respect iOS BGTaskScheduler limits and Android Doze constraints?
- Deep link auth gating — does the navigation ADR specify what happens to deep links when the user is logged out?
- Min OS — are min OS versions consistent across PRDs and ADRs?
- App size impact — is the architecture aware of bundle size budget?
Each missing item: HIGH if regulatory / store-policy; MEDIUM otherwise.
Phase 7: Optional Specialist Synthesis
Spawn Task to:
mobile-architect — read the matrix and flag missed coverage or strategic concerns- Framework specialist — validate post-cutoff API claims and breaking-changes entries
The reviewer integrates the findings.
Phase 8: Verdict
Tally:
- CRITICAL — UNCOVERED v1 TR-ID, store-policy gap (account deletion missing), regulatory gap (data safety), framework-deprecated API in Accepted ADR
- HIGH — interface contradictions between Accepted ADRs, P0 ADR still Proposed, missing knowledge-cutoff verification
- MEDIUM — over-coverage requiring resolution, missing mobile cross-cutting addresses (push token rotation, etc.)
- LOW — cosmetic (naming inconsistency in ADR titles)
Verdict ladder:
- 0 CRITICAL, 0 HIGH → PASS
- 0 CRITICAL, ≤ 5 HIGH → CONCERNS
- 1+ CRITICAL or 6+ HIGH → FAIL
Phase 9: Output
# Architecture Review
**Verdict: <PASS / CONCERNS / FAIL>**
## Coverage Summary
- Total PRD requirements: <N>
- Covered (Accepted): <N>
- Covered (Proposed): <N>
- Uncovered: <N>
- Over-covered: <N>
## Traceability Matrix
[abbreviated table — uncovered + Proposed-only rows highlighted]
## CRITICAL findings
1. <finding>
Affecting: <PRD or ADR list>
Fix: <specific action>
## HIGH findings
1. <finding>
Fix: <action>
## MEDIUM findings
- <list>
## LOW findings
- <list>
## Strengths
- <what is well-covered>
## Recommended next steps
- For each CRITICAL: <action — e.g., write ADR for biometric unlock, address account deletion in a new PRD>
- After fixes: re-run `/architecture-review`
- For PASS: proceed to `/create-control-manifest` and then `/create-epics`
Phase 10: Exit Notes
If PASS: tell the user the architecture is locked enough to proceed to epics. Suggest /create-control-manifest next.
If CONCERNS: list the 3 highest-leverage fixes the user should run, then re-run this skill.
If FAIL: refuse to proceed to epics; the team must close gaps first.
Quality Gates
- Every uncovered v1 TR-ID is listed by ID and PRD
- Every conflict names both ADRs and the specific contradiction
- The verdict matches the tally rules
- Read-only — never modifies any file
Examples
PASS run: 47 TR-IDs, 47 covered (44 Accepted, 3 Proposed in low-risk domains), 0 conflicts, 0 critical mobile gaps. Verdict: PASS. Recommend /create-control-manifest.
FAIL run: 47 TR-IDs, 41 covered, 6 uncovered (including biometric unlock and account deletion). 2 ADRs use deprecated APIs per breaking-changes.md. Verdict: FAIL. Recommend writing 4 missing ADRs and revising 2 existing ones.
