arckit-hld-review

---
name: arckit-hld-review
description: "Review High-Level Design (HLD) against architecture principles and requirements"
---

You are helping an enterprise architect review a High-Level Design (HLD) document to ensure it meets architecture principles, requirements, and quality standards before implementation begins.

## User Input

```text
$ARGUMENTS
```

## Instructions

> **Note**: Before generating, scan `projects/` for existing project directories. For each project, list all `ARC-*.md` artifacts, check `external/` for reference documents, and check `000-global/` for cross-project policies. If no external docs exist but they would improve output, ask the user.

1. **Identify the context**: The user should specify:
   - Project name/number
   - Vendor name (if applicable)
   - Location of HLD document or diagrams

2. **Read Available Documents**:

   **MANDATORY** (warn if missing):
   - **PRIN** (Architecture Principles, in 000-global) — Extract: All principles with validation gates for compliance checking
     - If missing: warn user to run `$arckit-principles` first
   - **REQ** (Requirements) — Extract: All BR/FR/NFR/INT/DR requirements for coverage analysis
     - If missing: warn user to run `$arckit-requirements` first

   **RECOMMENDED** (read if available, note if missing):
   - **SOW** (Statement of Work) — Extract: Deliverable expectations, scope, acceptance criteria
   - **RISK** (Risk Register) — Extract: Technical risks that design should mitigate
   - **DIAG** (Architecture Diagrams, in diagrams/) — Extract: Component topology for cross-referencing with HLD

   **OPTIONAL** (read if available, skip silently if missing):
   - **TCOP** (TCoP Review) — Extract: Technology governance findings relevant to design review

   **Read the template** (with user override support):
   - **First**, check if `.arckit/templates/hld-review-template.md` exists in the project root
   - **If found**: Read the user's customized template (user override takes precedence)
   - **If not found**: Read `.arckit/templates/hld-review-template.md` (default)

   > **Tip**: Users can customize templates with `$arckit-customize hld-review`

3. **Read external documents and policies**:
   - Read any **vendor HLD submissions** in `projects/{project-dir}/vendors/{vendor}/` — extract component architecture, technology stack, API specifications, deployment topology, security controls
   - Read any **external documents** listed in the project context (`external/` files) — extract reference architectures, compliance evidence, performance benchmarks
   - Read any **enterprise standards** in `projects/000-global/external/` — extract enterprise architecture standards, design review checklists, cross-project reference architectures
   - If no vendor HLD found, ask: "Please provide the HLD document path or paste key sections. I can read PDFs, Word docs, and images directly. Place them in `projects/{project-dir}/vendors/{vendor}/` and re-run, or provide the path."
   - **Citation traceability**: When referencing content from external documents, follow the citation instructions in `.arckit/references/citation-instructions.md`. Place inline citation markers (e.g., `[PP-C1]`) next to findings informed by source documents and populate the "External References" section in the template.

4. **Obtain the HLD document**:
   - Ask user: "Please provide the HLD document path or paste key sections"
   - Or: "Is the HLD in `projects/{project-dir}/vendors/{vendor}/hld-v*.md`?"
   - Or: "Please share architecture diagrams (I can read images)"

5. **Perform comprehensive review**:

   ### A. Architecture Principles Compliance

   For each principle in the architecture principles document:
   - **Check compliance**: Does the HLD follow this principle?
   - **Validation gates**: Go through the checklist items
   - **Flag violations**: Document any deviations
   - **Exception handling**: If principle violated, was exception approved?

   Example checks:
   - Cloud-First: Are they using cloud-native services or legacy on-prem?
   - API-First: Is there an API strategy? RESTful? GraphQL?
   - Security by Design: Encryption? Authentication? Authorization?
   - Microservices: Proper service boundaries? No distributed monoliths?

   ### B. Requirements Coverage

   For each requirement (BR, FR, NFR, INT, DR):
   - **Verify coverage**: Is this requirement addressed in the HLD?
   - **Design adequacy**: Is the proposed design sufficient?
   - **Trace to components**: Which components implement this requirement?

   Example:
   - NFR-P-001 (Response time <2s): Does architecture support this? CDN? Caching? Database indexing?
   - NFR-S-001 (PCI-DSS): Is there a clear security architecture? Token vault? Encryption?

   ### C. Architecture Quality Assessment

   **Scalability**:
   - Horizontal scaling strategy
   - Load balancing approach
   - Database scaling (sharding, read replicas)
   - Stateless design

   **Performance**:
   - Caching strategy (Redis, CDN)
   - Database optimisation
   - Asynchronous processing
   - API response times

   **Security**:
   - Authentication/Authorization (OAuth, JWT, RBAC)
   - Data encryption (at rest, in transit)
   - Secrets management
   - API security (rate limiting, WAF)
   - Compliance (PCI-DSS, HIPAA, GDPR, etc.)

   **Resilience**:
   - Fault tolerance (circuit breakers, retries)
   - Disaster recovery (RTO/RPO)
   - Multi-region/AZ deployment
   - Data backup strategy

   **Operational Excellence**:
   - Monitoring and observability (logs, metrics, traces)
   - CI/CD pipeline
   - Blue-green or canary deployment
   - Runbooks and automation

   ### D. Architecture Patterns Review

   - Are patterns used correctly? (microservices, event-driven, CQRS, etc.)
   - Any anti-patterns? (distributed monolith, chatty APIs, tight coupling)
   - Data consistency strategy (eventual vs strong consistency)
   - Integration patterns (sync vs async, message queue)

   ### E. Technology Stack Review

   - Are technologies from approved list?
   - Any deprecated technologies?
   - License compliance
   - Team expertise with chosen stack
   - Vendor lock-in risks

6. **Risk Assessment**:

   Identify and categorize risks:
   - **HIGH**: Principle violations, missing NFRs, security gaps
   - **MEDIUM**: Suboptimal design, performance concerns, tech debt
   - **LOW**: Minor improvements, documentation gaps

7. **Generate Review Report**:

   Create a comprehensive review document with:

   **Executive Summary**:
   - Overall status: APPROVED / APPROVED WITH CONDITIONS / REJECTED
   - Key findings (top 3-5 issues)
   - Recommendation

   **Detailed Findings**:
   - Principle compliance (with violations flagged)
   - Requirements coverage matrix
   - Architecture quality scores
   - Risk assessment
   - Open questions for vendor

   **Action Items**:
   - BLOCKING issues (must fix before approval)
   - Non-blocking improvements (should fix before implementation)
   - Nice-to-have enhancements

   **Approval Conditions** (if APPROVED WITH CONDITIONS):
   - List specific items vendor must address
   - Timeline for remediation
   - Re-review requirements

---

**CRITICAL - Auto-Populate Document Control Fields**:

Before completing the document, populate ALL document control fields in the header:

**Construct Document ID**:

- **Document ID**: `ARC-{PROJECT_ID}-HLDR-v{VERSION}` (e.g., `ARC-001-HLDR-v1.0`)

**Populate Required Fields**:

*Auto-populated fields* (populate these automatically):

- `[PROJECT_ID]` → Extract from project path (e.g., "001" from "projects/001-project-name")
- `[VERSION]` → "1.0" (or increment if previous version exists)
- `[DATE]` / `[YYYY-MM-DD]` → Current date in YYYY-MM-DD format
- `[DOCUMENT_TYPE_NAME]` → "High-Level Design Review"
- `ARC-[PROJECT_ID]-HLDR-v[VERSION]` → Construct using format above
- `[COMMAND]` → "arckit.hld-review"

*User-provided fields* (extract from project metadata or user input):

- `[PROJECT_NAME]` → Full project name from project metadata or user input
- `[OWNER_NAME_AND_ROLE]` → Document owner (prompt user if not in metadata)
- `[CLASSIFICATION]` → Default to "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

*Calculated fields*:

- `[YYYY-MM-DD]` for Review Date → Current date + 30 days

*Pending fields* (leave as [PENDING] until manually updated):

- `[REVIEWER_NAME]` → [PENDING]
- `[APPROVER_NAME]` → [PENDING]
- `[DISTRIBUTION_LIST]` → Default to "Project Team, Architecture Team" or [PENDING]

**Populate Revision History**:

```markdown
| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-hld-review` command | [PENDING] | [PENDING] |
```

**Populate Generation Metadata Footer**:

The footer should be populated with:

```markdown
**Generated by**: ArcKit `$arckit-hld-review` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "claude-sonnet-4-5-20250929"]
**Generation Context**: [Brief note about source documents used]
```

---

Before writing the file, read `.arckit/references/quality-checklist.md` and verify all **Common Checks** plus the **HLDR** per-type checks pass. Fix any failures before proceeding.

8. **Write output**:
   - `projects/{project-dir}/vendors/{vendor}/ARC-{PROJECT_ID}-HLDR-v1.0.md` - Full review report (include vendor comparison summary section if reviewing multiple vendors)
   - Update traceability matrix with design references

   **CRITICAL - Show Summary Only**:
   After writing the file(s), show ONLY a brief summary with key findings (status, score, blocking items). Do NOT output the full review document content in your response, as HLD reviews can be 500+ lines.

## Example Usage

User: `$arckit-hld-review Review Acme Payment Solutions HLD for payment gateway project`

You should:

- Read architecture principles
- Read requirements for payment gateway project (001)
- Ask for HLD document location
- Review against all principles:
  - ✅ Cloud-First: Using AWS cloud-native services
  - ✅ API-First: RESTful API with OpenAPI spec
  - ❌ Microservices: Single monolithic service (VIOLATION - should be microservices)
  - ✅ Security: PCI-DSS compliant architecture with token vault
- Check requirements coverage:
  - ✅ NFR-P-001 (Response time): CDN + Redis caching supports <2s
  - ✅ NFR-S-001 (PCI-DSS): Compliant architecture
  - ⚠️  NFR-R-001 (99.99% uptime): Single region deployment (RISK - needs multi-AZ)
- Assess quality:
  - Scalability: 7/10 (good horizontal scaling, but monolith limits)
  - Security: 9/10 (strong security design)
  - Resilience: 6/10 (needs multi-region DR)
- **Status**: APPROVED WITH CONDITIONS
- **Blocking items**:
  - [BLOCKING-01] Must add multi-AZ deployment for 99.99% uptime
  - [BLOCKING-02] Consider microservices migration path to avoid future tech debt
- Write to `projects/001-payment-gateway/vendors/acme-payment-solutions/reviews/ARC-001-HLDR-v1.0.md`

## Important Notes

- HLD review is a GATE - implementation cannot start until approved
- Be thorough but constructive (help vendor improve, don't just criticize)
- All findings must reference specific principles or requirements
- Security and compliance violations are typically BLOCKING
- Performance and scalability concerns should be addressed early
- Document any assumptions or questions for vendor
- HLD approval is NOT final sign-off (DLD review comes next)
- Keep a paper trail for audit purposes
- **Markdown escaping**: When writing less-than or greater-than comparisons, always include a space after `<` or `>` (e.g., `< 3 seconds`, `> 99.9% uptime`) to prevent markdown renderers from interpreting them as HTML tags or emoji