Add Single Adr

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/1234 or #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-website

For the VADS docs repo:

GH_HOST=va.ghe.com gh pr view [number] --repo software/vets-design-system-documentation

Also 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 patch or bugfix
• 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/null

Then 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.

1. Read the flat file's full content
2. Derive the URL prefix from [collection]:

• src/_components → /components/
• src/_patterns → /patterns/
• src/_templates → /templates/

1. Create [collection]/[path]/index.md with the same content, adding a permalink if not already present:

``yaml permalink: /[url-prefix]/[path]/ ` Add it after the layout` line. Ensure it has a trailing slash. Leave all other frontmatter unchanged.

1. Add a redirect_from entry pointing to the path without trailing slash:

```yaml redirect_from:

• /[url-prefix]/[path]

```

1. Delete the original flat .md file

---

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.

1. Read the existing file
2. Find the highest existing ADR number — the new one gets the next number (e.g. if ADR 003 exists, add ADR 004)
3. Append the new ADR at the end of the file using the formatting rules in Step 4b
4. Update the anchors frontmatter 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]

- **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 | ` | | Proposed | | | Not for MVP | | | Deprecated | | | Anything else | ` |

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 → ``

  
    Header 1
    Header 2
  
  
    Value
    Value
  

External links → ``

Replace [text](https://...) with `. 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: true

Place 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

  
  [today's date, Month Day, Year]

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 main in the vets-design-system-documentation repo. Include the component or pattern name with the ADR title in the PR title so reviewers know what decision is being documented.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeana-adhoc
• Source: jeana-adhoc/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.