adr-backfill

What this skill does

# 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: "<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

| 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 re