skills.rest
azborgonovo
azborgonovoCOMMUNITY
Explore all skills by this author →
Website𝕏@azborgonovoGitHub

backfill-decisions

Mines git history to reconstruct retroactive Architecture Decision Records for past decisions.

Updated Apr 12, 2026
Search Tags:#architecture#documentation#adr#legacy code#git history#decision records#mining
One-click install
npx skills add https://github.com/azborgonovo/ai-skills --skill backfill-decisions-azborgonovo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: backfill-decisions
Source: https://github.com/azborgonovo/ai-skills/tree/main/skills/decisions/backfill-decisions
Command: npx skills add https://github.com/azborgonovo/ai-skills --skill backfill-decisions-azborgonovo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Legacy and long-lived repositories contain architecturally significant decisions that were never documented, leaving teams without the reasoning behind technology choices, infrastructure changes, and structural reshaping. ## Core Features & Use Cases - Git history mining: Sweeps commit messages, merge titles, dependency manifests, infrastructure files, and structural snapshots to detect architecturally significant changes. - Evidence-based triage: Clusters related commits into candidate decisions with confidence levels, detects reversals and superseded choices, and deduplicates against existing Decision Records. - Retroactive DR writing: Generates Decision Records following the log-decision conventions, with honest provenance notes, commit evidence links, and correct historical dates and authors. - Use Case: Point it at a five-year-old codebase with no ADR folder, and it will propose documented records for events like the migration from RabbitMQ to SQS or the adoption of a new framework, which you confirm before anything is written. ## Quick Start Run /backfill-decisions with an optional time range, path, or topic such as "2023..2024" or "database" to mine the repository history and generate Decision Records for confirmed past decisions.

Frequently Asked Questions about backfill-decisions

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

FAQPage Schema
How do I generate ADRs for an existing codebase?▼

Run /backfill-decisions to mine the git history for significant decisions such as dependency adoptions, infrastructure additions, and structural changes. It triages candidates with you, then writes Decision Records only for the ones you confirm.

How to document architectural decisions from git history?▼

The skill sweeps commit subjects, merge titles, dependency manifests, infra file additions, and top-level directory changes to cluster evidence into candidate decisions. Each written DR cites the evidence commits and is marked as a retroactive reconstruction.

Does backfill-decisions work with a shallow git clone?▼

It detects shallow clones with git rev-parse --is-shallow-repository and warns that truncated history will miss most decisions. It suggests running git fetch --unshallow before continuing.

When should I use log-decision instead of backfill-decisions?▼

Use log-decision for a decision being taken right now, while the reasoning is fresh. Use backfill-decisions only for decisions already made and buried in the repository's past.

Does backfill-decisions modify my git repository?▼

All git usage is read-only; it never commits, checks out, or mutates the repository. The only writes are the new Decision Record markdown files in the decisions directory.

What are the limitations of reconstructing ADRs from git history?▼

History cannot reveal consulted or informed stakeholders, and rejected alternatives are only visible when something was removed or replaced. Candidates without an observable trade-off are downgraded in confidence, and every claim must trace to a commit.

Related Skills

Explore More Software Engineering Skills→
daidrdaidr
8

commit

Generates conventional git commit messages from current repository changes.

Community
Basic
faustellar1995faustellar1995
1

decision-capture

Detect and record decisions from conversation logs with YAML frontmatter.

Community
Intermediate
MaelwalserMaelwalser

architecture-decision-records

Capture architectural decisions as formatted ADR documents during coding sessions.

Community
Advanced
psw7205psw7205
1

trace-change-why

Traces the rationale behind code changes from session transcripts and git history.

Community
Intermediate