review-arch

Review system boundaries and architecture tradeoffs; not line-level code review.

SKILL.md

GitHub

Architecture Review

Assess the architecture of a named system, subsystem, or design decision. Report structural risks grounded in the system's actual goals and constraints. Do not edit code or create a report file unless requested.

Route precisely

  • Use this skill when the question concerns system structure, ownership, dependency direction, integration topology, or quality tradeoffs.
  • Use review-spec when a proposed specification or revision is the primary artifact and the question is whether its design is sound.
  • Use verify-impl for requirement-by-requirement conformance of existing code to a spec.
  • Use code-review for correctness of changed lines and ordinary pull-request readiness. A changed architecture may warrant both reviews when explicitly requested, with separate scopes.
  • Use plan-review for an ordered implementation plan.

Build a bounded model

  1. Name the system boundary, users, purpose, scale, deployment environment, and known quality priorities. Source these from the request and directly relevant documents; mark unknowns instead of assuming enterprise-scale needs.
  2. Read applicable repository instructions, architecture documentation and decisions, and representative implementation paths. Follow data and control across the boundaries under review.
  3. List the major decisions actually present: component responsibilities, data ownership, communication, persistence, failure isolation, deployment, and operational ownership. Record explicit deferrals.
  4. Form at least one realistic scenario that stresses each material quality goal, such as a partial dependency failure, simultaneous updates, or increased load. State the scenario's assumptions.

Evaluate decisions

For each consequential decision, assess:

  • whether it serves the stated business and user goals;
  • which quality attribute it improves and what it costs elsewhere;
  • whether component boundaries and dependency direction preserve clear ownership;
  • whether data consistency, failure recovery, security boundaries, and observability are credible for the scenario;
  • whether a simpler architecture meets the same constraints;
  • whether an apparent anti-pattern has a concrete failure mode here rather than merely matching a label.

Ground each finding in a file, diagram, decision record, requirement, or observed runtime behavior. Trace the consequence through a plausible scenario and check for mitigations. Do not infer operational needs solely from a methodology or demand every quality attribute be maximized. If a key priority is unknown, present the conditional alternatives and the decision needed.

Go lifecycle, when applicable

For Go systems, trace ownership of background goroutines, shared state, connections, and shutdown across package boundaries. Check whether fan-out, queued work, retries, and partial failures remain bounded under the stated load. Judge flat packages, internal/, architectural layers, and DI containers by their observed dependency/lifecycle cost; none is a defect by name. Reuse the same scenario-based evidence standard instead of requiring a particular Go architecture.

Selected Go lifecycle considerations adapt Samber's design-pattern guidance, under the bundled LICENSE.samber-cc-skills-golang.

Report

Return the reviewed boundary and evidence, then a verdict of SOUND, CONCERNS, or BLOCKED. BLOCKED means essential context is unavailable. Group evidence-backed findings as critical risks, significant concerns, and observations; give each the triggering scenario, impact, and smallest useful decision or experiment. Include sound decisions worth preserving, open questions, and verification limits. A structural concern does not automatically block a small code change; state what decision it affects.