# Adr Creation

> Creates and maintains dual-format ADRs — Markdown (source of truth for agents) and HTML (rich explainer for humans with diagrams). Keeps both formats in sync on updates. Use when user says "create an ADR", "document this decision", "write an ADR", "ADR for X", or when creating or updating a file in docs/adr/.

- Skill: `ceilidhboy/adr-creation` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ceilidhboy/adr-creation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ceilidhboy/adr-creation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ceilidhboy (https://skillmd.com/u/ceilidhboy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ceilidhboy/adr-creation

---


# ADR Creation (Dual Format)

## Core Principles

1. **Markdown** (`<adr-dir>/YYYY-MM-DD_kebab-title.md`) is the source of truth.
   Concise, technical — for AI agents. The ADR directory is `docs/adr/` by
   default, but mirror the project's existing ADR location if it differs
   (e.g. `wip/docs/adr/`).

2. **HTML** (`<adr-dir>/html/YYYY-MM-DD_kebab-title.html`) is the human explainer.
   Rich, narrative, with diagrams. **Lead with the problem** — open with a concrete
   before-state so the reader feels the pain before learning the fix. The HTML
   destination is task-derived — do not consult `htmlOutputDir` settings for ADRs.

3. **HTML targets non-technical readers.** The markdown is for developers and AI
   agents — concise, technical, assumes domain knowledge. The HTML is for sending
   to clients, stakeholders, project managers, and non-programming colleagues.
   Include explainers for concepts the markdown takes for granted. If you must use
   a technical term, define it inline. Use analogies. Assume the reader knows the
   business problem but not the code.

4. **Keep both in sync.** Stale HTML is worse than no HTML.

## File Naming

Both files share the same YYYY-MM-DD_kebab-case-title, differing only by extension.
No ADR numbering — numbers clash across branches. Refer by date + title
(e.g. "see Capture Referrer As Intended Login URL (2026-07-19)").

## Process: Creating a New ADR

### 1. Gather context

Ask: What decision was made? What was the problem? What alternatives were considered?
Why was this approach chosen?

Auto-detect project name and repo URL from README.md or `git remote get-url origin`.

### 2. Create the Markdown ADR

Determine the ADR directory first: use where the project's existing ADRs live
(look for `docs/adr/`, `wip/docs/adr/`, etc.), defaulting to `docs/adr/` when
none exist yet. Write to `<adr-dir>/YYYY-MM-DD_kebab-title.md`. Use the template in
[template-markdown.md](template-markdown.md).

### 3. Create the HTML ADR

Write to `<adr-dir>/html/YYYY-MM-DD_kebab-title.html`. The HTML should:
- Expand freely — diagrams, narrative, safety checks. Never contradict the markdown.
- Follow the **section order** below.
- Be self-contained (single HTML file, no external dependencies).

### Design system and SVG conventions

**YOU MUST check whether the `html-output` skill is installed.** If it is, read its
`references/DESIGN_SYSTEM.md` for the canonical CSS tokens, colour palette,
typography, spacing, and CSS patterns — and its `references/SVG_GUIDELINES.md`
for SVG diagram conventions (figure structure, common diagram types, flowcharts,
timelines). These are the authoritative sources and take precedence over the
bundled fallback.

If `html-output` is NOT installed, fall back to the bundled
[html-design-system.md](html-design-system.md) — an abridged subset of the
design system sufficient for standalone ADR creation.

Follow the narrative guide in [html-narrative-guide.md](html-narrative-guide.md) —
audience, story examples, readability principles, before/after diagrams.

#### HTML section order

1. **Problem in plain English** — Concrete before-state example. A story that answers
   "why should I care?" Assume your reader is a project manager or client — they
   know the business problem but not the code or terminology. Define technical terms
   inline.
2. **Why it happened** — Root cause in lay terms. Before/after flow diagrams.
3. **What we changed** — The fix or improvement. Include any safety guards added.
4. **Consequences** — Positive outcomes and trade-offs, in plain language.

### 4. Add cross-links

- Markdown frontmatter: add `html` (relative) and `html_github` (absolute) fields.
- HTML header: link back to the markdown on GitHub.

### 5. Present to the user

Show both files for review before committing. On WSL, link HTML files as
`file://wsl.localhost/Ubuntu-24.04/...`.

## Process: Updating an Existing ADR

1. Edit the markdown first (source of truth).
2. Regenerate the HTML — same narrative depth, consistent facts.
3. Cross-link consistency — both files link to each other correctly.
4. Present for review.

## Cross-Reference URLs

```
Markdown: https://github.com/{owner}/{repo}/blob/HEAD/docs/adr/YYYY-MM-DD_kebab-title.md
HTML:     https://github.com/{owner}/{repo}/blob/HEAD/docs/adr/html/YYYY-MM-DD_kebab-title.html
```

Use `HEAD` (not a branch name). Derive `{owner}` and `{repo}` from `git remote get-url origin`.
Adjust the `docs/adr/` path in the URLs if the project's ADR directory differs.

## Markdown Notes

- The markdown is for AI agents. Keep it concise and technical.
- Context → Decision → Consequences is sufficient. No narrative treatment.
- Only explain non-obvious system behaviour; skip what's self-evident.

## Reference Files

- [template-markdown.md](template-markdown.md) — Markdown template
- [template-html.html](template-html.html) — HTML boilerplate
- [html-narrative-guide.md](html-narrative-guide.md) — Audience, story examples, readability principles, before/after diagrams
- [html-design-system.md](html-design-system.md) — CSS tokens, visual style rules (fallback; superseded by `html-output/references/DESIGN_SYSTEM.md` when the `html-output` skill is installed)