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.
adr-backfill records architectural decisions made in the past but never documented, with mandatory honesty marking.
AI-generated summary based on this skill's SKILL.md
Install
JosiahSiegel/claude-plugin-marketplace/adr-backfill · repository language: Shell
git clone https://github.com/JosiahSiegel/claude-plugin-marketplace
cp -r claude-plugin-marketplace/plugins/doc-master/skills/adr-backfill ~/.claude/skills/adr-backfillnpx skillfed install JosiahSiegel/claude-plugin-marketplace/adr-backfillFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I document a decision we made years ago?
adr-backfill helps you record architectural decisions that shipped long ago but were never written as ADRs. Start by gathering two independent evidence sources—code diffs, commit messages, issue threads, design docs, or team recollections—to reconstruct the rationale. adr-backfill then guides you through drafting the ADR with a visible backfill marker so readers know the record was reconstructed after the fact, not written contemporaneously.
What makes adr-backfill different from writing a normal ADR?
adr-backfill enforces stricter honesty than forward drafting. It requires a visible backfill marker in the ADR to signal that the record was reconstructed, not contemporaneous. It also demands two independent evidence sources before proceeding and refuses to draft when confidence in the original reasoning is too low. This prevents false certainty about decisions made long ago.
Can adr-backfill help when an audit found undocumented architectural decisions?
Yes. adr-backfill is designed for exactly this scenario. When a documentation audit surfaces undocumented decisions, adr-backfill helps you backfill the missing ADRs by reconstructing the decision rationale from available evidence—code history, git logs, and team memory—while marking each record as backfilled so future readers understand its provenance.
How does adr-backfill handle low confidence in original intent?
adr-backfill refuses to draft when confidence in the reasoning is too low. If you cannot gather two independent evidence sources or the rationale remains unclear, adr-backfill will not proceed. This prevents you from inventing plausible-sounding justifications for decisions you no longer fully understand, keeping your decision record honest.
Can I use adr-backfill to document a decision before my time?
adr-backfill can help, but with caveats. It requires two independent evidence sources—code diffs, commit messages, design artifacts, or documented team discussions—to reconstruct the rationale. If those sources exist, adr-backfill guides you through drafting with a backfill marker. If evidence is sparse or contradictory, adr-backfill will decline rather than let you guess.
What does the backfill marker in an adr-backfill ADR tell readers?
The backfill marker signals that the ADR was written after the decision shipped—it was reconstructed, not drafted contemporaneously. This transparency helps future readers understand that the rationale may be incomplete or inferred from code and history rather than direct decision-making notes. It preserves trust in your decision record by being honest about its origins.
SKILL.md
rendered from the published skill — quoted content, verbatim
adr-backfill
Retroactively records a past architectural decision that was made but never documented. Surfaces typically come from
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 2 files
plugins/doc-master/skills/adr-backfill/SKILL.md
plugins/doc-master/skills/adr-backfill/references/honesty-clause.md