cc-os/plugins/os-adr/skills/create/SKILL.md

description

Record an architecture decision as a correctly templated, numbered, and indexed ADR in one invocation. Use unprompted WHEN a decision of real consequence has just been made or is being made mid-task — choosing between technologies, setting a convention, changing an approach the codebase already uses, or reversing/superseding a previously recorded decision (a reversal is itself a decision that must be recorded). Invoked by `/os-adr:create`.

Create a new ADR under docs/adr/. All mechanical work (ID assignment, templating, index regeneration, supersession bookkeeping) is done by the plugin's CLI — never hand-author the file, number, or index.

Moments that warrant an ADR (recognize these unprompted; don't wait to be asked):

• a technology/library/protocol choice with alternatives that were genuinely considered
• a convention or pattern the codebase will now follow
• a change that replaces an approach the codebase already uses
• a reversal of an existing Accepted ADR — a task that reverses a recorded decision is not complete until the superseding ADR is created (supersedes: NNNN); implementing the change and stopping leaves the ADR history asserting the opposite of what the code does

1. Gather the decision content

From the conversation (ask only for what you cannot infer):

• title — short, imperative or noun-phrase ("Use Postgres for persistence")
• context — the forces/problem that made a decision necessary
• decision — what was decided, stated actively
• consequences — what becomes easier/harder as a result
• alternatives — options considered and why each was rejected (highest-value field; push for real reasons, not placeholders)
• affected_paths / affected_components — repo paths and component names this decision governs (used for deterministic retrieval later; be concrete, e.g. ["src/db/", "config/database.yml"])
• status — default Accepted; use Proposed only if the user says it isn't settled
• supersedes — 4-digit ID, only if this replaces an existing ADR (check docs/adr/README.md)

If the project has no docs/adr/ yet, run /os-adr:init first (or its CLI, step 2's adr-init).

2. Invoke the CLI

echo '{"title": "...", "context": "...", "decision": "...", "consequences": "...",
  "alternatives": "...", "affected_paths": ["..."], "affected_components": ["..."]}' \
  | ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-new --root <project-root>

Optional JSON fields: status, date (ISO), supersedes ("NNNN"). The CLI prints the created file path, sets superseded-by + Superseded status on any superseded ADR, and regenerates docs/adr/README.md. Prefer writing the JSON to a temp file and piping it (cat file | ...) when section bodies contain quotes.

3. Confirm

Show the user the created path and a one-line summary. Do not edit the generated index by hand.