Review architecture specifications for completeness, appropriate abstraction level, and separation of concerns. Use when reviewing top-level, implementation-agnostic architecture documents that define system boundaries, responsibilities, flows, and constraints without prescribing implementation details.
Review architecture specifications at the appropriate level of abstraction, evaluating whether they successfully define system structure without drifting into implementation details.
Architecture specifications exist on a spectrum:
Top-level Architecture Specs (this skill's focus):
Executable Specifications:
Implementation Documentation:
Before reviewing, read the document's stated goals:
Never review against your expectations - review against the document's stated purpose.
For architecture specifications, assess whether these are clear:
Boundaries: Is each component's responsibility distinct and well-defined?
Flows: Are the key scenarios described?
Constraints: Are architectural guarantees stated?
Extension Points: Can the design evolve?
Deferred Decisions: What's appropriately left for later?
Architecture specs should NOT specify:
Architecture specs SHOULD specify:
Critical pause: Before sharing your review, evaluate your own findings.
Ask yourself:
Am I asking about HOW when the doc only promises WHO and WHAT?
Would my questions add clarity or just detail noise?
Am I respecting explicit scope boundaries?
Could I explain why the architecture needs to specify this?
Change your perspective:
Structure your review:
What Works:
Questions (only architectural concerns):
Not: "How does X work internally?" But: "What guarantee does X provide to its clients?"
Avoid:
Over-Specification Demands:
Scope Creep:
Pattern Matching:
A good architecture specification:
A good review:
For Reviewers:
For Authors:
Architecture specs are about structure and boundaries, not implementation and mechanisms.
When in doubt, ask: "Does this question change how components interact, or just how a component works internally?"