adr-author

name	adr-author
description	Produces a numbered Architecture Decision Record (ADR) file in the project's ADR directory. Use when the user asks to create an ADR, write an architecture decision record, document a decision, add to the decision log, or mentions docs/adr/. Also trigger when the user says "new ADR", "log a decision", or "record why we chose X". Do not use for general documentation, READMEs, or non-decision narrative writing.
allowed-tools	Read Write Edit Bash
license	GPL-3.0-only
status	unstable
metadata	{"version":"0.1.0","author":"Leandro Kellermann de Oliveira <[e-mail]>","model":"sonnet"}

ADR Author

This skill creates a numbered Architecture Decision Record (ADR) file following a consistent structure. ADRs are written after a change has been tested and applied — they document what was actually learned, not just what was planned.

---

Step 1 — Gather the title

The user must provide a short slug for the decision (e.g. github-actions-pipeline, lock-file-strategy). If no title is given, ask before proceeding.

---

Step 2 — Find the next ADR number

Locate the ADR directory:

1. Check for docs/adr/ relative to the repo root. If it does not exist, ask the user for the correct path before creating any file.
2. Run ls <adr-dir>/ (or Bash: ls) and collect all filenames that begin with three digits (e.g. 001-initial-setup.md, 010-lock-file.md).
3. Parse the leading three-digit prefix from each filename; take the maximum.
4. The new ADR number is max + 1, zero-padded to three digits.
   • Example: highest existing is 010 → new file is 011-<title>.md.
   • If no ADRs exist yet, start at 001.

If the listing fails (directory missing, permissions, etc.), stop and report the error to the user before creating any file.

---

Step 3 — Collect content from the user

Ask the user for the following before writing the file:

1. Context — What problem or situation prompted this decision? Include constraints, triggering events, and alternatives considered.
2. Decision — What was decided and how it works?
3. Status — One of: Accepted, Proposed, or Superseded by ADR <NNN>.

If the user says "fill it in" or gives only a rough description, scaffold placeholder text in each section and remind them to complete it before merging.

---

Step 4 — Create the ADR file

Write <adr-dir>/<NNN>-<title>.md with this exact structure:

# ADR <NNN> — <Human-readable title>

**Date:** <today's date in YYYY-MM-DD>
**Status:** <Accepted | Proposed | Superseded by ADR NNN>

---

## Context

<Why this decision was needed. Include constraints, triggering events, alternatives
considered. Be specific — vague context makes ADRs useless six months later.>

---

## Decision

<What was decided and how it works. Include config snippets, commands, or diagrams
where they clarify the decision.>

---

## What we learned

<Numbered lessons — specific gotchas, error messages encountered, non-obvious
behaviour. Each lesson should be actionable: someone hitting the same wall should
be able to fix it in minutes by reading this.>

---

## Next steps

<Bullet list of follow-on work, with checkboxes. Mark completed items with [x].>

---

## References

<Link to official documentation, RFCs, or external resources that informed the
decision. Use plain Markdown links. If purely internal, write:
`N/A — internal design decision.`>

Formatting rules:

• Use **Date:** and **Status:** on separate lines, not in a table.
• Do not add a "Consequences" or "Alternatives" section unless the user asks.
• "What we learned" is the highest-value section — push the user to fill it in with specific, actionable lessons rather than leaving it empty or generic.
• "References" is required — always link to official docs or write the N/A note.

---

Step 5 — Confirm and remind

After writing the file, tell the user:

1. The exact path of the file created (e.g. docs/adr/011-github-actions-pipeline.md).
2. Which sections still need their input (Context, What we learned, Next steps) if placeholder text was used.
3. Reminder: ADRs in this project are written after a change is tested and applied — they document what was actually learned, not just what was planned.

---

Error handling

• If the ADR directory cannot be found or listed, report the error and ask the user for the correct path. Do not guess or create a new directory without confirmation.
• If a file with the computed name already exists, report the conflict and ask whether to increment the number or overwrite.
• If today's date cannot be determined from the environment, use YYYY-MM-DD as a placeholder and note it in the reminder.