adr-creation

Files (5)

• SKILL.md
• html-design-system.md
• html-narrative-guide.md
• template-html.html
• template-markdown.md

SKILL.md (first lines)

# 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)

From ceilidhboy/skills, MIT.

More from ceilidhboy/skills