nhs-adr-writer

name: nhs-adr-writer description: 'Use when documenting architectural decisions for an NHS digital service using the ADR format, or when reviewing technology choices for GDS assessment evidence.'

NHS ADR Writer — Architectural Decision Records

This skill generates Architectural Decision Records (ADRs) for NHS digital services. ADRs provide the evidence trail required by GDS Service Standard point 11 ("Choose the right tools and technology") and point 12 ("Make new source code open").

When to Use

Documenting a technology choice (framework, hosting, database, auth strategy)
Recording a design decision that affects the system architecture
Preparing evidence for a GDS Alpha assessment
Reviewing or updating an existing ADR after a decision changes

ADR Format

Use the MADR (Markdown Any Decision Records) format. Store ADRs as new files in docs/adr/ with sequential numbering. Do not edit this skill file — it is a reference, not a template to fill in.

docs/adr/
├── README.md           # Index of all ADRs
├── 0001-backend-framework.md
├── 0002-frontend-framework.md
├── 0003-hosting-platform.md
├── 0004-infrastructure-as-code.md
├── 0005-authentication-strategy.md
└── ...

ADR Template

# ADR-NNNN: [Decision Title]

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-NNNN

**Date**: YYYY-MM-DD

**Deciders**: [Who was involved in the decision]

## Context

[What is the issue that we're seeing that is motivating this decision or change?
Include NHS-specific constraints that influenced the decision.]

## Decision

[What is the change that we're proposing and/or doing?]

## Consequences

### Positive
- [What becomes easier or possible as a result of this change?]

### Negative
- [What becomes more difficult as a result of this change?]

### Risks
- [What risks does this decision introduce?]

## Alternatives Considered

### [Alternative 1]
- **Pros**: [advantages]
- **Cons**: [disadvantages]
- **Why rejected**: [reason]

### [Alternative 2]
- **Pros**: [advantages]
- **Cons**: [disadvantages]
- **Why rejected**: [reason]

## NHS Constraints

[Document any NHS-specific constraints that influenced this decision, such as:]
- Data sovereignty (UK hosting)
- NHS Digital standards compliance
- Clinical safety implications (DCB0129)
- Data protection (UK GDPR Art. 9 special category)
- NHS Design System requirements
- Integration with NHS systems (PDS, Spine, MESH)

## References

- [Links to relevant documentation, RFCs, NHS standards]

Standard ADRs for NHS Alpha Services

Every NHS Alpha built during the workshop should document at minimum:

ADR-0001: Backend Framework — Python/FastAPI

Context: Need a lightweight, async-capable API framework with strong type validation
Decision: FastAPI with Pydantic for input validation, Uvicorn as ASGI server
NHS constraints: NHS Digital Python community of practice, strong ecosystem for health data processing
Alternatives: Django REST Framework (heavier, more opinionated), Flask (no built-in validation)

ADR-0002: Frontend Framework — React with nhsuk-react-components

Context: Need to build user-facing pages compliant with NHS Design System
Decision: React 18 with TypeScript, Vite, and nhsuk-react-components
NHS constraints: Must use NHS Design System components, WCAG 2.2 AA mandatory
Alternatives: Jinja2 server-side rendering (simpler but less interactive), Next.js (more complex than needed for Alpha)

ADR-0003: Hosting — Azure App Service (UK South)

Context: NHS data sovereignty requires UK-based hosting; team has Azure subscription
Decision: Azure App Service on Linux in UK South region
NHS constraints: Data must remain in UK, Managed Identity for authentication, Key Vault for secrets
Alternatives: Azure Container Apps (more complex), NHS Cloud Centre of Excellence recommends Azure

ADR-0004: Infrastructure as Code — Terraform

Context: Infrastructure must be reproducible and auditable
Decision: Terraform with azurerm provider, state stored remotely
NHS constraints: Multiple Alpha teams may share a subscription; naming convention uses var.app_name for isolation
Alternatives: Bicep (Azure-only, less portable), Pulumi (smaller community)

ADR-0005: Authentication Strategy — Managed Identity

Context: Service-to-service auth needed for Key Vault, Application Insights
Decision: User Assigned Managed Identity, no service principal secrets
NHS constraints: No client secrets in code or CI/CD; aligns with NHS Cloud Centre of Excellence guidance
Alternatives: Service Principal with client secret (less secure, secret rotation burden)

ADR Index Template (`docs/adr/README.md`)

# Architectural Decision Records

This directory contains the Architectural Decision Records (ADRs) for this service.

| ADR | Title | Status | Date |
|---|---|---|---|
| [0001](0001-backend-framework.md) | Backend Framework — Python/FastAPI | Accepted | YYYY-MM-DD |
| [0002](0002-frontend-framework.md) | Frontend Framework — React/nhsuk-react-components | Accepted | YYYY-MM-DD |
| [0003](0003-hosting-platform.md) | Hosting — Azure App Service UK South | Accepted | YYYY-MM-DD |
| [0004](0004-infrastructure-as-code.md) | Infrastructure as Code — Terraform | Accepted | YYYY-MM-DD |
| [0005](0005-authentication-strategy.md) | Authentication — Managed Identity | Accepted | YYYY-MM-DD |

## What is an ADR?

An Architectural Decision Record captures a significant design decision along with
its context and consequences. See [GDS Service Standard point 11](https://www.gov.uk/service-manual/service-standard/point-11-choose-the-right-tools-and-technology).

Rules

Number ADRs sequentially — never reuse a number
Set status to "Accepted" when the team agrees, not before
When a decision changes, create a new ADR that supersedes the old one — never delete ADRs
Include NHS-specific constraints — assessors look for evidence of constraint-aware decision making
Keep ADRs concise — 1–2 pages maximum
Write in plain English — ADRs may be read by non-technical assessors