adr-sequencer

name

adr-sequencer

description

Manage a CORPUS of Architecture Decision Records over time — the longitudinal discipline atop adr-writer (which authors ONE ADR): numbering and the ADR index/log, the status lifecycle (proposed → accepted → deprecated → superseded), bidirectional superseding links so a new decision points at the one it replaces and vice versa, detecting and resolving contradictions between ADRs, deciding when a change is a NEW ADR vs an amendment, and keeping the decision history navigable and trustworthy as append-only. Composes adr-writer for single-record authoring; owns the collection. Use when standing up or curating an ADR log, superseding/deprecating a past decision, reconciling conflicting ADRs, or when the ADR folder has become an unnavigable pile. Do NOT use to author ONE ADR's content (adr-writer), organize the whole docs corpus by type (diataxis-doc-organizer), or design the docs pipeline/toolchain (docs-as-code-architect).

ADR Sequencer

Purpose

A single ADR is a decision written down; a hundred ADRs with no management is a landfill you can't navigate — nobody knows which decisions still hold, two "accepted" records quietly contradict each other, and someone edits a three-year-old ADR in place, destroying the history it existed to preserve. This skill manages the ADR CORPUS over time: the index/log, sequential numbering, the status lifecycle, the bidirectional superseding graph that lets a reader trace how a decision evolved, contradiction detection, and the rule that keeps the record trustworthy — ADRs are append-only history; you supersede, you don't overwrite. It composes adr-writer for authoring any individual record and owns everything about the collection: its order, its status, and its navigability.

Use When

• Use when: standing up an ADR log/index for a project, or curating one that's grown into an unnavigable pile.
• Use when: a past decision is being superseded or deprecated and the old and new ADRs need correct bidirectional links and statuses.
• Use when: two ADRs appear to contradict and the conflict must be surfaced and resolved.
• Use when: deciding whether a change warrants a NEW ADR (a material decision change) or an amendment (a clarification).
• Do NOT use when: the task is authoring ONE ADR's content — context, decision, alternatives, consequences, rollback — that is adr-writer, which this skill composes and does not replace.
• Do NOT use when: the task is organizing the whole documentation corpus by type (tutorials/how-to/reference/explanation) — that is diataxis-doc-organizer.
• Do NOT use when: the task is the docs toolchain/pipeline (generator, build, deploy, CI) — that is docs-as-code-architect.

Inputs to Inspect

1. The existing ADR corpus: how many, their numbers, dates, current statuses, and where they live — plus the gaps (missing numbers, status-less records).
2. The index/log if any: whether a single navigable list of decisions exists, and how stale it is.
3. Superseding relationships already implied: decisions that clearly replace earlier ones but aren't linked, and any in-place edits that overwrote history.
4. Apparent contradictions: pairs of "accepted" ADRs whose decisions can't both hold now.
5. The team's ADR conventions: template in use (so new records match), numbering scheme, and where ADRs are expected to be referenced from (code, docs, PRs).

Workflow

1. Inventory and index. List every ADR with its number, title, date, and current status in a single index/log — the navigable front page of the decision history. Assign missing numbers; give status-less records a status.
2. Apply the status lifecycle. Each ADR is proposed, accepted, rejected, deprecated, or superseded — never ambiguous. A superseded ADR stays in the record (it's history) with its status and a pointer to its successor; it is not deleted.
3. Wire the superseding graph both ways. When a new decision replaces an old one, the NEW ADR names what it supersedes, and the OLD ADR is marked "superseded by ". Bidirectional links let a reader walk the evolution in either direction. Preserve the chain, don't collapse it.
4. Enforce append-only history. A decided ADR is not edited in place to change its decision — that erases the reasoning that was true when it was made. A changed decision is a NEW ADR that supersedes; only typo/clarity fixes amend in place, noted as such.
5. Draw the new-vs-amend line. Material change to the decision or its consequences → new superseding ADR. Clarification, formatting, a fixed link → amendment with a dated note. State which and why.
6. Detect and resolve contradictions. Scan for two current decisions that conflict; surface each pair and resolve it — usually a new ADR that supersedes one or reconciles both — rather than leaving the corpus self-contradictory. Contested FACTS behind a conflict go to source-of-truth-reconciler first.
7. Make it navigable and referenced. Group/tag by area, link related ADRs, and ensure code/docs point at the governing ADR. The log's job is that anyone can find the current decision on a topic and its history.
8. Author via adr-writer. Any individual ADR (new, or the superseding record) is written by adr-writer; this skill places it in the sequence, sets statuses, and wires links. Deliver the corpus plan/index in the Output Format.

The ADR index format, the status lifecycle diagram, superseding-link conventions, and the new-vs-amend decision guide: references/adr-corpus-sheet.md.

Output Format

ADR CORPUS PLAN — <project>
Index:         numbered list — <NNNN | title | date | status | supersedes/superseded-by>
Status pass:   every ADR has a lifecycle status; ambiguous ones resolved
Superseding:   bidirectional links wired (new names old; old → superseded-by new)
Append-only:   history preserved; changed decisions = new superseding ADRs, not in-place edits
New-vs-amend:  <decisions on which changes are new ADRs vs amendments, with reasons>
Contradictions:<conflicting pairs surfaced + resolution (superseding/reconciling ADR)>
Navigation:    grouping/tags; related-ADR links; code/docs → governing ADR
Authoring:     individual records → adr-writer
Boundaries:    corpus-by-type → diataxis-doc-organizer; pipeline → docs-as-code-architect

Validation Checklist

• A single index/log lists every ADR with number, title, date, and status.
• Every ADR has a lifecycle status; none is ambiguous.
• Superseding links are bidirectional (new names old; old points to its successor).
• History is append-only — no decided ADR was edited in place to change its decision; changes are new superseding records.
• The new-ADR-vs-amendment line is applied with stated reasons.
• Contradictions between current ADRs are surfaced and resolved, not left silent.
• The corpus is navigable and code/docs reference the governing ADR.
• Individual-record authoring is delegated to adr-writer, not duplicated here.

Gotchas

• Editing a decided ADR in place to "update" it destroys the very thing an ADR is for: the reasoning that was true at decision time. Supersede with a new record; never overwrite history.
• An ADR folder with no index is write-only memory — decisions go in and are never found again. The log is what makes the corpus usable.
• Superseding links that only point forward (or only back) leave readers stranded: from an old ADR they can't find what replaced it. Wire both directions.
• Two "accepted" ADRs that contradict each other are worse than no ADRs — they give false confidence in opposite directions. Detecting these is a primary job, not a nicety.
• Deleting a superseded ADR erases the trail. A superseded decision is still history; mark it, don't remove it.
• Confusing amendment with supersession blurs the record: a material decision change hidden as an "amendment" makes the history lie. Keep the line sharp.
• This skill doesn't rewrite adr-writer. Re-authoring single-ADR content here duplicates a neighbor; compose it.

Stop Conditions

• The task is authoring ONE ADR's content (context/decision/alternatives/ consequences/rollback) → route to adr-writer; this skill sequences and manages, it doesn't re-implement single-record authoring.
• A contradiction between ADRs rests on a contested FACT (which config/ number/state is actually current) → route to source-of-truth-reconciler before writing a resolving ADR.
• Resolving a contradiction requires MAKING a new architecture decision (not just recording sequence) → the decision itself is architecture-designer's; this skill wires the resulting ADR into the corpus once decided.
• The task is corpus-by-type organization or the docs pipeline → route to diataxis-doc-organizer or docs-as-code-architect.

Supporting Files

• references/adr-corpus-sheet.md — the ADR index format, the status lifecycle, superseding-link conventions, the new-vs-amend decision guide, and a contradiction-scan checklist.
• evals/evals.json — behavior cases including the supersede-not-overwrite discipline, the contradiction resolution, and the new-vs-amend call.
• evals/trigger-evals.json — discrimination against adr-writer (single vs corpus — the compose seam), diataxis-doc-organizer, and docs-as-code-architect.