Retrospective ADR Template — Writing Decision Records for Pre-Adoption Architecture Choices

What a retrospective ADR is

A retrospective ADR documents a decision that was made in the past — before the team adopted an ADR practice, before anyone knew it mattered, or simply before anyone wrote it down. It is not a post-mortem or a post-decision review — those analyze whether the decision was correct. A retrospective ADR makes a different and narrower claim: "this decision was made, here is what was decided, here is what context we can recover about why, and here is the evidence quality for this reconstruction."

Retrospective ADRs differ from contemporaneous ADRs in three important ways:

• The Alternatives Considered section has a quality ceiling. The clearest value of an ADR is documenting which alternatives were genuinely compared and why they were rejected. For a retrospective ADR, this is often the hardest section to reconstruct — the rejected alternatives were discussed in a meeting, in Slack, or in someone's head, and those are the least durable artifacts. A contemporaneous ADR captures alternatives while the comparison is live; a retrospective ADR reconstructs them from whatever evidence remains.
• The date fields carry more weight. A contemporaneous ADR's date field is the date the PR was opened. A retrospective ADR needs to distinguish between the decision date (best estimate of when the choice was actually made) and the commit date (when the ADR was written and merged). These can be years apart, and the distinction matters for understanding the decision's context.
• The confidence must be explicit. Future readers need to know whether the ADR is a contemporaneous record or a reconstruction — they'll weight the Alternatives Considered section differently if they know it's one person's 3-year-old memory versus an AI chat session from the week of the decision. The retrospective-confidence field makes this explicit rather than leaving readers to guess.

The retrospective ADR backlog problem

Teams that start an ADR practice face a natural temptation: backfill everything. Document the last 3 years of architecture decisions, catch up to some imagined complete state, then maintain going forward. This approach fails for two reasons:

1. The opportunity cost is enormous. Writing a retrospective ADR for a 3-year-old decision that has already been revisited and superseded produces a document that nobody will read. The engineering time spent on it is worse than zero — it fills the ADR corpus with low-signal entries that make the high-value entries harder to find.
2. The quality ceiling means some decisions can't be reconstructed well enough to be useful. A retrospective ADR for a decision made 4 years ago by engineers who have left the company, with no AI chat sessions or PR discussions as source material, will produce an ADR that invents more than it records. These ADRs are actively misleading — they look authoritative but are mostly reconstruction rationalization.

The right approach is triage, not backfill. Write retrospective ADRs for the decisions that actively confuse current engineers or will confuse future engineers — not for historical completeness. Start with the decisions a new team member asks about in their first month.

Identifying backlog priority

Three signals indicate a retrospective ADR is worth writing:

• The question gets asked more than once. If two different engineers have asked "why are we using X instead of Y?" in the last 6 months, the answer belongs in an ADR, not in repeated Slack threads.
• The decision still has active consequences. A 3-year-old decision that currently constrains every new service (e.g. ORM choice, authentication pattern, data model convention) is more valuable to document than a 6-month-old decision that was already revisited. The age of the decision is irrelevant; the current-impact is what matters.
• The absence of an ADR is causing re-litigation. When team members are debating a decision that was already made — because nobody knows it was made — the most efficient thing to do is write the retrospective ADR and point to it. The ADR closes the debate by establishing that the decision has already been made and documenting the reasoning, rather than having the same conversation repeatedly.

Four source-material tiers

The quality of a retrospective ADR is bounded by the quality of the available source material. Before starting a retrospective ADR, identify which tier of source material you have — it determines the retrospective-confidence value and shapes how much of the template you can fill with confidence.

Tier 1: AI chat session from around the decision period (best)

For decisions made after 2022, an AI chat session (ChatGPT or Claude) from around the time of the decision is typically the richest available source. Engineers increasingly use AI chat to think through architecture decisions: "we're choosing between Postgres and MongoDB for our user data model — here are our constraints, what should we consider?" These sessions contain the explicit comparison the ADR needs: alternatives stated with their specific tradeoffs, constraints articulated, objections raised and addressed. The session often reads like a structured deliberation — which is exactly what it was.

The AI chat session doesn't just provide raw material for the ADR; it often contains the exact Alternatives Considered rows: "MongoDB would give you schema flexibility but you'd lose the relational joins your reporting queries require — here's why that matters for your specific access pattern." The constraint that drove the decision is named explicitly, which is precisely the Context section content. The WhyChose extractor processes your ChatGPT or Claude export and surfaces these sessions, ranking them by how many decision-relevant comparisons they contain. A session that explicitly weighs two database options against several constraints produces 3–5 ADR-quality records automatically.

To access this source material: export your ChatGPT history (Settings → Data Controls → Export) or your Claude conversations (Settings → Data Controls → Export), then run the extractor or browse the JSON directly with jq. The search path: filter by date range around the decision, look for conversations with explicit "we should use X because" or "the problem with Y is" language. Set retrospective-confidence: high when writing from a rich AI session — the source material quality is equivalent to a contemporaneous RFC.

Tier 2: PR description and code review comments

A well-written PR description for the change that implemented the decision often contains the decision reasoning — especially for senior engineers who write PR descriptions as a form of documentation. The PR description may not be in the ADR format, but it typically contains the Context section material (what problem this solves), the Decision statement (what was done and why), and sometimes the Alternatives Considered (why this approach over others). Code review comments add additional constraint discussion: reviewers who raised concerns, objections that were accepted and led to changes, and the outcome of those discussions.

Search git history for the commit that introduced the technology or architectural pattern, find the originating PR, and read the full description and review thread. git log --all --oneline -- path/to/affected/file often surfaces the introducing commit quickly. Set retrospective-confidence: medium when writing primarily from PR history — you have the decision but the Alternatives section is typically thinner than what an AI chat session would provide.

Tier 3: Slack threads, meeting notes, or email

Decision discussions that happened in Slack, meeting notes, or email provide context for the decision but typically in unstructured conversational form. Slack threads preserve the reasoning if you export them (see the Slack decision-capture guide for export paths by plan tier), but the structure is conversational rather than architectural — there is no explicit Alternatives Considered section, and the decision rationale is often distributed across multiple messages in a way that requires editorial synthesis. Meeting notes are similar: they record what was discussed but don't produce the clean decision summary the ADR requires.

Set retrospective-confidence: low when writing from Slack or meeting notes. The Alternatives Considered section will be thin — include only alternatives you can verify were genuinely discussed, not ones you're adding for completeness. A sparse but honest Alternatives section is more trustworthy than a full one that was partly invented.

Tier 4: Memory only (worst)

When no written source material is available, the retrospective ADR is constrained to what one or more participants remember. Memory of the Decision section (what was decided) is typically reliable even years later — people remember what was chosen. Memory of the Context section (what constraints drove the choice) degrades over 6–18 months into a simplified narrative that feels coherent but omits the specific technical constraints that made the decision necessary. Memory of the Alternatives Considered section is the least reliable — people remember that alternatives were discussed but typically conflate the alternatives considered with the alternatives that exist, which produces an ADR Alternatives section that lists the obvious alternatives rather than the ones that were actually evaluated.

Set retrospective-confidence: low and leave Alternatives Considered either empty (with a note: "Alternatives considered at the time are not reconstructable from available sources") or note only the alternatives you are certain were genuinely evaluated. Do not fabricate Alternatives Considered rows to make the ADR look complete — it undermines the trustworthiness of the rest of the record. The Decision and Context sections from memory are usually the most useful parts of a Tier 4 retrospective ADR; they may be enough to stop the repeated "why did we choose X?" question even without a full Alternatives section.

The retrospective-confidence field

The retrospective-confidence frontmatter field signals to future readers how much of the ADR was recorded at decision time vs reconstructed after the fact. It is not a quality judgment — a retrospective-confidence: low ADR can still be more valuable than no ADR. It is a provenance signal that helps readers calibrate how much weight to give the Alternatives Considered section and whether to investigate further before relying on the record.

The three values:

• retrospective-confidence: high — The ADR is written from a primary source that was produced at or near decision time (Tier 1 or Tier 2 source material). The Alternatives Considered section reflects what was genuinely compared. Readers can treat this ADR as equivalent to a contemporaneous record in terms of evidential quality.
• retrospective-confidence: medium — The ADR is written from partial primary sources (a PR description, code review comments, or a partial AI session). The Decision and Context sections are reliable; the Alternatives Considered section may be incomplete. Readers should check cited sources (linked PR, linked commit) before making decisions that depend on the Alternatives reasoning.
• retrospective-confidence: low — The ADR is written primarily from memory, secondhand accounts, or very incomplete primary sources. The Decision section is likely accurate; the Context and Alternatives sections should be treated as best-effort reconstruction. Readers should not rely on the Alternatives Considered section as a complete record of what was evaluated.

Always add a reconstructed-by field alongside retrospective-confidence — the person who wrote the ADR, even if they weren't present at the decision. This creates accountability for the reconstruction quality and identifies who to ask if the provenance is questioned.

Retrospective ADR template

Copy-paste the following template and fill in what you can from your available source material. Leave sections you cannot fill honestly rather than fabricating content.

# ADR-0043 — Use Postgres as the primary data store

**Status:** Accepted
**Date:** 2021-03-15  (best estimate of when decision was made)
**Committed:** 2026-06-03  (date this retrospective ADR was written)
**Retrospective-confidence:** medium
**Reconstructed-by:** Alex Chen
**Source:** PR #247 (linked below) + Claude.ai session 2021-03-11 (WhyChose ref: d4a9c2)
**Implementing PR:** https://github.com/org/repo/pull/247

## Context
[Write from available source material. If reconstructing from memory only, note it:
"Context reconstructed from memory — original decision predates ADR practice."]

The service required durable storage for user profiles and session data. The access
patterns at the time were primarily key-value (user lookup by ID) with occasional
join requirements for the reporting queries the CPO had requested for the Q2 board deck.
The team had 3 engineers, all with Postgres experience; MongoDB was under evaluation
at the time for the document-storage tier.

## Decision
We will use Postgres as the primary data store for user and session data.

## Consequences
**Positive:** Single operational surface; team familiarity means no onboarding cost;
JSONB columns satisfy the flexible-fields requirement without giving up joins.
**Negative:** Will require a schema migration if the document-storage use case (product
catalog with highly variable attributes) grows beyond the JSONB column pattern.
[If Alternatives Considered is thin: "See also: adr-tools PR review comments for the
constraints that drove the evaluation."]

## Alternatives Considered

### MongoDB
- Considered for flexible schema and document storage use case
- Rejected: would have required a second operational dependency; the team's reporting
  queries require relational joins that MongoDB's aggregation pipeline would not express
  naturally with the existing team's SQL familiarity
- Source: PR #247 review comment by @jane

### DynamoDB
- Considered for operational simplicity (managed service, no VPS dependency)
- Rejected: joins for reporting queries would have required a separate read model;
  vendor lock-in risk for a team uncertain of AWS commitment
- Source: memory only — not certain this was formally evaluated; treating as lower-confidence

## Links
- Implementing PR: https://github.com/org/repo/pull/247
- AI chat session (WhyChose extracted): ref d4a9c2 (2021-03-11, "postgres vs mongodb
  for user data" — contains the relational-joins constraint discussion)

Notes on the template fields:

• Date vs Committed: date should reflect the best estimate of when the decision was actually made, even if you're only guessing the month. committed is when the retrospective ADR was merged. Tools like Log4Brains and adr-tools use the date field for sorting — a committed date of today with a decision date of 2021 correctly positions the ADR in the chronological record.
• Source field: List every source you used for reconstruction. Future engineers who question the ADR provenance should be able to verify the sources directly. A broken source link is better than no source field — at least it shows where the reconstruction was attempted.
• Alternatives per-entry confidence: If some alternatives are from primary sources and some are from memory, note it per-row. "Source: PR #247 review comment" vs "Source: memory only" per-alternative is more honest than a blanket confidence level on the whole section.

Using AI chat exports as the primary source

For decisions made since 2022, AI chat sessions are typically the richest available source for retrospective ADRs — richer than most PR descriptions and orders of magnitude richer than memory. The reason is structural: when engineers use ChatGPT or Claude to think through an architecture decision, the AI naturally elicits the exact content the ADR needs. The AI asks "what are your constraints?", "what alternatives are you considering?", "what happens if the load spikes?" — and the engineer answers with the specific context that a week later will feel obvious and not worth writing down, but six months later will be the information nobody can reconstruct.

A Claude.ai or ChatGPT session from the week an architecture decision was made typically contains:

• The explicit alternatives that were being compared (not invented in retrospect)
• The specific constraints that made the alternatives unacceptable (access pattern, team familiarity, cost, operational complexity at the team's current scale)
• The concerns about the chosen option that the engineer hadn't resolved yet (which become the honest Consequences negative section)
• The rationale stated in the engineer's own words, not a rationalized narrative constructed months later

This material maps almost directly onto the ADR sections: the session's alternative comparison becomes Alternatives Considered; the constraint discussion becomes Context; the unresolved concerns become Consequences negative; the final recommendation becomes the Decision statement draft.

Finding the relevant sessions

Exporting several years of ChatGPT or Claude history produces a conversations.json file that contains every session you've had. The WhyChose extractor processes this export and ranks sessions by decision density — sessions with explicit comparison language ("X vs Y", "why I chose", "trade-offs between") and constraint language ("given that we can't", "the constraint is", "the problem with Y is") score highest. For a retrospective ADR about the Postgres decision from 2021-03-15, filter the export to the two-week window around that date and search for sessions mentioning "postgres", "mongo", or "database".

If you remember working through the decision in a Claude.ai or ChatGPT session but aren't sure exactly when, the WhyChose extractor's decision-extraction mode surfaces the most decision-dense sessions regardless of date. Run it on your full export and look for sessions in the relevant date range with high decision scores — you'll typically find the session within a few minutes even across years of history.

Backlog prioritization in practice

If you're starting an ADR practice and inherit a multi-year backlog of undocumented decisions, the following prioritization produces the highest value per hour of retrospective work:

1. Decisions the team re-litigates. If the same debate comes up repeatedly ("why are we on a monolith again?"), write the retrospective ADR first. The debate is proof of active demand for the record. One ADR that ends a recurring debate is worth more than five ADRs for decisions nobody is questioning.
2. Decisions that constrain a planned change. If your team is planning to migrate to microservices, a retrospective ADR for the original monolith decision will be referenced by the migration ADR — write it before starting the migration write-up. The retrospective ADR becomes the "Superseded by ADR-0089" record that documents the full decision arc from adoption to migration.
3. Decisions where the original decision-maker is leaving. Institutional knowledge exits with departing engineers. If someone who made a significant architecture decision is leaving in the next 30 days, write the retrospective ADR now while they can still contribute to the Alternatives Considered section. A 30-minute session with the departing engineer produces a better ADR than any amount of detective work afterward.
4. Decisions with high-quality AI chat source material available. If your ChatGPT or Claude export contains a decision-dense session from around the time a significant decision was made, writing that retrospective ADR from the session is fast (the source material is already structured) and produces a high-confidence ADR. These are the easiest wins in the backlog.

Decisions you can deprioritize or skip entirely: decisions that have already been superseded and no longer affect the codebase; decisions made in contexts so different from today (different scale, different team, different product direction) that the reasoning would be more misleading than clarifying; decisions you cannot reconstruct to retrospective-confidence: low without the original decision-maker who is no longer available.

Common mistakes in retrospective ADRs

• Inventing Alternatives Considered for completeness. The most common mistake. Adding "we considered DynamoDB but rejected it for vendor lock-in" when no one actually evaluated DynamoDB looks like a complete ADR but inserts false history into the record. Future engineers who are genuinely considering DynamoDB will find the retrospective ADR's DynamoDB row and assume the team investigated it — leading them to trust a rejection reason that was never actually researched. Only document alternatives you can verify were genuinely evaluated.
• Writing the Context section in retrospect without flagging it. The Context section tells future engineers what constraints were in place when the decision was made. Writing "at the time we had 3 engineers" from memory is usually accurate; writing "the system was handling 500 requests per second" from memory is often an approximation. Flag uncertainty in the Context section: "Approximate load at decision time — see ADR-0031 for the capacity-planning context from Q1 2021" is more trustworthy than an invented number.
• Using the current understanding of the decision's consequences as the Consequences section. The Consequences section should reflect what was anticipated at decision time, not what actually happened. If you're writing a retrospective ADR for a Postgres decision made in 2021 and you now know it led to a migration in 2024, the Consequences section should not describe the migration — that belongs in the supersession ADR that documents the migration decision. The retrospective ADR captures what was known and anticipated at decision time.
• Spending multiple hours reconstructing low-priority decisions. A retrospective ADR that required 4 hours of detective work for a decision that no current team member has ever asked about is a poor use of engineering time. If you can't find primary source material within 30 minutes of searching (git history, PR search, export search), the decision either doesn't have recoverable source material or isn't high enough priority to warrant continued investigation. Write a minimal retrospective-confidence: low ADR with only the Decision section filled in, or skip it and move to a higher-priority backlog item.

Cross-linking retrospective ADRs

Retrospective ADRs should be linked into the existing ADR corpus the same way contemporaneous ADRs are. If a retrospective ADR documents a decision that was subsequently superseded, add the Superseded by ADR-NNNN status to the retrospective ADR when you commit it — don't wait to add the link when the superseding ADR is written. Future readers browsing the retrospective ADR need to know immediately that it has been superseded before reading the content.

If the retrospective ADR documents a decision that is currently Accepted and governs the codebase, link to it from the code: a comment in the relevant config file, service entrypoint, or framework setup pointing to the ADR number closes the loop between the code and the decision record. This is the pattern that makes ADRs discoverable during code review rather than only during a dedicated search.