agentleFS
jeana-adhocjeana-adhoc/claude-skills/skills/add-single-adr/SKILL.md

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.

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
  1. Very specific:

    If the content already includes both a "date raised" and a "decision date", use both.

    line 34
  2. Distinctive:

    If only one date is provided or known, ask:

    line 36
  3. Distinctive:

    If no date is provided at all, ask:

    line 40
  4. Distinctive:

    If the decision is still in-progress or proposed with no decision date yet, record only the date raised and mark the ADR Proposed.

    line 44
  5. Distinctive:

    Do not draft, invent, or fill in any content the user didn't provide.

    line 54
  6. Distinctive:

    Ask only for what's missing.

    line 61
  7. Distinctive:

    Wait for their answers. Do not write the ADR until you have real content for all three sections.

    line 69
  8. Distinctive:

    Before drafting anything, assess whether this PR contains a genuine design decision worth recording.

    line 95
  9. Distinctive:

    If the PR clearly contains a design decision — you can articulate what was decided and why — proceed to draft.

    line 111
  10. Distinctive:

    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:

    line 113
  11. Distinctive:

    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 …

    line 125
  12. Distinctive:

    Check the file system to understand what you're working with before touching anything.

    line 133
  13. Distinctive:

    Read the flat file's full content

    line 156
  14. Very specific:

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

    line 161
  15. Very specific:

    Add it after the layout line.

    line 165
  16. Very specific:

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

    line 166
  17. Very specific:

    Delete the original flat .md file

    line 171
  18. Distinctive:

    Do not add a "Last updated" line.

    line 245
  19. Distinctive:

    Read the existing file

    line 253
  20. Very specific:

    Update the anchors frontmatter to add the new ADR heading as the last anchor entry

    line 256
  21. Very specific:

    Always include at least one date.

    line 306
  22. Very specific:

    If the decision was made on the same day it was raised, use only Decision date: — a single date is sufficient.

    line 308
  23. Very specific:

    If the dates differ, include both Date raised: and Decision date: so the gap is visible.

    line 309
  24. Very specific:

    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 …

    line 310
  25. Distinctive:

    Place it with the other boolean flags.

    line 348
  26. Distinctive:

    If this component already has a row in the index: Update the "Last updated" date to today's date.

    line 356
  27. Distinctive:

    If this is a new entry: Add a row to the correct table in alphabetical order.

    line 358

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 existsWhat to do
[collection]/[path]/design-decisions.mdFile 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 foundTell 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/
  3. Create [collection]/[path]/index.md with the same content, adding a permalink if not already present:
    permalink: /[url-prefix]/[path]/
    Add it after the layout line. Ensure it has a trailing slash. Leave all other frontmatter unchanged.
  4. Add a redirect_from entry pointing to the path without trailing slash:
    redirect_from:
      - /[url-prefix]/[path]
  5. 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]

<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

StatusTag
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: 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
<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 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.