adr-backfill

Reconstruct MADR-formatted Architecture Decision Records from commits and documentation.

346|50|Updated Jan 17, 2026
One-click install
npx skills add https://github.com/liza-mas/liza --skill adr-backfill-liza-mas
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: adr-backfill
Source: https://github.com/liza-mas/liza/tree/main/skills/adr-backfill
Command: npx skills add https://github.com/liza-mas/liza --skill adr-backfill-liza-mas

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Backfill Architecture Decision Records (ADRs) from commit history and documentation, enabling teams to recover rationale after it was decided but not recorded.

Core Features & Use Cases

  • Cluster related commits, specs, and docs into single ADRs representing a decision.
  • Scan specs/docs for supplementary decisions not captured by commits.
  • Generate MADR-formatted ADR files under specs/architecture/ADR with cross-references and implementation notes.
  • Persist state to allow resuming work across sessions.

Quick Start

Run the adr-backfill skill on this repository to start reconstructing ADRs from history and docs. The tool will classify files, form clusters, and output new ADRs under specs/architecture/ADR.

Frequently Asked Questions about adr-backfill

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate Architecture Decision Records from git history?

Generate Architecture Decision Records from commit history by analyzing historical changes, specs, and docs to cluster related commits into decisions and outputting MADR-formatted ADR files.

What is the best way to document architecture decisions that were made but never recorded?

Document unrecorded architecture decisions by backfilling ADRs from existing commits and documentation, reconstructing the rationale and context to recover lost decision history.

Can I resume ADR backfilling across sessions if the process is interrupted?

Resume ADR backfilling across interrupted sessions using a stateful workflow that persists classification, clustering, and chronological reordering progress to maintain a continuous audit trail.

How does clustering related commits work when reconstructing architecture decisions?

Clustering related commits analyzes historical changes, specs, and docs to group associated modifications into a single Architecture Decision Record, ensuring coherent documentation of each decision.

Does adr-backfill scan existing documentation for supplementary decisions not captured in commits?

adr-backfill scans specs and docs to identify supplementary architecture decisions not captured by commits, enriching the generated MADR files with cross-references and implementation notes.

What format is used for the output files when backfilling architecture decisions?

Backfilled architecture decisions are generated as MADR-formatted ADR files, placed under the specs/architecture/ADR directory to ensure standardized documentation and cross-referencing.