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.

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 — an abridged subset of the design system sufficient for standalone ADR creation.

Follow the narrative guide in 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 — Markdown template
• template-html.html — HTML boilerplate
• html-narrative-guide.md — Audience, story examples, readability principles, before/after diagrams
• 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)