| name | architecture-document-review |
| version | 1.0.0 |
| description | Review architecture documents for defensibility, boundary clarity, ownership, survivability, and testability. Works beyond manufacturing. |
| tags | ["architecture","review","manufacturing","isa-95","idmz","ot","governance","risk"] |
| tool_agnostic | true |
Architecture Document Review
Review architecture documents as architecture documents — not as general writing or implementation specs.
Use When
- Reviewing target-state documents, patterns, proposals, standards, technical principles, ADRs, BDRs, or control baselines
- Checking whether a document is safe, testable, and usable across multiple sites or contexts
- Challenging weak claims, blurred ownership, vendor hand-waving, or cloud assumptions that would fail in production
- Pressure-testing architecture language before review with security, legal, OT, or platform stakeholders
Do Not Use When
- The task is software implementation or code review
- The task is pure copy-editing, grammar cleanup, or branding polish only
- The document is a project plan or migration backlog rather than an architecture artifact
Review Standard
Default to blunt, evidence-oriented review.
Check the document against these questions:
- Is the architectural problem clear, or is the document just describing technology?
- Are scope, assumptions, and hard constraints explicit?
- Are trust boundaries, separation concerns, and support-access assumptions stated clearly where relevant?
- Does the design survive WAN loss, cloud loss, vendor outage, and degraded-mode operation where production depends on it?
- Is ownership explicit for design authority, approvals, operations, exceptions, and lifecycle?
- Is the control model concrete enough to audit, test, or implement?
- Are supplier obligations, exit constraints, and operating costs visible where external services are involved?
- Is the document reusable across multiple sites or contexts, or does it quietly depend on local heroics?
Grounding
Before reviewing, read the document carefully. For manufacturing architecture, also ground in:
- Any packed repository context (e.g.
ai-context/architecture-context.md) as read-only compiled context
- Any directly related source documents that are more authoritative than packed context
Procedure
-
Identify the artifact type.
Distinguish between principle note, pattern, proposal, decision record, reference design, control standard, or vendor assessment.
-
Identify the review lens.
Default is architectural defensibility. Add security, operating model, vendor, cost, rollout, or governance emphasis only when the document requires it.
-
Review for findings first.
Lead with concrete issues, not summary praise. Focus on missing constraints, blurred ownership, broken boundary assumptions, and untestable or non-operable statements.
-
Separate structural issues from writing issues.
Do not waste time on prose cleanup when the actual architecture is weak.
-
State residual risk.
Even when no major findings exist, call out testing gaps, dependency risk, site-variation risk, or operating-model assumptions.
Output Shape
- Findings ordered by severity
- Open questions or assumptions that need resolution
- Short change summary only if useful
Common Failure Modes To Call Out
- Generic "best practice" language with no enforceable meaning
- Cloud dependency that would stop production or critical operations
- Direct cross-boundary trust or hidden vendor-access shortcuts
- Missing ownership for exceptions, approvals, or operations
- No cost, lifecycle, support, or exit story
- Local effort assumed but not staffed or funded
- Principles that sound good but cannot be evidenced or tested
- Designs that are technically sound but operationally undeliverable in the actual environment
