SuperAPI AI Directory

write-adr

General & other

View repository

Updated 10-16 05:51

About this skill

/write-adr — Architecture Decision Record scaffolder

This skill writes one ADR file at docs/adr/NNNN-<slug>.md in the consumer's project. It is a scaffolder, not an interview — keep prompts short and focused. The user is here to write down a decision they have already weighed, not to be grilled into making one. (If the user actually needs to interrogate an upstream ask, point them at /gather-requirements instead.)

What an ADR is in this repo

An immutable record of a cross-cutting platform commitment — warehouse choice, modelling convention, PII-handling pattern, governance posture, ingestion framework, scheduler choice. An ADR differs from a DGQ in scope (platform-wide, not a per-stakeholder ask) and in lifecycle (superseded by a later ADR, never edited in place once accepted). Format is MADR-lite: Context, Decision Drivers, Considered Options, Decision, Consequences.

This skill is self-contained: the ADR contract it writes against ships beside it at references/adr.md, and the linter that enforces that contract ships at scripts/lint-adr.sh. Read the contract for the frontmatter fields, enum domains, and body section order before writing — do not duplicate that material here; reference it.

Optional deeper reading — not required to run this skill (a per-skill install works without them): the full repo worldview in CONTEXT.md and the lifecycle reference in docs/data-engineering-101.md.

The hard rule: no single-option ADRs

If the user supplies fewer than two Considered Options, refuse to write the file. Surface the pushback explicitly with the framing below — do not soften it, do not work around it, do not silently fill in a placeholder "do nothing" option on the user's behalf.

An ADR with one option isn't a decision — it's a postcard. The Considered Options section exists to record the alternatives you weighed (including the "keep the status quo" or "do nothing" option, if those were genuinely on the table). What were the realistic alternatives, and why are they not the chosen path? If you really did not consider alternatives, this probably isn't ADR-shaped — log it as a code comment, a runbook note, or a CHANGELOG entry instead.

Ask the user to either name at least one more option or to drop the ADR.

Steps

Carry out the following in order. Do not ask for every section up front in one wall of questions — prompt for each piece as you go.

1. Locate docs/adr/ and pick the next number

  • If docs/adr/ does not exist in the current project, create it.
  • Scan docs/adr/ for filenames matching NNNN-*.md (four-digit prefix). The next number is max(existing) + 1, zero-padded to four digits. If none exist, start at 0001.
  • Ignore README.md and any non-conforming file when picking the number.

2. Prompt for the title

Ask for a one-line title in the active voice — "Adopt Snowflake as the warehouse", "Standardise on dbt for transformation", "Encrypt regulated PII at rest with customer-managed keys". Derive a kebab-case slug from the title (lowercase, hyphens for spaces, ASCII letters and digits only, strip punctuation). Confirm NNNN-<slug>.md with the user before writing.

3. Prompt for the five MADR-lite sections, in order

For each, prompt the user separately. Keep prompts tight; do not deliver a multi-paragraph monologue per section.

  • Context. The situation forcing the decision. One short paragraph: what changed, what is being decided, who needs the answer, and any constraint that bounds the choice.
  • Decision Drivers. What matters when choosing. A short list — typically 2–5 bullets (cost envelope, latency, sensitivity classification, team familiarity, vendor lock-in, governance posture, time-to-first-value). The drivers should be the things the rationale in Decision will refer back to.
  • Considered Options. A list of the realistic alternatives. Minimum two. Each as a bullet with a half-sentence framing of what the option is. If the user offers only one option, invoke the pushback above and stop.
  • Decision. The chosen option, followed by one or two sentences of rationale that reference the drivers from the previous section.
  • Consequences. Positive and negative, both explicit. Use either two short bullet lists (Positive / Negative) or one combined list with +/- markers — whichever the user prefers — but make sure both kinds of consequence are recorded. If the user only volunteers positives, ask for at least one cost or trade-off.

4. Status and date

  • Default status to proposed. Ask the user once if they want to mark it accepted instead (which implies the decision is already in force, with the team behind it).
  • Write a date field as YYYY-MM-DD for today.
  • Do not invent a superseded-by-NNNN status here — that value is only set later by a future ADR that explicitly replaces this one. The linter accepts the value; this skill does not write it.

5. Write the file

Write to docs/adr/<NNNN>-<slug>.md, shaped exactly as the contract in references/adr.md specifies — the three frontmatter fields and the five MADR-lite body sections. Each earlier step already gathered the content each field and section needs: the title and slug from step 2, the five sections from step 3, the status and date from step 4. Read the contract for the exact field list, enum domains, and section order rather than reproducing them here.

Run the bundled structural linter scripts/lint-adr.sh — it sits beside this SKILL.md, in the skill folder's own scripts/ — as a cheap sanity check after writing. Resolve it relative to this skill folder and invoke it from the consumer project root so it picks up docs/adr/ (or point it elsewhere with ADR_ROOT=<dir>). It is best-effort: if the script is present in this install, run it; if it is absent — a partial install that dropped the skill's scripts/, say — skip it silently and rely on the consumer's pre-commit hook.

6. Confirm

Print a short confirmation containing the file path, the ADR number, and the status. Do not summarise the body of the ADR back to the user — they just wrote it; reading it back is noise.

Example:

Wrote docs/adr/0003-adopt-snowflake.md
  number: 0003
  status: proposed

After writing

If the conversation surfaces a related per-stakeholder ask (e.g., "we also need to track the migration rollout for the analytics team"), suggest invoking /gather-requirements separately rather than bundling a DGQ into this run. One skill, one artefact — keep the ADR clean.