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: <one paragraph: is the design sound to build? what are the top risks?>
findings:
  - severity: blocker | major | minor | suggestion
    area: gaps | boundaries | data-model | contract | security | scaling | reliability | observability
    location: <lld/*.md section / openapi path / file:line>
    evidence: <quoted design/contract text or its absence>
    recommendation: <the design change>
    safe_for_ai_fix: <true|false>
blocking: <true if any blocker/major remains>

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.