Objective

Reconstruct Architecture Decision Records from a repository's git history and documentation. You're doing archaeology — finding the decisions buried in commits, specs, and docs, then surfacing them as ADRs.

An ADR is warranted when someone made a choice that shaped the system. Not every commit is a decision. Your job is to find the ones that were.

Process

1. Classify files — Distinguish architectural files (where decisions manifest) from supportive files (tests, utils). Persist this classification.

2. Identify candidate commits — Find commits that touch architectural files with structural changes (not just edits).

3. Cluster into decisions — Group related commits that represent a single decision being implemented.

4. Fill gaps — Pull in minor commits (typo fixes, forgotten files) that belong to a cluster but were filtered out.

5. For each cluster — Analyze intent, ask the user for context, generate the ADR.

6. Scan complementary sources — Check specs/ and docs/ for decisions not captured by commits.