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.