adr-generator

Run the adr-generator skill on your repository; it analyzes commits, clusters related changes into decision candidates, classifies them by diff signals, and writes MADR files to docs/decisions/. Use quick mode for repos under ~500 commits or autonomous mode for larger histories.

MADR (Markdown Architectural Decision Records) is a lightweight template with sections for Status, Context, Considered Options, and Decision Outcome. This skill generates MADR files with a retroactive notice, evidence citations, and links back to the original commits.

Yes, it auto-detects merge commits, squash merges (via (#NNN) subject patterns), and linear rebase histories, choosing a chunking strategy per workflow. For rebase repos it groups by file-path affinity only, since rebasing destroys original timestamps.

A shallow clone has incomplete history, so retroactively generated ADRs would be misleading. The skill halts and instructs you to run git fetch --unshallow before proceeding, except in assisted mode where you can accept incomplete output.

Every Considered Option must carry an inline evidence citation (commit SHA plus a deleted/added/renamed file, removed line, or message phrase). The judge.py verifier checks each citation against git deterministically and drops any option that cannot be pinned to actual bytes.

Avoid it on repos with uninformative commit messages like "fix" or "wip", shallow clones, or codebases where decision context lives only in external tools like Confluence. Output quality scales directly with commit message discipline.