version: "1.0.0" name: decision description: 'Use when the user has made an architectural, technical, or product decision and wants it recorded as a written .context/decisions/ ADR — what was chosen, why, the alternatives, and the consequences — so the team does not re-litigate it later. Fires on "we decided X", "document this decision", "write an ADR", "record the decision to X", "log why we chose X", "we settled on X, write it up". Not for: planning multi-step work (/aidex:plan); deferring or parking an idea for later (/aidex:backlog); capturing a stakeholder/client request (/aidex:request), research notes (/aidex:research), or a settled reference (/aidex:reference); ecosystem audits (/aidex:aidex); project-state audits (/aidex:audit).' disable-model-invocation: false allowed-tools: Bash Read Write

Decision

Record an architectural, technical, or product decision as an ADR in .context/decisions/ so it is not re-litigated later. This skill is the single-purpose entry point for decision records; the formatting canon lives in the shared conventions reference package (not forked here).

Workflow

1. Read the decision conventions canon:

${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/request-decision-conventions.md (Decisions section; or .claude/skills/conventions/references/request-decision-conventions.md if a project-level copy exists).

1. Create a single dated file: .context/decisions/YYYY-MM-DD-<slug>.md

(slug kebab-case; date YYYY-MM-DD).

1. Front-matter per the canon — decisions use the ADR status enum

(accepted · superseded · dropped), not the base open/doing/done vocabulary. Set superseded_by: decision/<filename> when one decision replaces another.

1. Body per the canon template: Context, Decision, Consequences

are the mandated triad. Capture the deciding factor, not just the verdict. Add a separate Options Considered (Pros/Cons) section only when two or more alternatives were genuinely weighed; otherwise fold the alternatives into the Decision prose ("considered X and Y; chose Z because …"). Write the artifact in English (canon §Language).

Closing a decision

Decisions close only when superseded or dropped (an accepted ADR stays active in place). Close atomically (stamps updated, sets status + superseded_by, archives per D-10) instead of hand-editing:

bash ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/close-dated-artifact.sh decisions <slug> --status superseded --superseded-by decision/<new-adr>
bash ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/close-dated-artifact.sh decisions <slug> --status dropped

Self-check

Validate the artifact you just wrote and fix any violation before closing:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/validate.py --type decisions

If the project carries a ratchet baseline (.context/.validate-baseline.json), a non-zero exit means you introduced a NEW violation — fix it before closing.

Boundaries

Related

• conventions — owns the shared documentation canon (this skill

delegates into its references/request-decision-conventions.md).