# Architecture Review > Review the per-stack LLDs and the cross-repo contract — analyze architecture gaps, security, scaling, reliability, data model, and contract soundness. Read-only; writes a review artifact. Front door for /architecture-review. - Skill: `keyvaluesoftwaresystems/architecture-review` (Agent Skill) - Install (CLI): `npx skillmds@latest add keyvaluesoftwaresystems/architecture-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/keyvaluesoftwaresystems/architecture-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: keyvaluesoftwaresystems (https://skillmd.com/u/keyvaluesoftwaresystems) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/keyvaluesoftwaresystems/architecture-review --- # architecture-review Review the drafted design so architecture problems are caught while they are cheap to fix. Read-only — never edit code. ## Inputs Your instructions name what to read — the per-stack LLDs and the cross-repo contract — cross-checked against the HLD, acceptance criteria, and the architecture rules (`AGENTS.md`, `CLAUDE.md`, ADRs). ## Steps 1. **Read** the HLD, every selected repository LLD, the contract, and acceptance criteria; note the stated NFRs. Use `lld-repos.json` as the authoritative selection. 2. **Trace each acceptance criterion** to a design element — flag anything unmet (a gap). 3. **Deep, evidence-backed pass** over every dimension in the checklist below. For a more independent read you MAY spawn a fresh read-only sub-agent (via the Task tool) that follows this same skill — do this where your harness supports it (e.g. Claude Code or Codex). Otherwise perform the pass **inline**. Either way: **read-only — never edit code.** You are the read-only backstop; nothing is skipped. 4. **Consolidate** findings; sort by severity; decide `blocking`. 5. **Classify the revision route.** For a blocking verdict, select the earliest authoritative layer that would normally need revision: `product`, `hld`, `lld`, `contract`, `verification`, or `cross-cutting`. Name every repository whose LLD must reflect the correction, even when the normal source layer is PRD/HLD/contract; the human is always offered an LLD-only correction path that deliberately preserves the approved PRD/HLD. 6. **Write** the report and return the verdict. ## What the review must cover (checklist — independent of the external skill) - **Completeness / gaps** — does the design satisfy every requirement & acceptance criterion? Missing flows, unhandled cases, undefined behavior, TBDs. - **Boundaries & coupling** — correct service/module boundaries; no coupling that bypasses the contract; clear ownership. - **Data model & migrations** — schema soundness; expand→migrate→contract; reversibility; indexing; no online long locks; safe backfill. - **Contract soundness** — versioning/backward-compat; consistent error shape; auth per operation; pagination/limits; **idempotency**; concurrency control; breaking changes flagged. - **Security posture** — authn/authz model, tenant isolation, PII/data protection, threat surface of new endpoints/integrations, secrets handling. - **Scalability & performance** — expected load, hotspots, N+1/fan-out, caching, statelessness, rate limits, payload caps, connection pools. - **Reliability** — failure modes, timeouts, retries/backoff, backpressure, partial-failure and rollback behavior, degradation. - **Observability & cost** — logs/metrics/traces planned for new paths; cost blast radius. ## Edge cases / smells to watch for - "Happy-path" designs that omit failure and permission paths. - Breaking contract changes not labeled as such; missing deprecation/migration plan. - Migrations without rollback or without a backfill plan for existing data. - New synchronous call in a hot path (latency/coupling); unbounded queries or list endpoints. - Multi-tenant leakage; PII in logs; secrets in config committed to the repo. - Cross-service transaction assumed where only eventual consistency is available. ## External skill (provision — review method) If the `requesting-code-review` skill (from the Superpowers pack) is installed, apply its review discipline first; it must not narrow the checklist above. If it is not installed, review inline per the checklist. ## Findings format (what the review returns — evidence mandatory) ``` summary: findings: - severity: blocker | major | minor | suggestion area: gaps | boundaries | data-model | contract | security | scaling | reliability | observability location: evidence: recommendation: safe_for_ai_fix: blocking: ``` ## Decide & output Sort findings blocker → major → minor → suggestion; `blocking = true` if any blocker/major remains. A contract/auth/data-model change is never `safe_for_ai_fix`. Write the report (summary + findings table) to the artifact path your instructions specify (the orchestrator passes it). Running standalone? write to a sensible path you choose and tell the user where. For the routing fields: - `revision_scope` is the earliest source-of-truth layer whose revision would resolve all blocking findings. Prefer the order product → hld → lld → contract → verification; use `cross-cutting` only when no single layer owns the decision. - `affected_repos_csv` is a comma-separated subset of the exact repository names in `lld-repos.json`. It is mandatory for a blocking verdict because the human may approve the finding as an effective-design correction and update only those LLDs. - `correction_text` is one or two precise sentences stating the resulting design rule. It must be complete enough to become a human-approved correction receipt; do not put analysis or options in it. - For a non-blocking verdict return `revision_scope: "none"`, `affected_repos_csv: ""`, and `correction_text: ""`. ## Output contract Return `review_path`, `blocking`, `summary`, `revision_scope`, `affected_repos_csv`, and `correction_text`.