/record-decision

name: record-decision
description: >
  Append a new Architecture Decision Record (ADR) to the repo with an
  auto-incremented number and the MADR template.
  TRIGGER when the user says "record this decision", "log this
  decision", "add an ADR for X", "create an ADR about Y", "record the
  choice to use Postgres", "write up this decision", "document this
  as an ADR", "/nyann:record-decision".
  Do NOT trigger on "write a doc" / "add documentation" (those are
  broader — route to the appropriate doc skill). Do NOT trigger on
  "record a bug" / "open an issue" (those are GitHub concerns).
  Do NOT trigger on "what decisions have we made" (that's reading
  existing ADRs, not creating one).

record-decision

Wraps `bin/record-decision.sh`. Creates one ADR file per invocation under `docs/decisions/` (or the profile's configured location). Only MADR format is supported in v1.

1. Collect inputs from the user

• **`--title`** (required). Short, imperative headline: *"Use Postgres

for the primary datastore"*, *"Adopt pnpm over npm"*. If the user's phrasing is long and prose-y ("I think we should probably go with Postgres because…"), propose a crisp title and confirm.

• **`--status`**. `proposed` (default) when the decision is still up

for review; `accepted` when the user says "we've already decided" or similar. Never default to `accepted` silently — when unclear, **you MUST call the `AskUserQuestion` tool** (not plain text):

  {
    "questions": [
      {
        "question": "What is the status of this decision?",
        "header": "Status",
        "multiSelect": false,
        "options": [
          { "label": "Proposed (Default)", "description": "Decision is open for review" },
          { "label": "Accepted", "description": "Decision has already been agreed upon" }
        ]
      }
    ]
  }

• **`--dir`**. Default `docs/decisions`. Override when the repo uses

a different location (check the profile's `documentation.scaffold_types` if uncertain).

• **`--slug`** — derived from the title. Review the auto-derived slug

with the user when the title contains non-ASCII or unusual punctuation.

2. Check for existing scaffolding

`record-decision` creates the directory if missing, but doesn't scaffold a `README.md` or `ADR-000`. If the directory is empty (no prior ADRs), mention that `bootstrap-project` scaffolds an introductory `ADR-000` and offer to run it first — but proceed with the new ADR either way if the user insists.

3. Dry-run first when the title is non-obvious

Run `bin/record-decision.sh --dry-run` and read back:

• The target path (which ADR number it'll land at).
• The derived slug.

Confirm before the real run. Single-line "record that we chose X" phrasings can skip confirmation when the title is already explicit.

4. Invoke

bin/record-decision.sh --target <cwd> \
  --title "<imperative headline>" \
  [--status proposed|accepted] \
  [--dir <path>] \
  [--slug <slug>] \
  [--date YYYY-MM-DD] \
  [--dry-run]

5. After creation

The output JSON gives you the relative path. Offer to:

• Open the file so the user can fill in the sections (Context,

Decision drivers, Considered options, Decision outcome, Consequences, Validation).

• Stage it for commit via `/nyann:commit` (suggest a commit subject

like `docs(adr): ADR-NNN — <title>`).

Do NOT auto-fill the body from the user's conversation. An ADR's value comes from the writer thinking through the structure; filling it with Claude-generated prose dilutes that.

6. Number collisions

Numbers come from scanning `ADR-<NNN>-*.md` files in the target directory. When the user has a non-conventional ADR naming scheme (e.g. `0001-foo.md` without the `ADR-` prefix), the detector will miss them and start at 000. If the user reports this, offer to rename existing files or accept a manual `--dir` pointing at a separate location.

When to hand off

• "Show me existing ADRs" → `ls docs/decisions/` or a simple file

listing; outside this skill.

• "Update an existing ADR" → this skill creates only. Supersedence

is represented as a new ADR pointing at the old one (MADR convention).

• "Generate a changelog entry for this decision" → `release` skill

handles CHANGELOG; ADRs and CHANGELOG are separate stores.