hld-review - SKILL.md Agent Skill

name: hld-review context: fork description: Evaluate an HLD note against linked ADRs, requirements, and architecture principles across six dimensions model: opus

/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 frontmatter
- tags for domain context
- confidence, 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:
```
node .claude/scripts/graph-query.js --type=Concept --tag=conceptType/principle
```
If the graph query returns no results, fall back to:
```
grep -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
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:
```
node .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

# HLD Review: [HLD Title]

**Reviewed:** [today's date]
**HLD Created:** [created date from frontmatter]
**Last Reviewed:** [reviewed date from frontmatter]
**Confidence:** [confidence from frontmatter]

---

## Review Status: [APPROVED / APPROVED WITH CONDITIONS / NEEDS REWORK]

---

## Scoring Summary

| Dimension | Score | Evidence | Gaps |
|---|---|---|---|
| ADR Coverage | [PASS/PARTIAL/FAIL] | [what ADRs exist and cover] | [what design choices lack ADRs] |
| Requirements Traceability | [PASS/PARTIAL/FAIL] | [requirements addressed] | [requirements not addressed] |
| Principle Compliance | [PASS/PARTIAL/FAIL] | [principles aligned with] | [principles not addressed or contradicted] |
| Security Architecture | [PASS/PARTIAL/FAIL] | [security measures documented] | [security aspects missing] |
| Integration Clarity | [PASS/PARTIAL/FAIL] | [interfaces documented] | [interfaces lacking detail] |
| Operational Readiness | [PASS/PARTIAL/FAIL] | [operational aspects covered] | [operational aspects missing] |

---

## Findings

### BLOCKING

[If none: "No blocking findings."]

1. **[Finding Title]** — [Description of the gap, which dimension it affects, and why it blocks progress]
   - **Dimension:** [affected dimension]
   - **Recommendation:** [specific action to resolve]

### ADVISORY

[If none: "No advisory findings."]

1. **[Finding Title]** — [Description and recommendation]
   - **Dimension:** [affected dimension]
   - **Recommendation:** [specific action to resolve]

### INFORMATIONAL

[If none: "No informational findings."]

1. **[Finding Title]** — [Observation or suggestion]

---

## Conditions

[Only include if status is APPROVED WITH CONDITIONS]

The following conditions must be addressed before implementation:

- [ ] [Condition 1 — specific, actionable item]
- [ ] [Condition 2]

---

## Context Analysed

### Linked ADRs
| ADR | Status | Relevance |
|-----|--------|-----------|
| [[ADR - Title]] | accepted | [how it relates to the HLD] |

### Architecture Principles Assessed
| Principle | Domain | Compliance |
|-----------|--------|------------|
| [[Concept - Principle Name]] | [domain] | [aligned/not addressed/contradicted] |

### Threat Coverage
| Threat | Severity | Mitigated? |
|--------|----------|------------|
| [[Threat - Name]] | [severity] | [yes/partial/no] |

### Systems Referenced
[List of System notes referenced in the HLD with their status]

---

## Next Steps

- [ ] [Action item based on findings — e.g., "Create ADR for Docker orchestration choice"]
- [ ] [Action item — e.g., "Add monitoring section to HLD"]
- [ ] [Action item — e.g., "Link Threat - Denial of Service and document mitigation"]
- [ ] Update HLD `reviewed` date to today
- [ ] 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