/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
| Dimension | What Is Checked |
|---|
| ADR Coverage | Does each significant design choice have a corresponding ADR? Are referenced ADRs accepted? |
| Requirements Traceability | Are all referenced requirements (from relatedTo, project notes, linked concepts) addressed in the design? |
| Principle Compliance | Does the design align with vault architecture principles (Concept notes with conceptType: principle)? |
| Security Architecture | Are threat mitigations documented? Are security boundaries, encryption, and access controls explicit? |
| Integration Clarity | Are system interfaces, data flows, protocols, and error handling paths clearly defined? |
| Operational Readiness | Are monitoring, deployment strategy, runbook considerations, and rollback plans addressed? |
Instructions
Phase 1: Load the HLD
- Parse the command — extract the HLD note title from
$ARGUMENTS
- 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
- Read the HLD note — load the full content including frontmatter and body
- Extract metadata:
relatedTo wiki-links from frontmattertags for domain contextconfidence, freshness, verified quality indicators- Any inline wiki-links in the body text (
[[...]] references)
Phase 2: Gather Context
-
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)
-
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 itselfimplications — what follows from the principledomain — which domain it applies to
-
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
-
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
| Score | Criteria |
|---|
| PASS | Every significant design choice (technology selection, architectural pattern, integration approach) has a corresponding accepted ADR |
| PARTIAL | Some design choices have ADRs but others are undocumented, or ADRs exist but are still in draft/proposed status |
| FAIL | Major design choices lack ADR coverage entirely |
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
| Score | Criteria |
|---|
| PASS | All requirements referenced in linked project/concept notes are explicitly addressed in the HLD |
| PARTIAL | Most requirements are addressed but some are missing or only implicitly covered |
| FAIL | Significant requirements gaps — linked requirements not addressed in the design |
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
| Score | Criteria |
|---|
| PASS | Design explicitly aligns with all applicable architecture principles; no contradictions |
| PARTIAL | Design is broadly consistent but some principles are not explicitly addressed |
| FAIL | Design contradicts one or more architecture principles, or ignores critical principles |
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
| Score | Criteria |
|---|
| PASS | Security boundaries, encryption (in-transit and at-rest), authentication, authorisation, and threat mitigations are all explicitly documented |
| PARTIAL | Some security aspects are covered but gaps exist (e.g., encryption mentioned but no auth model) |
| FAIL | Security is not meaningfully addressed in the HLD |
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
| Score | Criteria |
|---|
| PASS | All system interfaces are documented with protocols, data formats, error handling, and SLAs |
| PARTIAL | Interfaces are identified but details are incomplete (missing protocols, no error handling) |
| FAIL | System interfaces are vague or missing — unclear how components communicate |
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
| Score | Criteria |
|---|
| PASS | Monitoring, alerting, deployment strategy, rollback plan, and operational runbook considerations are documented |
| PARTIAL | Some operational aspects are covered but the design lacks deployment or monitoring detail |
| FAIL | No operational considerations — the HLD focuses only on functional architecture |
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:
| Severity | Definition | Action Required |
|---|
| BLOCKING | Fundamental gap that must be resolved before the design can proceed to implementation | Rework required |
| ADVISORY | Gap that should be addressed but does not prevent progress | Address before go-live |
| INFORMATIONAL | Observation or suggestion for improvement | Consider in future iterations |
Phase 5: Determine Review Status
Based on the dimension scores and finding severities:
| Status | When Applied |
|---|
| APPROVED | All dimensions PASS, no BLOCKING findings |
| APPROVED WITH CONDITIONS | No dimensions FAIL, but PARTIAL scores exist or ADVISORY findings need attention |
| NEEDS REWORK | Any dimension scores FAIL, or any BLOCKING findings exist |
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
1617|---|---|---|---|
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
6768|-----|--------|-----------|
69| [[ADR - Title]] | accepted | [how it relates to the HLD] |
70
71### Architecture Principles Assessed
7273|-----------|--------|------------|
74| [[Concept - Principle Name]] | [domain] | [aligned/not addressed/contradicted] |
75
76### Threat Coverage
7778|--------|----------|------------|
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
/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
.claude/rules/naming-conventions.md — HLD naming patterns.claude/context/frontmatter-reference.md — HLD frontmatter schema.claude/context/architecture.md — Architecture governance context
