DavidROliverBA/hld-review

/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

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:

   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

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:

   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