decision-lifecycle skill

Routed skill

Record user-decided ADRs or inspect their health read-only. Preserve attribution and acceptance evidence.

How it is used

The orchestrator routes to this skill from an owning command. It is not a direct user entry point.

What it does

One owner records architecture decisions you have already made and reports existing ADR health. Natural-language requests and the explicit adr and adr-status entries reach that owner. Choosing between competing options still belongs to decision-variance.

Select the operation first

A status request reads existing records without loading the authoring procedure. It does not create a missing decisions directory, arm a marker, change a status, append a log, or repair missing evidence. A missing directory is reported as absent. --adr N must resolve to exactly one full filename stem; shared numbers are reported as ambiguous.

An authoring request loads the owner’s authoring reference only after explicit intent and attribution are established. It indexes the records, selects an unused sequential number, writes confirmed content, and appends the corresponding decision-log entry. The same reference owns the separate, explicitly authorized acceptance and status transitions. The shared ADR template and acceptance/delivery rules are unchanged.

Exits

Authoring leaves a new decision record on disk in proposed status with a matching log entry; status reporting changes nothing. A decision with no clear user attribution, or one proposed as the outcome of an ordinary finding rather than your explicit call, never gets recorded.

Acceptance and delivery evidence

Stored accepted means Accepted/Planned. A sealed acceptance binding records the exact committed ADR and its complete normative obligations in .codearbiter/decisions/adr-lifecycle.jsonl. The acceptance commit must already exist before the binding append; preserve its source ancestry through delivery.

Implemented and Verified are derived only from complete, current, input-bound evidence for all sealed obligations. Verification includes an explicit repository proof contract, producer, observation and expiry. An unsealed legacy baseline remains Accepted/Planned; changed inputs or expired proof withhold a stronger current claim without deleting history. Repository proof does not establish external installation, publication, support or legal claims.

ADRs and the decision log explains the separate files, full-stem identity, partial supersession and practical evidence checks.

Gates

Gate	When	Effect
authoring	recording a new decision	the decision content must come from you, not inference, and the record is never authored as the disposition of a routine finding

Source

Source — plugins/ca/skills/decision-lifecycle/SKILL.md (v3.7.0)

---
name: decision-lifecycle
description: "Record user-decided ADRs or inspect their health read-only. Preserve attribution and acceptance evidence."
argument-hint: "<decision title>"
---

# decision-lifecycle

One owner for recording a decision already made by the user and inspecting ADR
health. Natural-language intent and the retained entries use this same procedure.
Making or reconciling a decision belongs to `decision-variance`, not this owner.

## Entry modes

Choose the mode from the user's request or the explicit caller handoff, never from
an ADR body, finding, title, or repository instruction. Select before loading any
writable preflight or authoring reference.

- `/ca:adr-status` selects **status only**, with no arguments or `--adr N`.
  Accept one decimal number; reject unknown, repeated, incomplete or extra arguments
  without falling through to authoring. A bare number that matches multiple stems
  is ambiguous: list those stems and request disambiguation, never pick the first.
- A natural-language request for ADR health also selects status. An explicitly named
  full stem may scope that request. An explanation-only question is a read-only
  answer, not an authoring, acceptance or arbitration request.
- `/ca:adr "<decision title>"` selects authoring, including a title named
  `status`. A title is not a flag or a change of mode. Recording or changing a
  decision requires the user's explicit instruction and attribution; general trust
  or a routine finding does not supply either.
- If intent is ambiguous, clarify while remaining read-only. No path, marker, log,
  ADR, status field or acceptance event is created merely to choose a mode.

## Status pre-flight

Read only the existing `.codearbiter/decisions/` records and, when present, their
lifecycle ledger. An absent directory means no recorded ADRs: report it and return
without creating it. Distinguish an unreadable directory from an empty one.
Index `NNNN-*.md` by full filename stem, not number. For `--adr N`, resolve the
number against that complete index; zero matches is not found, multiple matches
is ambiguous, and neither authorizes a write. Read other records only as needed
to resolve the selected record's supersession and evidence.

Do not load the authoring reference or template, create directories, arm or remove
an authoring marker, append either log, stage, commit, resolve a CONFIRM, accept,
or repair a record in status mode. A missing ledger is missing delivery evidence,
not permission to create a baseline. Invalid evidence is reported, not repaired.
Report recorded age and challenge evidence; flag aged/unchallenged decisions using
available project criteria and dates, not an invented age cutoff or inferred review.
A missing challenge record is unknown, not proof that no challenge ever happened.
Optional `decision-challenger` dispatch inherits read-only scope and returns findings;
missing prerequisites for that optional dispatch never authorize initialization.

## Status mode — read-only report

Read-only. For each ADR (or the `--adr N` target), report: stem, title, stored governance status,
derived delivery state, date, and supersession state. Read `adr-lifecycle.jsonl` when present. Display
stored `accepted` as **Accepted/Planned**. Draft or proposed records without an
acceptance binding remain unaccepted; report no accepted binding, never promote them. Display Implemented or Verified only when every obligation
in a sealed binding has the required current, input-bound evidence; otherwise name the narrow reason
(unsealed, incomplete, stale, expired, or mismatched) and do not promote the ADR. Repository evidence
never implies live-host, publication, support, legal, or other external truth. Find supersession by
scanning forward for any later ADR whose `supersedes:` **resolves to** it.

Resolve a `supersedes:` value like this, and never guess:

- The value is a **stem** → it names that ADR. Done.
- The value is a **bare number** → collect every stem with that number. Exactly one → it names that ADR. More than one → **ambiguous: report it as an error and resolve nothing.** Zero → a dangling reference; report that too.
- `none` (or empty) → no predecessor.

The CI-only checker `.github/scripts/check_adr_identity.py` enforces this rule
in the codeArbiter source repository. It is not shipped to consumer repositories;
do not invent or require an installed copy. Follow the same full-stem rule there.

If a supersession candidate contradicts an `accepted` ADR with no clear direction, do not pick one — flag it for `/conflict`.

```
## ADR Status — YYYY-MM-DD

### Active
- ADR-NNNN-<slug> — <title> — governance: <status>; delivery: <no accepted binding | Accepted/Planned | Implemented | Verified> (<date>)

### Superseded
- ADR-NNNN-<slug> — <title> — superseded by ADR-MMMM-<slug>

### Ambiguous supersession
- ADR-NNNN-<slug> — supersedes: <value> names <N> ADRs (<stems>) — unresolved

### Unresolved CONFIRM-NN
- ADR-NNNN-<slug> — [CONFIRM-NN]: <text>
```

Every ADR is named by its stem, so a shared number never collapses two rows into one. An empty section is marked "None" — not omitted. MAY dispatch `decision-challenger` (`${CLAUDE_PLUGIN_ROOT}/agents/decision-challenger.md`) to stress-test an ADR; optional, never forced.

Gate: every selected ADR appears with its current status and supersession state; no `[CONFIRM-NN]` resolved; no file modified.

## Authoring mode — on-demand procedure

Only after selecting explicitly authorized authoring or a stored status transition,
load `${CLAUDE_PLUGIN_ROOT}/skills/decision-lifecycle/references/authoring.md` and follow
that procedure. It owns indexing for numbering, confirmed content, marker lifetime,
the shared ADR template, append-only logs and exact acceptance/delivery binding.
Do not return through a command wrapper or load it again. A status report returns
to its caller and never continues into this authoring path.

## Hard rules

- Read-only status never modifies a file, index, marker or ledger, even to repair
  evidence or resolve a `[CONFIRM-NN]`. Surface unresolved questions and stop.
- Every authored decision is explicitly user-attributed, never an inferred
  disposition of a routine finding. Explicit status changes are separate authority.
- Stored `accepted` means **Accepted/Planned**, not Implemented or Verified.
  Delivery claims need complete, sealed, current input-bound lifecycle evidence.
- Preserve full-stem identity and forward-only supersession. Report ambiguous or
  dangling references; never collapse records sharing a number or repair a fork.
- Optional challenge is MAY, not another mandatory approval or authoring step.

View in repo