review-design-high-level

name	review-design-high-level
description	Review a high-level design document for gaps in architecture, security posture, data model soundness, technology choices, and deployment readiness. Use after producing a high-level design and before starting low-level design.
argument-hint	[prefix or path to high-level design file, or leave blank to auto-discover]

Review a high-level design document for architectural gaps, unsound decisions, and unclear specifications. This review is tailored to the concerns that belong at the architecture level — not implementation details.

Input

The user may provide: $ARGUMENTS

Expected Folder Structure

project/
├── design/
│   ├── {prefix}-requirements.md              # Read for cross-reference
│   └── {prefix}-high-level-design.md         # Input: document to review
└── reviews/
    └── {prefix}-high-level-design-review.md  # Output

Process

Phase 1: Locate Documents

1. High-level design: Determine the file to review:

   • If $ARGUMENTS is a file path (contains / or ends in .md), use it directly and infer the prefix from the filename (e.g., design/foo-high-level-design.md → prefix is foo)
   • If $ARGUMENTS is a prefix word (no /, does not end in .md), look for design/{prefix}-high-level-design.md
   • If no arguments provided, scan design/ for files matching *-high-level-design.md (also check for unprefixed high-level-design.md)
     • One match: Use it and infer the prefix from the filename
     • Multiple matches: Use AskUserQuestion listing the discovered files and ask the user which design to review
     • No matches: Use AskUserQuestion to ask the user where to find the high-level design
   • If no prefix can be determined, ask the user

2. Requirements document: Once the prefix is established, look for design/{prefix}-requirements.md — needed for cross-referencing

3. If either is missing: Use AskUserQuestion to ask the user where to find them. The requirements doc is strongly recommended but not blocking — proceed without it if the user chooses.

Phase 2: Read and Understand

Read both documents thoroughly. Before reviewing, understand:

• What system is being designed
• What requirements it must satisfy
• What architectural decisions have been made and their stated rationale

Phase 3: Review Analysis

Analyze the high-level design across these areas. For each area, assess what's present, what's missing, and what's unclear. Not every area will be relevant to every design — focus on what matters for this specific system.

3.1 Architecture & Component Design

• Are component boundaries clearly defined? Is each component's responsibility unambiguous?
• Are communication patterns between components specified (sync vs async, protocols)?
• Are there single points of failure? Is this acknowledged if intentional?
• Does the component decomposition match the problem? Over-decomposed? Under-decomposed?
• Are ownership boundaries clear — which component owns which data and behavior?
• For distributed designs: is the consistency model addressed (strong, eventual, causal)?
• Are there circular dependencies between components?

3.2 Data Model Soundness

• Do the entities and relationships match what the requirements describe?
• Are cardinalities correct and complete? (Every relationship should state one-to-one, one-to-many, or many-to-many.)
• Are there entities mentioned in the requirements but missing from the data model?
• Is the data lifecycle addressed — how is data created, updated, archived, deleted?
• Are there implicit entities that should be explicit (e.g., audit logs, events, configuration)?
• For stateful systems: is the source of truth identified for each piece of data?

3.3 Data Flow Integrity

• Are the major data flows documented (happy path and key failure paths)?
• For each flow: is it clear which component initiates, which processes, which persists?
• Are there flows mentioned in requirements that aren't covered?
• Are failure/error paths addressed or only the happy path?
• For async flows: is the delivery guarantee specified (at-least-once, exactly-once, best-effort)?
• Are there data flows that cross trust boundaries without being called out?

3.4 Security Architecture

• Is the authentication model fully specified — who authenticates, how, what credentials?
• Is the authorization model defined — what grants access to what?
• Are trust boundaries drawn? Is it clear what's internal vs external?
• Is encryption specified for data in transit and at rest?
• Are secrets management practices defined (where secrets live, how they're rotated)?
• For multi-tenant systems: is tenant isolation addressed?
• Are compliance requirements from the requirements doc reflected in the security design?
• Is input validation strategy mentioned for external-facing interfaces?
• Are there obvious attack surfaces left unaddressed?

3.5 Technology Choices

• Is every technology choice accompanied by rationale?
• Were alternatives considered and documented?
• Are there choices that conflict with stated requirements or constraints?
• Are there vendor lock-in risks that aren't acknowledged?
• Does the team have experience with the chosen technologies? (Flag if unclear.)
• Are there unnecessary technologies — things included without a clear requirement driving them?
• Do the choices compose well? Are there known integration friction points?

3.6 Deployment & Operational Readiness

• Is the deployment model realistic for the team and infrastructure described?
• Is local development addressed — can developers run the system locally?
• Is observability covered at an appropriate level for a high-level design (logging strategy, metrics, tracing)?
• Are failure modes at the infrastructure level considered (node failure, network partition, storage failure)?
• Is the scaling model clear — horizontal, vertical, or "we don't need to scale yet"?
• For cloud deployments: are region, availability zone, and redundancy decisions stated?

3.7 Requirements Coverage

• Does the design address every functional requirement from the requirements document?
• Are there requirements that appear to be forgotten or only partially addressed?
• Does the architecture naturally support the non-functional requirements (performance, reliability, etc.)?
• Are deferred items clearly marked and consistent with the requirements doc's scope?

3.8 Specification Clarity

Flag anything that:

• Uses ambiguous language ("may", "could", "might consider", "possibly", "TBD")
• References future work without clear boundaries
• Mentions a capability without specifying how it's achieved architecturally
• Has multiple reasonable interpretations
• Contradicts another section of the document
• Contradicts the requirements document

Phase 4: Generate Review

Create the review document at reviews/{prefix}-high-level-design-review.md using the template in template.md.

Conventions:

• Finding IDs with category prefixes: ARCH-*, DATA-*, FLOW-*, SEC-*, TECH-*, OPS-*, COV-*, UNCLEAR-*
• Priority ratings: Must Address (blocking — do not proceed to low-level design), Should Address (high priority), Consider (medium)
• RFC 2119 language (SHALL, SHOULD, MAY) for recommendations
• Mermaid diagrams where they clarify a gap or proposed improvement
• Cross-reference requirement IDs (FR-x.x.x) when flagging coverage gaps

Mermaid Diagram Rules (required for renderer compatibility — GitLab, GitHub, VS Code use older Mermaid.js):

• Always quote flowchart node labels: A["Start here"] not A[Start here]
• Always quote decision nodes: B{"Is it ready?"} not B{Is it ready?}
• Always quote subgraph titles: subgraph sg["My Group"] not subgraph sg[My Group]
• Prefer A -- "label" --> B link syntax over A -->|"label"| B
• Keep labels short — move detail into surrounding prose
• NO <br/> in any label or node text
• NO par / and blocks in sequence diagrams — use Note over A,B: description instead
• NO <--> bidirectional arrows — use two separate directed arrows
• NO }o--|| at start of erDiagram lines — reverse to ||--o{
• NO special characters in state/flowchart labels: () . / → __ — use plain words

Phase 5: Present Summary

After creating the review, summarize for the user:

• Overall assessment of the design's readiness for low-level design
• Verdict for each review area
• Top 5 most critical items
• Count of findings by priority
• Whether the design is ready to proceed to low-level design, needs targeted fixes, or needs significant rework

Output

Create reviews/{prefix}-high-level-design-review.md (create reviews/ directory if needed).