--- id: JosiahSiegel/claude-plugin-marketplace/adr-backfill version: "3cd6ebe2" license: MIT install: manual updated: 2026-06-18 --- # adr-backfill — adr-backfill lets you record decisions that shipped long ago but were never written up as ADRs—typically surfaced by doc audits or code archaeology. It enforces stricter honesty than forward drafting by requiring a visible backfill marker so future readers know the record was reconstructed, not contemporaneous. The skill demands two independent evidence sources and refuses to draft when confidence in the reasoning is too low. Publisher: JosiahSiegel · Stars: 49 · Updated: 2026-06-18 Install (manual): `git clone https://github.com/JosiahSiegel/claude-plugin-marketplace` ## SKILL.md # adr-backfill Retroactively records a past architectural decision that was made but never documented. Surfaces typically come from `/doc-audit` `BACKFILL-ADR` rows or from a user who realises a past change should have been an ADR. Operates with relaxed gates relative to `adr-drafting` (the decider may be unrecoverable, alternatives may not be reconstructible) but enforces stricter honesty: a backfill ADR must visibly mark itself as a backfill so future readers do not mistake it for a contemporaneous record. ## When to use this skill - `/doc-audit` surfaced a `BACKFILL-ADR` candidate row and the user wants to record it. - The user describes a decision in past tense — *"we decided years ago,"* *"back when,"* *"before my time,"* *"we never wrote it down"* — about a change whose effects are visible in the codebase today. - A code-archaeology session uncovered a migration, vendor removal, or subsystem retirement with no corresponding decision record. ## When NOT to use this skill - The decision is current or in-flight — use `adr-drafting` instead. - The decision is already recorded in any form — use `adr-critique` to tighten the existing record. - `reconstruction-confidence` is `low` (only the *what* is recoverable, not the *why*) — refuse to draft and route to `open-questions.md`. - The change is not architecturally significant — see `_shared/adr-is-backfillable.md` § 2. Route via the alternatives catalog in `doc-diagnostic`. ## Inputs - **Required:** at least two independent evidence locators (see `_shared/adr-is-backfillable.md` § 3). Examples: commit SHA + migration file, migration file + removed manifest entry, removed module + retired feature-flag commit. - **Required:** a measurable signal for the architectural characteristic affected (see `_shared/adr-is-backfillable.md` § 4). - **Optional:** a `BACKFILL-ADR` row from `/doc-audit` containing the proposed `decision`, `evidence-locator`, `ASR-test-result`, `reconstruction-confidence`, and `suggested-status` fields. If present, use it as the starting brief. ## Refusal behaviors The skill **refuses to draft** when: - The eligibility self-check in `_shared/adr-is-backfillable.md` fails any of items 1-3 or 5 (no evidence, no ASR significance, single-locator evidence, or already recorded). - `reconstruction-confidence` is `low` — the *why* would have to be fabricated. Route to `open-questions.md`. - No measurable signal can be named for the architectural characteristic affected. - The user wants the backfill ADR to look like a contemporaneous record (no honesty clause). The clause is non-negotiable. ## Core operating rule **Never emit more than one question or one step per message.** Inherits the one-question-per-turn discipline from `adr-drafting`. Backfill is at least as easy to over-stuff as forward drafting; tighter discipline, not looser. ## The four phases ### Phase 1 — Eligibility and evidence Run the seven-item eligibility self-check from `_shared/adr-is-backfillable.md` against the candidate. Walk it one item at a time. If any item fails, stop: - Items 1-3 or 5 failing → refuse to draft, explain which evidence is missing. - Item 4 failing (no measurable signal) → drop to `open-questions.md`. - Item 6 failing (confidence `low`) → drop to `open-questions.md` with the evidence that would upgrade it. - Item 7 failing (decider not nameable and not yet marked `unrecoverable`) → ask once whether to use the `unrecoverable` marker or to keep digging. Confirm the two-locator evidence in dialogue — quote the locators back to the user so they can correct a mistaken artifact. Do not proceed to Phase 2 until the user agrees the evidence is right. ### Phase 2 — Historical context reconstruction (best effort) For each section of the ADR, gather what can be reconstructed and **mark gaps explicitly** rather than papering over them. | Section | Reconstruction approach | |---|---| | Context (the forces) | Read commit messages, PR descriptions, ticket links, removed README content, retired runbooks. Cite each source. If the forces cannot be reconstructed, write *"Forces at the time of the decision could not be reconstructed from available evidence."* — do not invent. | | Decision | The *what* — almost always reconstructible from the shipped change. Stated in present-tense active voice, same as a forward ADR. | | Alternatives | Often the hardest to recover. If the original alternatives are visible in PR review comments, commit history, or contemporary RFCs, cite them. If not, the honesty clause covers the gap. | | Consequences (Good / Bad) | Reconstruct from observable effects in the codebase today. *"Removed 14k LOC"* is observable; *"Improved developer morale"* is not. | | Decider | Named human(s) from commit author / PR reviewer / explicit attribution, OR the literal token `unrecoverable`. Never fabricate. | ### Phase 3 — Draft with honesty clause (MANDATORY) Every backfill ADR must contain a verbatim honesty clause near the top of the body (after the title, before Context). The verbatim form, required fields, terminal punctuation, and refusal conditions live in `references/honesty-clause.md` — read it before drafting. The clause exists so a future reader cannot mistake the backfill for a contemporaneous record. Removing or softening it is a critique-flag (see `adr-critique` audit checklist). ### Phase 4 — Save Same save discipline as `adr-drafting`: 1. Glob ADR Explorer-friendly directories first (`docs/adr/`, `docs/decisions/`, `docs/architecture/decisions/`, `**/adr/*.md`); also check legacy `architecture/decisions/` but warn it may need custom ADR Explorer root configuration. Use the first existing directory; if none, create `docs/adr/`. 2. Auto-number: read existing ADRs, take `max+1`, zero-pad to 4 digits. **The backfill ADR takes the next available number, not a number from the past.** Numbering reflects creation order, not decision order. The original decision date appears inside the file (see frontmatter); the number is just-now. 3. Filename: `NNNN-kebab-imperative-title.md`. 4. Write the file with the honesty clause and the backfill-specific frontmatter (see template below). 5. Update the decision-log `README.md` index, marking the row with `(backfilled YYYY-MM-DD)`. ## Backfill-specific frontmatter ```yaml --- title: "" status: accepted # or deprecated if reversed; keep status ADR Explorer-compatible date: backfilled-on: YYYY-MM-DD # today deciders: - evidence: # at least two locators - - reconstruction-confidence: high | medium asr-characteristic: asr-signal: "" tags: [backfill] --- ``` If the decision has since been reversed by a later shipped change, set `status: deprecated` and cite the reversing commit / migration in `evidence:` plus the honesty clause or notes. The backfill still gets recorded — the historical decision matters even after reversal — but the status remains ADR Explorer-compatible. ## Status conventions | Status | Use when… | |---|---| | `accepted` | The decision is still in force today. Default. | | `deprecated` | A later shipped change undid the original decision. Cite the reversing evidence. | Backfill ADRs never use `proposed` or `rfc` — a backfill is, by definition, a recording of a decision that was already shipped. Keep backfill identity in `tags: [backfill]`, `backfilled-on`, evidence fields, and the mandatory honesty clause; do not encode it in `status`. ## Refusal: when the user wants the honesty clause removed The honesty clause is the single non-negotiable element of a backfill ADR. If the user asks to remove it, soften it, or hide it in a footnote, refuse. Explain that a backfill without the clause looks like a contemporaneous record and silently poisons the decision log — a future reader has no way to tell the rationale was reconstructed rather than recorded in the moment. The clause stays in the body. `adr-critique` enforces this independently: a record with `tags: [backfill]` or `backfilled-on` whose body lacks the honesty clause is a flag in the audit checklist. ## Hand-off `adr-backfill` does **not** chain automatically to other skills. After the backfill record is saved, the user may choose to: - Run `adr-critique` against the new record to tighten language (especially if `reconstruction-confidence` was `medium`). - Run `c4-model` to add a Context / Container view that reflects the post-decision system shape (optional). - Update `open-questions.md` to close out any locked questions the backfill resolved. None of these are forced. Soft hand-off via skill triggers only. ## References - `references/honesty-clause.md` — the canonical spec for the Phase 3 honesty clause (form, required fields, terminal punctuation, refusal conditions). Single source of truth; `adr-critique` reads the same file. - `../_shared/adr-is-backfillable.md` — the seven-item eligibility self-check (used in Phase 1) - `../_shared/adr-is-not.md` — applies to backfill ADRs the same as forward ADRs (no tutorial, no implementation guide, no marketing, no hedging, no long-form padding) - `../doc-diagnostic/references/audit-procedure.md` — defines the `BACKFILL-ADR` row schema that feeds this skill - `adr-drafting` skill — the forward-drafting counterpart for in-the-moment decisions - `adr-critique` skill — for tightening the saved backfill record afterwards - `doc-diagnostic` skill — for the ASR definition and the alternatives catalog [View on SkillFed](https://skillfed.io/JosiahSiegel/claude-plugin-marketplace/adr-backfill) · [View on GitHub](https://github.com/JosiahSiegel/claude-plugin-marketplace)