adr-backfill

Reconstructs Architecture Decision Records from git history and documentation into MADR-formatted ADRs.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill reconstructs Architecture Decision Records from a repository's git history and documentation, surfacing the decisions that shaped the system which may be buried in commits, specs, or docs.

Core Features & Use Cases

  • Commit-based ADR backfill: Identify, cluster, and document architectural decisions from commit history that touched core modules, deployments, or interfaces.
  • Spec/doc-driven enrichment: Surface ADRs described in specs/docs not captured by commits and cross-reference related decisions.
  • Provenance and ordering: Maintain sources, dates, and anchors to support chronological ordering and traceability.

Quick Start

Run an initial scan of the repository to collect commits, specs, and docs. Review the generated MADR drafts under specs/architecture/ADR and refine clusters as needed, then commit the results to the repository.

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 existing git history?

To generate Architecture Decision Records from git history, this Skill analyzes your commits to identify changes that touched core modules or interfaces, clustering related commits into MADR-formatted drafts. The output is saved under specs/architecture/ADR with provenance metadata for traceability.

What is the best way to backfill missing ADRs from project documentation?

Backfilling missing ADRs from project documentation involves cross-referencing specs and docs with commit history to surface undocumented decisions. This Skill extracts architectural decisions buried in documentation and outputs MADR-formatted records with source anchors and chronological ordering.

Can I reconstruct architectural decisions if my repository has no existing ADRs?

Yes, you can reconstruct architectural decisions without any existing ADRs. This Skill scans your repository's commit history and documentation to identify buried decisions, clustering related changes into MADR-formatted drafts that you can review through an interactive enrichment workflow.

Does this ADR reconstruction tool output MADR formatted files?

Yes, this ADR reconstruction tool outputs MADR-formatted files. It analyzes your repository's commits and documentation to generate Architecture Decision Records saved under specs/architecture/ADR, complete with provenance metadata linking back to the original source materials.

How do I cluster related architectural changes scattered across multiple commits?

To cluster related architectural changes scattered across multiple commits, this Skill analyzes commit history touching core modules, deployments, or interfaces. It groups related changes together and generates MADR drafts, allowing you to refine the clusters through an interactive enrichment workflow.

What are the limitations of automatically generating ADRs from git history?

Automatically generating ADRs from git history relies on the quality of commit messages and documentation, meaning decisions lacking clear commit anchors may require manual enrichment. The generated MADR drafts under specs/architecture/ADR are starting points that benefit from an interactive review workflow to ensure accuracy.