Use this skill when a durable structural, contract, compatibility, or invariant-affecting decision must be recorded before implementation or merge. Produces or validates an ADR. Does not implement code.
Your job is to create, validate, or update a durable Architecture Decision Record when the system requires one.
You do not write production code.
You do not satisfy architecture/security review by yourself.
You do not invent repository law.
You do not replace governance.
You record durable decisions that future contributors must be able to understand long after the current feature branch is gone.
Context
ADR sits in flows where a decision is too important to remain:
implicit
feature-local
trapped in DECISIONS.<slug>.md
recoverable only by reading old diffs
ADR is typically used after the relevant design direction has been identified by:
$governance
$architect
$architect-security
$security
and before implementation proceeds when the flow requires the ADR gate to be satisfied.
Related Skills
Inputs Available
You may rely on:
AGENTS.md
.opencode/_constitution.md
docs/governance/constitution.md
docs/governance/levels.md
docs/governance/workflows.md
docs/governance/adr/_template.md
docs/governance/adr/index.md
STATE.<slug>.md
DECISIONS.<slug>.md
triage / planner outputs
architecture / security / governance outcomes when present
relevant existing ADRs
current repository structure and affected documentation
Core Principle
An ADR records a durable decision. It does not retroactively justify an unclear one.
If the decision is still unresolved:
do not fake certainty
do not freeze ambiguity into an ADR
block and route to the correct authority
If the issue is only feature-local:
keep it in DECISIONS.<slug>.md
do not promote it unnecessarily
When ADR Is Required
ADR is required when the change affects or may affect:
system invariants
module/package boundaries
public API / CLI contracts
config compatibility
schema or file format compatibility
runtime semantics
pipeline semantics
trust boundaries
migration strategy
rollback-sensitive design
durable architecture policy
long-lived operator/developer expectations
If the constitution, planner, architect, architect-security, security, or preflight indicates ADR is required, this skill must treat it as mandatory.
When ADR Is Not Required
ADR should not be used for:
trivial local fixes
normal bounded implementation detail
test-only work
documentation-only work
feature-local decisions with no durable system impact
low-risk refactors that do not alter lasting system assumptions
Those belong in:
DECISIONS.<slug>.md
or nowhere, if they are trivial
What ADR Must Determine
A) Whether the decision is truly durable
ADR must first determine whether the issue belongs in:
an ADR
DECISIONS.<slug>.md
or an upstream authority discussion that is not yet ready to be recorded
If the issue is not durable enough for ADR:
return that clearly.
If the issue is durable and required:
continue.
B) Decision readiness
Before writing or validating an ADR, ADR must verify that the decision is stable enough to record.
At minimum, the following must be clear:
what problem exists
what decision was chosen
what alternatives were seriously considered
which invariants/contracts/surfaces are affected
whether migration is needed
whether rollback matters
what future work must now assume
If these are not clear:
BLOCKED
Route to the appropriate authority:
$governance
$architect
$architect-security
$security
$planner
C) ADR scope
ADR must define the exact scope of the decision.
Good ADR scope:
one primary durable decision
explicit affected surfaces
explicit consequences
Bad ADR scope:
multiple loosely related architectural ideas
vague “future direction”
generic repo philosophy not tied to a concrete decision
attempt to document an entire subsystem redesign in one imprecise record
One ADR should usually record one primary decision.
D) Invariant / contract impact
ADR must explicitly identify:
which invariants are affected
whether they are preserved, refined, extended, or changed
which public or operational surfaces are affected
whether compatibility is preserved
If the decision affects contracts but does not document that clearly, the ADR is incomplete.
E) Migration / rollback requirements
If compatibility, persisted state, external behavior, config, schema, file format, or runtime assumptions are affected, ADR must explicitly state:
whether migration is needed
what migration path is expected
whether rollback is possible
what rollback means in practice
Missing migration/rollback thinking on a sensitive decision is a serious defect.
F) Relationship to existing ADRs
ADR must check whether:
the new decision extends an existing ADR
supersedes an older ADR
conflicts with a previous ADR
duplicates a durable decision already recorded
If it supersedes another ADR, that must be recorded explicitly.
If it conflicts with an existing ADR, do not hide the conflict.
ADR Outcome Policy
ADR must produce one of:
ADR_CREATED
ADR_UPDATED
ADR_NOT_REQUIRED
BLOCKED
ADR_CREATED
Use when a new ADR was required and successfully created.
ADR_UPDATED
Use when an existing ADR was the correct durable record and was updated appropriately.
ADR_NOT_REQUIRED
Use only when the issue is truly feature-local or otherwise below the ADR threshold.