add-single-adr
Skill1 starsChanged 5 months agoMITView on GitHub
Use this skill when a designer or developer wants to add a single Architecture Decision Record (ADR) to the VA Design System documentation site. Triggers on phrases like 'add an ADR', 'add a design decision', 'I have an ADR for [component]', 'write an ADR from this PR', or when someone shares a PR URL, rough notes, or formatted markdown and wants it documented. Handles all cases: creating a new design-decisions page from scratch, appending to an existing one, or drafting the ADR itself from a PR or rough notes.
In this repositoryOne other file it gives its agents.
- ship-notesSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
27 rules. About 0 are common, 17 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
If the content already includes both a "date raised" and a "decision date", use both.
- Distinctive: line 36
If only one date is provided or known, ask:
- Distinctive: line 40
If no date is provided at all, ask:
- Distinctive: line 44
If the decision is still in-progress or proposed with no decision date yet, record only the date raised and mark the ADR Proposed.
- Distinctive: line 54
Do not draft, invent, or fill in any content the user didn't provide.
- Distinctive: line 61
Ask only for what's missing.
- Distinctive: line 69
Wait for their answers. Do not write the ADR until you have real content for all three sections.
- Distinctive: line 95
Before drafting anything, assess whether this PR contains a genuine design decision worth recording.
- Distinctive: line 111
If the PR clearly contains a design decision — you can articulate what was decided and why — proceed to draft.
- Distinctive: line 113
If you're not confident it's a design decision (ambiguous signals, looks more like a bug fix, or the "why" is unclear), ask before drafting:
- Distinctive: line 125
If any of the three sections can't be filled from the PR alone, note what's missing and ask: *"The PR doesn't give me enough to write the …
- Distinctive: line 133
Check the file system to understand what you're working with before touching anything.
- Distinctive: line 156
Read the flat file's full content
- Very specific: line 161
Create [collection]/[path]/index.md with the same content, adding a permalink if not already present:
- Very specific: line 165
Add it after the layout line.
- Very specific: line 166
Add a redirect_from entry pointing to the path without trailing slash:
- Very specific: line 171
Delete the original flat .md file
- Distinctive: line 245
Do not add a "Last updated" line.
- Distinctive: line 253
Read the existing file
- Very specific: line 256
Update the anchors frontmatter to add the new ADR heading as the last anchor entry
- Very specific: line 306
Always include at least one date.
- Very specific: line 308
If the decision was made on the same day it was raised, use only Decision date: — a single date is sufficient.
- Very specific: line 309
If the dates differ, include both Date raised: and Decision date: so the gap is visible.
- Very specific: line 310
If only one date is known, use the appropriate label (Date raised: or Decision date:) so it's clear what the date represents — never leave …
- Distinctive: line 348
Place it with the other boolean flags.
- Distinctive: line 356
If this component already has a row in the index: Update the "Last updated" date to today's date.
- Distinctive: line 358
If this is a new entry: Add a row to the correct table in alphabetical order.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add a Single ADR to VADS Docs
This skill adds one Architecture Decision Record (ADR) to the VADS documentation site. It handles every case: creating the directory and file structure if it doesn't exist yet, appending to an existing design-decisions page, drafting ADR content from a PR or rough notes, and updating the central ADR index.
Announce at start: "I'm using the add-single-adr skill to document this decision."
Repo root: Detect by running git rev-parse --show-toplevel from the current working directory. All file paths in this skill are relative to that root.
Step 1: Gather inputs
You need three things. Collect only what hasn't already been provided:
1. Component or pattern name
The full path slug relative to the collection — e.g. telephone, accordion, form/telephone-input, ask-users-for/address. Many form components live under form/, so "va-telephone-input" or "telephone input" → form/telephone-input.
2. The decision content
Accept whichever of these the user provides — don't ask for a specific format:
- A PR URL or number (e.g.
https://va.ghe.com/software/vets-website/pull/1234or#1234) → fetch and draft the ADR (see Step 1a) - Rough notes or a decision statement → identify what's missing and ask before writing anything (see Step 1b)
- Formatted ADR markdown → use as-is with formatting transformations applied in Step 4
3. Dates
If the content already includes both a "date raised" and a "decision date", use both. If the dates are the same, use only **Decision date:**.
If only one date is provided or known, ask:
"Is [date] the date this was decided, or the date it was first raised? (Or do you have both?)"
If no date is provided at all, ask:
"Do you have a date for this decision? If so, is it the date it was decided or the date it was first raised? Hit Enter to use today's date ([today's date]) as the decision date."
If the decision is still in-progress or proposed with no decision date yet, record only the date raised and mark the ADR Proposed.
Once you have all three, proceed.
Step 1b: Gathering missing information from rough notes
Only when the user provided rough notes or a decision statement — not a PR, not formatted markdown.
Do not draft, invent, or fill in any content the user didn't provide. Your job here is to identify what's missing from the three required sections and ask for exactly that.
From the user's input, identify what was stated:
- Decision — usually present in some form (what was chosen)
- Context — often missing (why this decision was needed, what problem it solves)
- Consequences — almost always missing (positive outcomes, watch items or trade-offs)
Ask only for what's missing. Be specific — don't ask "can you tell me more?" Ask the actual question:
I have the decision: "[restate what they said concisely]"
Before I write this up, I need a couple more things:
- Context: What prompted this decision? What problem were you solving, or what situation made this choice necessary?
- Consequences: What are the positive outcomes? And are there any watch items — things teams should know about, trade-offs, or follow-up work?
Wait for their answers. Do not write the ADR until you have real content for all three sections. Only use what the user actually tells you — never infer, assume, or pad out sections with plausible-sounding content.
Once you have the answers, confirm back briefly: "Got it — I'll write this up now." Then proceed to Step 2.
Step 1a: Drafting from a PR (only if a PR URL or number was given)
Fetch the PR. For vets-website or the forms library:
GH_HOST=va.ghe.com gh pr view [number] --repo software/vets-websiteFor the VADS docs repo:
GH_HOST=va.ghe.com gh pr view [number] --repo software/vets-design-system-documentationAlso fetch the diff to see what actually changed:
GH_HOST=va.ghe.com gh pr diff [number] --repo [repo]Before drafting anything, assess whether this PR contains a genuine design decision worth recording.
Signals that suggest a bug fix, not a decision:
- PR label is
patchorbugfix - Title starts with "Fix", "Fixes", "Bug:", "Correct", "Resolve"
- Description says "closes a bug", "this was broken", "regression", or similar
- The change restores behavior to match documented spec
- The diff shows no change in intended behavior — only a correction to make behavior match intent
Signals that suggest a real design decision:
- A deliberate behavior change — something that worked one way and is now intentionally different
- An alternative approach was considered and rejected
- The change has a meaningful trade-off (something is gained, something is given up)
- Teams using the component will need to change how they use it
- The change came from research, accessibility findings, or a specific user problem
If the PR clearly contains a design decision — you can articulate what was decided and why — proceed to draft.
If you're not confident it's a design decision (ambiguous signals, looks more like a bug fix, or the "why" is unclear), ask before drafting:
"Before I write this up — is this a design decision or a bug fix? A bug fix corrects something that was broken or behaving unintentionally. A design decision intentionally changes how something works. It's worth capturing if there was a deliberate choice made here, especially if there were alternatives considered or if the change has trade-offs teams should know about."
Wait for their answer. If they confirm it's a decision worth documenting, proceed. If they say it's a bug fix, let them know: "Got it — bug fixes don't need an ADR. Let me know if there's a decision embedded in how you fixed it that's worth capturing separately."
Once confirmed as a decision, draft the ADR with only what the PR actually tells you:
- A clear title that names the decision (not just "Update X" — say what was decided and why it matters)
- Context: What problem or situation prompted this? Only include what the PR description or diff makes clear — do not invent a rationale.
- Decision: What was chosen? Note any alternatives visible in the PR or description.
- Consequences: What's in the diff that would affect teams? Flag breaking changes, deprecated APIs, or test updates required. Do not invent trade-offs.
If any of the three sections can't be filled from the PR alone, note what's missing and ask: "The PR doesn't give me enough to write the [context / consequences] — can you fill that in?"
Show the draft to the user before writing: "Here's a draft based on the PR — does this capture the decision accurately? I've left [X] blank since I couldn't find it in the PR." Only proceed after they confirm.
Step 2: Determine what already exists
Check the file system to understand what you're working with before touching anything.
find src/_components src/_patterns src/_templates -iname "*[slug]*" 2>/dev/nullThen check the result:
| What exists | What to do |
[collection]/[path]/design-decisions.md | File exists — go to Step 4a (append) |
[collection]/[path]/index.md (no design-decisions.md) | Directory exists — skip Step 3, go to Step 4 (create file) |
[collection]/[path].md (flat file) | Go to Step 3 (convert to directory, then Step 4) |
| Nothing found | Tell the user and confirm the correct path before continuing |
Set [collection] to whichever of src/_components, src/_patterns, or src/_templates matched. Carry this value through all remaining steps — it determines permalink structure, frontmatter, and which index table to update. Use [path] everywhere [name] appears in remaining steps.
Step 3: Convert flat file to directory
Only if Step 2 found a flat .md file. Skip entirely otherwise.
- Read the flat file's full content
- Derive the URL prefix from
[collection]:src/_components→/components/src/_patterns→/patterns/src/_templates→/templates/
- Create
[collection]/[path]/index.mdwith the same content, adding apermalinkif not already present:
Add it after thepermalink: /[url-prefix]/[path]/layoutline. Ensure it has a trailing slash. Leave all other frontmatter unchanged. - Add a
redirect_fromentry pointing to the path without trailing slash:redirect_from: - /[url-prefix]/[path] - Delete the original flat
.mdfile
Step 4: Create a new design-decisions.md
Only if no design-decisions.md exists yet. Skip to Step 4a if it already exists.
Create [collection]/[path]/design-decisions.md.
Derive [Title] from the title: field in the index.md. Use the correct frontmatter based on the collection detected in Step 2:
For a component (src/_components/)
---
layout: documentation
permalink: /components/[path]/design-decisions/
title: [Title] - Design decisions
intro-text: Key design decisions for the [Title] component.
parent: [Title]
has-parent: /components/[path]/
anchors:
- anchor: What is an ADR?
- anchor: ADR 001 - [decision title]
---For a pattern (src/_patterns/)
---
layout: documentation
permalink: /patterns/[path]/design-decisions/
title: [Title] - Design decisions
intro-text: Key design decisions for the [Title] pattern.
parent: [Title]
parent-type: pattern
has-parent: /patterns/[path]/
anchors:
- anchor: What is an ADR?
- anchor: ADR 001 - [decision title]
---For a template (src/_templates/)
---
layout: documentation
permalink: /templates/[path]/design-decisions/
title: [Title] - Design decisions
intro-text: Key design decisions for the [Title] template.
parent: [Title]
parent-type: template
has-parent: /templates/[path]/
anchors:
- anchor: What is an ADR?
- anchor: ADR 001 - [decision title]
---The anchors list must include What is an ADR? first, then each ADR heading verbatim.
Body
{% include design-decisions-what-is-an-adr.md %}
## ADR 001 - [decision title]
[formatted ADR content — see Step 4b]Do not add a "Last updated" line. Strip one from the source if present.
Step 4a: Append to an existing design-decisions.md
Only if design-decisions.md already exists.
- Read the existing file
- Find the highest existing ADR number — the new one gets the next number (e.g. if ADR 003 exists, add ADR 004)
- Append the new ADR at the end of the file using the formatting rules in Step 4b
- Update the
anchorsfrontmatter to add the new ADR heading as the last anchor entry
Step 4b: ADR formatting rules
Apply these to all ADR content, whether creating or appending.
Structure
Each ADR has this structure:
## ADR [number] - [decision title]
<va-tag-status status="success" text="Accepted"></va-tag-status>
- **Decision date:** [date]
### Context
[What problem or situation prompted this decision?]
### Decision
[What was decided? Be specific.]
### Consequences
**Positive:**
- [outcome]
**Negative / watch items:**
- [trade-off or thing to monitor]Status tag values
| Status | Tag |
| Accepted | <va-tag-status status="success" text="Accepted"></va-tag-status> |
| Proposed | <va-tag-status status="info" text="Proposed"></va-tag-status> |
| Not for MVP | <va-tag-status status="warning" text="Not for MVP"></va-tag-status> |
| Deprecated | <va-tag-status status="error" text="Deprecated"></va-tag-status> |
| Anything else | <va-tag-status status="info" text="[value]"></va-tag-status> |
The tag is a standalone block element — not a list item. The date lines are bullets below it.
Dates
Always include at least one date. Format all dates as "Month Day, Year" (e.g. April 21, 2025). Convert any other format before writing.
- If the decision was made on the same day it was raised, use only
**Decision date:**— a single date is sufficient. - If the dates differ, include both
**Date raised:**and**Decision date:**so the gap is visible. - If only one date is known, use the appropriate label (
**Date raised:**or**Decision date:**) so it's clear what the date represents — never leave a date without a label.
Markdown tables → <va-table>
<va-table table-type="bordered">
<va-table-row>
<span>Header 1</span>
<span>Header 2</span>
</va-table-row>
<va-table-row>
<span>Value</span>
<span>Value</span>
</va-table-row>
</va-table>External links → <va-link>
Replace [text](https://...) with <va-link href="https://..." text="text"></va-link>. Leave internal links (starting with / or {{ site.baseurl }}) as standard markdown.
Headings and spacing
- Normalize to
## ADR [number] - [title](no colon after ADR) - No
---horizontal rules between ADRs or at the end of the file
Step 5: Add has-design-decisions: true to the component or pattern frontmatter
Skip if the flag is already present.
Open [collection]/[path]/index.md and add:
has-design-decisions: truePlace it with the other boolean flags. This triggers the "Design decisions" link in the Resources bar on the component, pattern, or template page.
Step 6: Update the About > Design decisions index
Read src/_about/design-decisions.md.
If this component already has a row in the index: Update the "Last updated" date to today's date.
If this is a new entry: Add a row to the correct table in alphabetical order.
The index has two tables:
- Components with design decisions — for
/components/paths - Patterns with design decisions — for
/patterns/or/templates/paths
<va-table-row>
<span><va-link href="{{ site.baseurl }}/[url-prefix]/[path]/design-decisions/" text="[Title] - Design decisions"></va-link></span>
<span>[today's date, Month Day, Year]</span>
</va-table-row>Where [url-prefix] is components, patterns, or templates — the collection path without the src/ prefix or leading underscore (established in Step 3).
Step 7: Confirm and next steps
Tell the user:
- The ADR number assigned (e.g. "Added as ADR 003")
- Which files were created or modified
- The URL where it will be accessible (e.g.
/components/telephone/design-decisions/) - Whether the component was converted from flat file to directory (if applicable)
- That the About > Design decisions index has been updated
Then prompt them to open a PR:
Next step: open a pull request. When you're ready, push your branch and open a PR against
mainin thevets-design-system-documentationrepo. Include the component or pattern name with the ADR title in the PR title so reviewers know what decision is being documented.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

