| name | decision-inference |
| description | Use when inferring a codebase's design choices for the explore report: the archaeological-ADR card schema, the evidence-source hierarchy, the confidence ladder, and the rules that keep inferred decisions honest (no evidence-free claims, no strawman alternatives, consequences phrased as editing advice). |
Inferring design choices
The design-choices section is the report's product: why the code is this way and what that costs you. Each choice is an ADR written backwards, recovered from the artifact instead of authored before it.
Card schema (fixed)
Choice : "X over Y", named concretely ("SQLite over Postgres", not "a database")
Displaced alternative : the realistic option this beat, and why it plausibly lost
Evidence : file paths / commit SHAs / config lines; at least one, ideally two kinds
Consequence when editing : what the choice forces on someone changing the code TODAY
Confidence : documented | historical | inferred
Where evidence lives (in order of strength)
- The repo's own words: ADRs, design docs, README rationale sections, load-bearing comments ("we tried X, it deadlocked"). →
documented
- Git history: commit messages around large refactors; dependency swaps visible in lockfile/manifest diffs; deleted directories (
git log --diff-filter=D --summary); the first commit's shape vs today's. → historical
- Code shape: a hand-rolled thing where a library is standard (deliberate or ignorance?); an abstraction layer with exactly one implementation (anticipated portability); conspicuous absences (no ORM, no DI framework, no async). →
inferred
What makes a choice worth a card
Ask: would knowing this change how someone edits the code? Good cards: concurrency model, persistence boundary, error-handling strategy, the build system's one weird requirement, why the public API is shaped this way, a framework migration half-completed. Not cards: "uses Python", "has tests", "follows PEP 8" (properties, not choices).
Prefer choices where the alternative was live: something a competent team would actually have weighed. If you cannot name a realistic displaced alternative, it is probably not a decision; demote it to the architecture prose or cut it.
Honesty rules
- No evidence, no card. Cut, don't hedge.
- Never upgrade confidence. Plausible ≠ historical. If the only basis is code shape, the label is
inferred even when you're nearly sure.
- No strawmen. "They chose X over doing nothing" is not an alternative.
- Consequences are editing advice, present tense: "no concurrent writers, keep writes on one thread", not "this may have performance implications."
- 5–10 cards. If you found fifteen, the weakest five weren't decisions.
Related: [[explore-report]].
