tractorjuice/arckit-hld-review

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

$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-custom/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 ${user_config.default_classification}; if unavailable, use "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:

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

Populate Generation Metadata Footer:

The footer should be populated with:

**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