Adr Backfill

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.

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

---
title: "<imperative verb phrase>"
status: accepted                   # or deprecated if reversed; keep status ADR Explorer-compatible
date: <original decision date if known, else first-evidence date in ISO 8601>
backfilled-on: YYYY-MM-DD          # today
deciders:
  - <named human, or unrecoverable>
evidence:                          # at least two locators
  - <commit SHA / file path / manifest line>
  - <commit SHA / file path / manifest line>
reconstruction-confidence: high | medium
asr-characteristic: <latency | cost | availability | security | maintainability | operability | portability | ...>
asr-signal: "<measurable signal -- e.g., removed 14k LOC and one vendor dependency>"
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

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

The backfill honesty clause — canonical spec

The single source of truth for the mandatory honesty clause that every backfill ADR must contain. adr-backfill writes the clause during Phase 3; adr-critique audits records that should have one. Both skills point here rather than restating the clause. Update this file when the form changes; do not duplicate.

Why this clause exists

A backfill ADR is, by construction, written after the fact. Without an explicit mark, a future reader cannot distinguish a reconstructed rationale from a contemporaneous record — and silently treating reconstruction as recording poisons the decision log. The clause is the load-bearing honesty marker. Removing or softening it is a refusal trigger for adr-backfill and a flag for adr-critique.

Required form (verbatim)

The clause appears near the top of the ADR body, after the title and before Context. The literal form:

**Backfill notice.** Recorded YYYY-MM-DD from <evidence locators>; original decider <named human(s) or "unrecoverable">. Alternatives could not be reconstructed at backfill time<, except <list> if partially recoverable>.

Required fields

Three are mandatory, one is conditional.

Terminal punctuation (non-negotiable)

The clause ends with a literal period (.). The two valid terminations are:

• No reconstructible alternatives — ends with ... at backfill time.
• Partially reconstructible alternatives — ends with ... at backfill time, except <list>.

A clause that elides the terminal period (ends with at backfill time with no period, or trails into the next sentence without one) is non-compliant. adr-critique flags missing terminal punctuation. The period is part of the verbatim form, not a stylistic suggestion.

Refusal: when the user wants the clause removed or softened

The clause is the single non-negotiable element of a backfill ADR. If the user asks to remove it, soften it, paraphrase it into past-tense narrative, hide it in a footnote, or elide any required field, refuse. The reason: a backfill without the clause looks indistinguishable from a contemporaneous record, and a future reader has no way to tell the rationale was reconstructed rather than recorded in the moment.

adr-critique enforces this independently. A record whose tags: contains backfill or whose frontmatter has backfilled-on but whose body lacks a compliant clause is a flag in the audit checklist. Older records that encode backfill text in status should be migrated to ADR Explorer-compatible status: accepted or status: deprecated without softening this clause. The audit routes back to adr-backfill for a redraft rather than patching the file in place.

Where this clause is referenced

• skills/adr-backfill/SKILL.md Phase 3 — drafts the clause during backfill.
• skills/adr-critique/references/audit-checklist.md "Backfill ADRs" section — audits for the clause's presence, completeness, terminal punctuation, and softening.

These are the only two call sites by design. Adding a third would re-introduce the duplication this file exists to eliminate.