Record Decision

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.