/hld-review

Evaluate a High-Level Design (HLD) note against linked ADRs, requirements, and architecture principles. Produces a structured review with scoring across six dimensions, severity-rated findings, and actionable next steps.

Usage

/hld-review <HLD note title>
/hld-review HLD - Remote Vault Access Architecture
/hld-review HLD - SecureTransfer Azure Files to S3 Mirroring

Arguments

• $ARGUMENTS: The title of the HLD note to review (required). Must match an existing HLD - *.md file in the vault root.

Review Dimensions

Instructions

Phase 1: Load the HLD

1. Parse the command — extract the HLD note title from $ARGUMENTS
2. Find the HLD file — search for the file at the vault root matching the title
   • If not found, search using Grep for partial title matches across HLD - *.md files
   • If still not found, report the error and list available HLD notes
3. Read the HLD note — load the full content including frontmatter and body
4. Extract metadata:
   • relatedTo wiki-links from frontmatter
   • tags for domain context
   • confidence, freshness, verified quality indicators
   • Any inline wiki-links in the body text ([[...]] references)

Phase 2: Gather Context

1. Read linked notes — for each wiki-link found in relatedTo and body text:

   • Read each linked note (ADRs, Systems, Concepts, Projects, Patterns)
   • Categorise by type: ADR, System, Concept (principle/capability), Project, Pattern, Threat, other
   • Note the status of each ADR (draft/proposed/accepted/deprecated/superseded)

2. Query for architecture principles — find all Concept notes with conceptType: principle:

   bash
   1node .claude/scripts/graph-query.js --type=Concept --tag=conceptType/principle

   If the graph query returns no results, fall back to:

   bash
   1grep -rl "conceptType: principle" *.md

   Read each principle note to extract:

   • statement — the principle itself
   • implications — what follows from the principle
   • domain — which domain it applies to

3. Query for related threats — search for Threat notes relevant to the HLD's domain:

   • Check tags on the HLD for domain indicators (e.g., domain/security, domain/cloud, domain/integration)
   • Search: node .claude/scripts/graph-query.js --type=Threat
   • Match threats by affectedSystems and domain overlap

4. Check for related ADRs not yet linked — search for ADRs whose relatedTo or project fields reference the same systems or projects as the HLD:

   bash
   1node .claude/scripts/graph-query.js --type=Adr --tag=status/accepted

Phase 3: Evaluate Each Dimension

Score each dimension as PASS, PARTIAL, or FAIL using the criteria below.

3.1 ADR Coverage

How to assess:

• Identify each significant design choice in the HLD (technology selections, architectural patterns, protocol choices)
• Check whether an ADR exists for each choice (via relatedTo links or vault search)
• Note any ADRs that are draft or proposed rather than accepted
• Flag design choices that contradict accepted ADRs

3.2 Requirements Traceability

How to assess:

• Extract requirements from linked Project notes (goals, constraints, scope)
• Extract requirements from linked Concept notes (capabilities, principles)
• Verify each requirement has a corresponding design element in the HLD
• Check for orphaned requirements (mentioned in links but not in design)

3.3 Principle Compliance

How to assess:

• For each principle note loaded in Phase 2, check whether the HLD design aligns with the principle's statement and implications
• Focus on principles whose domain matches the HLD's domain tags
• Flag any contradictions between the design and established principles

3.4 Security Architecture

How to assess:

• Check for explicit security boundaries (network isolation, trust zones)
• Verify encryption is specified for data in transit and at rest
• Look for authentication and authorisation mechanisms
• Cross-reference with Threat notes — are relevant threats mitigated?
• Check for data classification and GDPR considerations if personal data is involved

3.5 Integration Clarity

How to assess:

• Identify all system boundaries and interfaces in the HLD
• Check each interface for: protocol, data format, authentication method, error handling
• Verify data flow direction is explicit (which system initiates, which responds)
• Look for SLA/latency/throughput specifications where applicable
• Check for retry and failure handling strategies

3.6 Operational Readiness

How to assess:

• Check for monitoring and alerting strategy
• Look for deployment approach (blue/green, rolling, canary)
• Verify rollback/recovery procedures are considered
• Check for logging and observability mentions
• Look for capacity planning and scaling considerations
• Check for runbook or operational handover references

Phase 4: Compile Findings

Categorise each finding by severity:

Phase 5: Determine Review Status

Based on the dimension scores and finding severities:

Phase 6: Generate Review Output

Output the review directly to the console. Use the template below.

Output Template

markdown
1# HLD Review: [HLD Title]
2
3**Reviewed:** [today's date]
4**HLD Created:** [created date from frontmatter]
5**Last Reviewed:** [reviewed date from frontmatter]
6**Confidence:** [confidence from frontmatter]
7
8---
9
10## Review Status: [APPROVED / APPROVED WITH CONDITIONS / NEEDS REWORK]
11
12---
13
14## Scoring Summary
15
16| Dimension | Score | Evidence | Gaps |
17|---|---|---|---|
18| ADR Coverage | [PASS/PARTIAL/FAIL] | [what ADRs exist and cover] | [what design choices lack ADRs] |
19| Requirements Traceability | [PASS/PARTIAL/FAIL] | [requirements addressed] | [requirements not addressed] |
20| Principle Compliance | [PASS/PARTIAL/FAIL] | [principles aligned with] | [principles not addressed or contradicted] |
21| Security Architecture | [PASS/PARTIAL/FAIL] | [security measures documented] | [security aspects missing] |
22| Integration Clarity | [PASS/PARTIAL/FAIL] | [interfaces documented] | [interfaces lacking detail] |
23| Operational Readiness | [PASS/PARTIAL/FAIL] | [operational aspects covered] | [operational aspects missing] |
24
25---
26
27## Findings
28
29### BLOCKING
30
31[If none: "No blocking findings."]
32
331. **[Finding Title]** — [Description of the gap, which dimension it affects, and why it blocks progress]
34   - **Dimension:** [affected dimension]
35   - **Recommendation:** [specific action to resolve]
36
37### ADVISORY
38
39[If none: "No advisory findings."]
40
411. **[Finding Title]** — [Description and recommendation]
42   - **Dimension:** [affected dimension]
43   - **Recommendation:** [specific action to resolve]
44
45### INFORMATIONAL
46
47[If none: "No informational findings."]
48
491. **[Finding Title]** — [Observation or suggestion]
50
51---
52
53## Conditions
54
55[Only include if status is APPROVED WITH CONDITIONS]
56
57The following conditions must be addressed before implementation:
58
59- [ ] [Condition 1 — specific, actionable item]
60- [ ] [Condition 2]
61
62---
63
64## Context Analysed
65
66### Linked ADRs
67| ADR | Status | Relevance |
68|-----|--------|-----------|
69| [[ADR - Title]] | accepted | [how it relates to the HLD] |
70
71### Architecture Principles Assessed
72| Principle | Domain | Compliance |
73|-----------|--------|------------|
74| [[Concept - Principle Name]] | [domain] | [aligned/not addressed/contradicted] |
75
76### Threat Coverage
77| Threat | Severity | Mitigated? |
78|--------|----------|------------|
79| [[Threat - Name]] | [severity] | [yes/partial/no] |
80
81### Systems Referenced
82[List of System notes referenced in the HLD with their status]
83
84---
85
86## Next Steps
87
88- [ ] [Action item based on findings — e.g., "Create ADR for Docker orchestration choice"]
89- [ ] [Action item — e.g., "Add monitoring section to HLD"]
90- [ ] [Action item — e.g., "Link Threat - Denial of Service and document mitigation"]
91- [ ] Update HLD `reviewed` date to today
92- [ ] Update HLD `verified` to `true` once conditions are met

Examples

Example 1: Quick Review

/hld-review HLD - Remote Vault Access Architecture

Reviews the HLD against all six dimensions, checking linked ADRs, vault principles, relevant threats, and operational completeness.

Example 2: Review After ADR Changes

/hld-review HLD - SecureTransfer Azure Files to S3 Mirroring

Useful after new ADRs are accepted to verify the HLD still aligns with the latest decisions.

Error Handling

• HLD not found: List all available HLD notes in the vault and ask the user to confirm
• No linked notes: Report that the HLD has an empty relatedTo field — this is itself a finding (ADVISORY: "HLD lacks cross-references to ADRs, systems, and requirements")
• Graph index unavailable: Fall back to Grep-based search for principles and threats
• No principles found: Note this as INFORMATIONAL — the vault may not yet have principle notes established

Related Skills

• /nfr-review — Review an HLD against NFR requirements (complementary to this skill)
• /diagram-review — Analyse architecture diagrams for readability and quality
• /adr — Create new ADRs for design choices identified as gaps
• /diagram — Generate architecture diagrams referenced in the HLD
• /impact-analysis — Analyse the impact of changes to systems in the HLD

Related Notes

• .claude/rules/naming-conventions.md — HLD naming patterns
• .claude/context/frontmatter-reference.md — HLD frontmatter schema
• .claude/context/architecture.md — Architecture governance context