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.md
• docs/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:

1. Extract all TR-IDs from Section 3 Detailed Requirements (TR-<system>-NNN)
2. 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.