Skip to content

Systems and records

Software architecture decision dataset: linking each ADR to what happened next

By SourceX Editorial · Updated

9 sections

Short answer

A software architecture decision dataset links each architecture decision record to the requirements it answered, the commits and reviews that implemented it, the deployments that shipped it, and the incidents and superseding decisions that followed. Carry the ADR id in commit trailers, store the links with timestamps in a manifest, and run validator checks for existence, ordering, commit ancestry and status agreement so a second reviewer can verify the outcome.

License terms

Software architecture

This page covers software architecture decision dataset: linking each ADR to what happened next.Illustrative

Key takeaways

  • An ADR records the decision; only linked code, deployment and incident history shows what happened next.
  • Commit trailers carrying the ADR id survive branches that pull request closing keywords ignore.
  • A manifest stores identifiers and timestamps; the documents and diffs stay in their own systems.
  • Validator checks for existence, ordering, ancestry and status agreement let a second reviewer rerun the links.
  • Failing records with unproven links are useful labeled negatives, not rows to delete.

Give every architecture decision record a stable id, carry that id into the issues, pull requests and commits that implement it, record which deployments shipped those commits to which environment, and link incidents, rollbacks and superseding decisions back through the same commits. Keep those links in a manifest with timestamps, and run a validator that fails when a link is missing, points to an unknown commit or contradicts the decision's status.

A software architecture decision dataset built this way shows not only what a team decided and why, but whether the decision was carried out, when it reached production and what happened afterward. That last part is what an ADR folder on its own cannot show, and it is what makes the records useful for evaluating engineering judgment rather than for imitating document style.

The rest of this guide gives the manifest fields, the validator checks, a valid worked record, a failing record, and the limits on what a reviewer can verify.

What does an ADR capture, and what gap does it leave?

An ADR captures the decision at the moment it was made: the forces, the choice, the status and the expected consequences. It does not record whether the consequences arrived.

Michael Nygard's 2011 post that popularized the format describes sections for context, decision, status and consequences, with a status that moves from proposed to accepted and later to deprecated or superseded, records numbered sequentially, and superseded records kept rather than deleted. The MADR template extends this with optional metadata for status, date, decision-makers, consulted and informed, a list of considered options, and a Confirmation section that describes how compliance with the decision can be confirmed, such as a review or an automated test. The adr-tools command line can create a new record that supersedes an older one, updating the older record's status, and can add named forward and reverse links between records.

Those links connect decisions to each other. None of them connects a decision to the code, deployment or incident history that tests it. The Confirmation section comes closest, because it names how the decision should be checked, which makes it the natural place to point to the manifest entry.

Most of the links already exist in tools you use; the work is making them explicit and stable. The weakest links are usually from code back to the decision and from an incident back to the change that caused it.

GitHub's documentation says a pull request description or commit message with a closing keyword such as closes, fixes or resolves links to an issue, but only when the pull request targets the default branch; on any other branch the keywords are ignored. A closing keyword in a commit message closes the issue on merge without listing the pull request as linked. Git trailers offer a sturdier path: git interpret-trailers adds or parses key-value lines at the end of a commit message, so a trailer naming the ADR id travels with the commit itself.

For deployments, GitHub's deployment history view shows the commits that triggered each deployment, the source pull request and branch, and deployment statuses by environment. OpenTelemetry's semantic conventions give stable attribute names for the environment, deployment.environment.name, and the service version, service.version, plus a release-candidate attribute, vcs.ref.head.revision, for the revision. For incidents, the archived Four Keys project from the DORA team linked incidents to deployments by parsing a root cause line holding a commit id from incident metadata, and defined change failure rate as failures per deployment.

Where does the evidence for each link already live?
LinkWhere it usually livesStable keyWeak spot
Decision to work itemADR text, issue trackerADR id in the issueIssues created before the ADR
Work item to codePull request description, commit messageIssue number and ADR trailerKeywords ignored on non-default branches
Code to deploymentCI or deployment historyCommit id and environment nameSquash merges that rewrite commit ids
Deployment to runtimeTelemetry resource attributesService version and revisionVersion strings that are not commit-derived
Incident to changeIncident record, postmortemCommit id cited as causeCauses recorded only in prose
Decision to later decisionADR status and linksSuperseded-by referenceReversals made in code without a new ADR

What should one manifest entry per decision hold?

The manifest holds one entry per decision, with arrays for each kind of linked evidence. Each entry stores identifiers and timestamps only; the documents, diffs and incident narratives stay in their systems and are referenced, not copied.

At a glance

What should one manifest entry per decision hold

Version the manifest itself. When a link is corrected, add a new manifest version rather than editing in place, so a reviewer can see what was known at each date.

What should one manifest entry per decision hold?
FieldContentRequired?Validation rule
adr_id, title, status, status_dateThe decision's id, title and current status with its dateYesStatus is one of proposed, accepted, rejected, deprecated, superseded
requirement_refsIssue or requirement ids with the version in force when decidedYesEach ref existed on or before the decision date
implementation_commitsCommit ids carrying the ADR trailer or linked through a referenced issueYes if acceptedEach commit exists in the repository and postdates the decision
review_refsPull request ids and review outcomesYes if acceptedEach pull request contains at least one listed commit
test_evidenceTest or fitness-function ids named in the ADR's confirmationRecommendedEach test ran on a listed commit
deploymentsDeployment ids, environment name, service version, commit, timeYes if acceptedEach deployed commit is, or descends from, a listed commit
incidentsIncident ids, cited cause commit, resolution timeWhen any existCited commit appears in a listed deployment, or the link is marked unproven
superseded_by and reversalsLater ADR ids or revert commitsWhen any existSuperseded status and superseded_by agree
outcome_summaryShort paraphrase of observed consequences against the ADR's stated onesYes after a review periodEvery statement cites a listed incident, metric or later ADR
rights_and_redactionRepository license basis and redaction notesYes before sharingNo personal names or secrets; third-party code flagged

Which validator checks can a separate reviewer rerun?

A validator turns the manifest from a claim into something a second person can test. Each check below needs only repository access and exports from the issue, deployment and incident tools, so it can be rerun without trusting the original annotator.

  • V1 existence: every commit, pull request, issue, deployment and incident id resolves in its source system export.
  • V2 ordering: requirement refs predate or equal the decision date; implementation commits postdate it; deployments postdate their commits; incidents postdate the deployment they cite.
  • V3 ancestry: each deployed commit is a listed implementation commit or a descendant of one, checked with the repository's commit graph.
  • V4 status agreement: an accepted decision has at least one implementation commit and one production deployment, or an explicit not-yet-implemented flag; a superseded decision names its successor and the successor names it back.
  • V5 incident attribution: an incident linked to the decision cites a commit that is in a listed deployment; otherwise the link is downgraded to unproven rather than dropped.
  • V6 outcome support: every sentence in the outcome summary cites a manifest element, and no outcome is inferred from a closed issue alone.
  • V7 sharing gate: rights and redaction notes are present and no field contains a personal name, credential or customer identifier.

What does a passing illustrative record look like for a session cache decision?

This record is invented to show the manifest; the company, repository and ids are not real, and the counts and durations are illustrative. ADR-0042, accepted, decides to move user session storage from the application database to a shared in-memory cache, with expected consequences of lower database load and a new dependency on cache availability. Its confirmation section names a load test and an alert on cache error rate.

At a glance

What does a passing illustrative record look like for a session cache decision

  • requirement_refs: issue 1187 at version 2, created 6 days before the decision
  • implementation_commits: 3 commits, each with the trailer ADR: 0042
  • review_refs: 2 pull requests targeting the default branch, both approved
  • test_evidence: load test run on the last implementation commit
  • deployments: staging, then production 4 days later, service version derived from the merge commit
  • incidents: 1 incident 19 days after the production deployment, cause cited as the second implementation commit, resolved in 47 minutes
  • superseded_by and reversals: none; a follow-up ADR-0051 amends the cache timeout and links back
  • outcome_summary: lower database load reported in the postmortem; one availability incident traced to the new dependency, matching the ADR's stated risk
  • validator result: V1 to V7 pass

What does the validator catch in a record that only looks complete?

The same decision can look complete in a wiki and fail every structural check. In this illustrative failing version, ADR-0042 still reads accepted, and a team page says it shipped.

The implementing pull request targeted a release branch, so its closing keyword was ignored and no issue link was created. The commits carry no ADR trailer. A squash merge replaced the three commits with one new commit id. The incident record names the cause only in prose. Run against this record, V1 fails because the listed commit ids no longer exist on the default branch, V3 fails because no listed commit is an ancestor of the deployed one, and V5 downgrades the incident link to unproven.

The fix is not to edit the old record but to add a corrected manifest version: map the squash commit to the original commits through the pull request, cite the pull request as the review link, and mark the incident link unproven until someone confirms the cause commit. The failing record is worth keeping in a dataset as a labeled negative example, because it shows exactly the shortcuts that make engineering history unverifiable.

How much of a decision outcome can a second reviewer reproduce?

A reviewer can usually rebuild the code state and rerun the named tests, but rarely the production conditions that produced an incident. The manifest should say which outcome claims rest on reproducible evidence and which rest on recorded telemetry and incident records.

Reproducible: the commit, its build inputs, the test or fitness function named in the ADR's confirmation section, and the ancestry between implementation and deployed commits. Recorded but not reproducible: production load, the incident timeline and the metrics reported in a postmortem. Label each outcome statement with one of the two, and do not present a recorded production effect as if a reviewer had reproduced it.

To make the reproducible part real, pin what a rebuild needs alongside each implementation commit: the build definition and dependency lock files at that commit, the runtime or base image version, and the configuration version the deployment used. Where any of these lived outside the repository and is now gone, say so in the manifest. A reviewer who cannot rebuild the exact state can still confirm the ancestry and ordering checks, which is often enough to show that the decision was carried out as recorded, but not enough to confirm a performance claim made at the time.

Which rights and redaction questions come before decision records are licensed?

Decision manifests point into source code, issue discussions and incident records, and each of those carries its own rights and privacy questions. Repository access does not settle whether code includes third-party or open source components under their own terms, whether contributors' agreements cover new uses, or whether issue threads contain customer details. Names in decision-maker fields should become roles, and security incidents may need to be held back entirely.

Engineering organizations that want to license decision manifests and the history behind them can work with SourceX, which takes on the rights review, the contract, preparation and delivery. Whether a company qualifies is answered by a short assessment that asks for no repository access or upload, and nothing ships until the company has approved the scope and terms and signed.

Frequently asked questions

What is a software architecture decision dataset?

It is a set of architecture decision records linked to the requirements, code, reviews, deployments, incidents and later decisions that followed them. The links let a reader or a model compare what a team expected with what happened.

What should the ADR linkage manifest include?

At minimum the decision id, status and date, requirement refs, implementation commits, review refs, deployments with environment and version, incidents with a cited cause commit, superseding decisions, an outcome summary and rights notes. Identifiers and timestamps go in the manifest; documents stay in their systems.

Why do pull request closing keywords miss links?

GitHub interprets closing keywords only when the pull request targets the repository's default branch, so work merged through a release branch creates no issue link. A commit trailer naming the decision id travels with the commit regardless of branch.

How do you link an incident to an architecture decision?

Record the commit the incident cites as its cause, confirm that commit was in a listed deployment, and follow it back to the decision's implementation commits. If no cause commit is recorded, keep the link but mark it unproven.

Are superseded ADRs still useful?

Yes. A superseded decision with its successor linked shows why a team changed course, which is often the most informative part of the history. Keep both records and make sure each points to the other.

Sources

  • Michael Nygard's 2011 post describes ADR sections for context, decision, status and consequences, sequential numbering and keeping superseded records. Source
  • The MADR template defines status, date, decision-makers, consulted and informed metadata, considered options and a Confirmation section. Source
  • adr-tools' adr new command can supersede earlier records, updating their status, and add named forward and reverse links. Source
  • GitHub documents closing keywords and says they are interpreted only for pull requests that target the default branch. Source
  • Git's interpret-trailers documentation describes key-value trailers at the end of commit messages. Source
  • GitHub's deployment history shows commits that triggered deployments, the source pull request and branch, and deployment statuses. Source
  • OpenTelemetry's deployment attributes define deployment.environment.name as stable. Source
  • OpenTelemetry's VCS attributes define vcs.ref.head.revision, at release-candidate stability, for a revision such as a Git commit. Source
  • The Four Keys metrics page defines change failure rate as failures per deployment; the repository says it is not currently maintained. Source
  • The Four Keys incidents query extracts a root cause commit id from incident metadata and joins it to deployment changes. Source

See if your company qualifies

A short company assessment. No data uploads are needed.

See if your company qualifies