Why does the ADR title matter for findability?

When engineers search a decision archive for 'why did we choose X', topic titles don't answer the question from the filename or list view alone. A decision statement title answers the question in the title itself: 'Chose X over Y for Z' tells you the outcome, the rejected alternative, and the context. In a directory of 50 ADRs, scanned as a list, topic titles require opening each file to determine what was decided; decision statement titles answer the question at the list level. The filename — which is the title in kebab-case — also becomes a meaningful reference: adr-chose-postgres-over-mongo-primary-persistence is a useful slug; adr-postgres is not.

What verb should an ADR title use?

The verb encodes the decision type and should be chosen deliberately. 'Chose' signals a selection among evaluated alternatives — the standard case for most architectural decisions. 'Rejected' signals a decision not to adopt something that was seriously considered — the negative-decision ADR that most teams fail to write. 'Deferred' signals an explicit not-yet — a deferral decision with conditions under which the topic will be revisited. 'Kept' signals a retention decision — the deliberate choice to stay with the current approach after considering an alternative, typically triggered by a migration proposal or a new option becoming available. 'Adopted' is a variant of 'Chose' for policies, practices, and standards rather than technologies. Each verb implies a different document structure and a different reason for writing the record.

Should an ADR title include the rejected alternative?

Yes. The rejected alternative in the title is the most useful part and the part most frequently omitted. 'Chose PostgreSQL' is a partial decision statement — it names the outcome but not the decision. 'Chose PostgreSQL over MongoDB' is a full decision statement — it names both the outcome and what was rejected, which is what future readers need when they encounter MongoDB proposed as an alternative and want to know whether the comparison has been made before. The full structure — chose X over Y for Z — encodes the decision, the rejection, and the context in a single scannable line. When the ADR is listed in a directory of 50 records, this structure answers the question 'has this decision been made?' without opening the file.

2026-06-13 · ~12 min read

The ADR title convention: why the title should be a decision statement, not a topic

Q: What is the correct format for an ADR title?

An ADR title should be a decision statement, not a topic. The structure that works consistently is: verb (chose/rejected/deferred/kept) + subject (what technology, pattern, or policy) + alternative (what was not chosen) + context (what it's for). 'Chose PostgreSQL over MongoDB for primary persistence' is a decision statement. 'PostgreSQL as the primary database' is a topic. The decision statement tells you what was decided without reading the document; the topic requires reading the document to determine what was actually decided.

Most architecture decision records have topic titles: "PostgreSQL as the primary database." "API gateway selection." "Service mesh evaluation." These titles describe a subject, not a decision. The record exists, but you can't tell from the title what was decided — only what was discussed. The distinction matters more than it looks: in a decision archive of 50 records, scanned as a list, topic titles require opening each file to determine what was actually chosen. Decision statement titles answer the question at the list level, before the file is opened. The title is the most-read line in an ADR; most titles are wasted on it.

The argument for decision statement titles isn't about style. It's about information density at the point in the archive workflow where it's most needed. When a senior engineer joins a team and scans the decisions directory, the question they're asking isn't "what topics has the team discussed?" — it's "what has the team decided, and what did they reject?" Topic titles answer the first question. Decision statement titles answer the second. The two questions have different costs: answering "what has been discussed" requires only that the record exists; answering "what has been decided and why" requires that the record's title encode the outcome.

This post covers the structural difference between topic titles and decision statement titles, the specific patterns that produce each, how the verb choice encodes the decision type, why including the rejected alternative is the highest-value part of the title, and what happens to a decision archive at scale when the title convention is wrong.

The anatomy of a decision statement title

A decision statement title has a consistent structure that works across most architectural decisions:

Verb + subject + rejected alternative + context. "Chose PostgreSQL over MongoDB for primary persistence." The verb is "chose" — it names the decision type. The subject is "PostgreSQL" — it names what was selected. The rejected alternative is "over MongoDB" — it names what was not selected. The context is "for primary persistence" — it names the decision scope.

Not every title needs all four components. The context is sometimes implicit when the subject is specific enough: "Chose Kafka over RabbitMQ" is unambiguous for teams where the use case is the event bus. The rejected alternative can be omitted when there is genuinely only one candidate — "Adopted trunk-based development" — though this is less common than it appears, because most decisions involve implicit alternatives even when they're not formally evaluated. But the verb is always required, and the subject is always required.

Compare these:

Topic: "Primary database selection" — describes a process, not an outcome
Partial decision: "Chose PostgreSQL" — names the outcome but not the decision
Decision statement: "Chose PostgreSQL over MongoDB for primary persistence" — names the outcome, the rejection, and the context

The standard ADR examples that circulate in the community tend to use topic titles, which is part of why the pattern persists. The most widely cited example — "Use Markdown Architectural Decision Records" — is closer to a decision statement (it names what was adopted) but still omits the rejected alternative (no-format, plain text, Google Docs, a formal RFC template). The examples train the convention, and the convention trains the examples.

How the verb encodes the decision type

The verb in a decision statement title is doing more work than it appears to. Each verb implies a different document structure and a different reason the record exists.

"Chose" signals a selection among evaluated alternatives. This is the standard case for most architectural decisions. The record exists because a choice was made that forecloses alternatives and accumulates consequences over time. The record's Alternatives Considered section should be substantial, because the evaluation was the hard work. "Chose React over Vue for the dashboard frontend" implies a record with a real evaluation of at least React and Vue, possibly others, with explicit rejection reasons for each non-chosen option.

"Rejected" signals a decision not to adopt something that was seriously considered. This is the most underwritten ADR type. Engineering teams write ADRs when they adopt something; they rarely write ADRs when they evaluate an option and decide against it. But the rejected-option ADR is often more valuable than the adopted-option ADR for future engineers, because it prevents the evaluation from being repeated when the same option resurfaces. "Rejected GraphQL for the internal API layer" — written when the team evaluated GraphQL seriously and decided against it — prevents a future engineer from proposing GraphQL without knowing the evaluation has been done and the specific objections are documented. Decisions that never get written down include rejected options more than any other category, precisely because there's no natural moment to write the record when nothing was built.

"Deferred" signals an explicit not-yet. This is the deferral decision — the choice to not decide yet, with conditions under which the topic will be revisited. "Deferred distributed tracing until team exceeds three services" is not just an absence of a decision; it's a decision that the current complexity doesn't justify the operational overhead, with a named trigger condition. Deferral ADRs are valuable because they make the revisitation condition explicit: the next engineer who proposes adopting distributed tracing can check whether the trigger condition has been met before proposing it, rather than discovering the deferral during review.

"Kept" signals a retention decision — the deliberate choice to stay with the current approach after evaluating an alternative. This ADR type is written when something was seriously proposed as a replacement and the team evaluated it and decided against switching. "Kept PostgreSQL over migrating to PlanetScale given current team operational expertise" — written when PlanetScale was proposed and evaluated — documents that the evaluation happened and names the constraint that was decisive. Without the record, the next engineer who proposes PlanetScale will repeat the evaluation without the prior context.

"Adopted" is a variant of "Chose" for policies, practices, and standards rather than technologies. "Adopted conventional commits for all repositories" applies to something the team is choosing to practice, not something being installed. The distinction between "chose" and "adopted" is mostly a register distinction — "chose X" reads as a technology selection; "adopted X" reads as a practice or standard — but both are decision statement titles.

The rejected alternative belongs in the title

The most valuable part of a decision statement title — and the part most frequently omitted — is the rejected alternative. "Chose PostgreSQL" is an incomplete decision statement: it names the outcome but not the decision. The decision is the comparison. "Chose PostgreSQL over MongoDB" is a complete decision statement: it names both the outcome and what was evaluated and rejected.

The reason this matters becomes clear at the list-scanning level. In a decision archive, the question a reader is often asking is: "Has this comparison been made before?" When an engineer proposes MongoDB as a candidate for a new service, they want to know whether the PostgreSQL/MongoDB comparison has already been evaluated in this organization. A title of "Chose PostgreSQL" doesn't answer that question — you have to open the ADR and check whether MongoDB appears in Alternatives Considered. A title of "Chose PostgreSQL over MongoDB" answers it at the list level.

The objection to including the rejected alternative is that some decisions involve many alternatives, and the title gets unwieldy. "Chose PostgreSQL over MongoDB, CockroachDB, and Cassandra for primary persistence" is long. The practical resolution is to name the most significant rejected alternative — the one that was most seriously considered or that future engineers are most likely to propose. If two alternatives were equally significant: "Chose PostgreSQL over MongoDB and CockroachDB for primary persistence" is still within the range of a usable title. If more than two alternatives require naming, that's a signal that the Alternatives Considered section is the right place for the full list, and the title should name the primary competitor: "Chose PostgreSQL over MongoDB for primary persistence (full evaluation in alternatives section)."

The Nygard ADR template's Context section is where the raw material for the rejected-alternative half of the title comes from. If the Context section doesn't name the alternatives that were in play when the decision was made, the title won't be able to include the rejected alternative — and the Alternatives Considered section is the most commonly underwritten section of the Nygard format. A title that can't name the rejected alternative is a symptom that the alternatives weren't formally evaluated.

Title anti-patterns and what causes them

The patterns that produce topic titles are consistent across teams and codebases, which suggests they have structural causes rather than just stylistic ones.

The noun phrase. "PostgreSQL." "Event sourcing." "GraphQL." Just the technology or pattern name, nothing else. This is the most compressed form of the topic title, and it typically appears in codebases where ADRs are filed quickly under time pressure. The record exists, the content may be good, but the title is inert — it names a subject, not a decision.

The process description. "Primary database selection." "API gateway evaluation." "Authentication approach." These titles describe what the team was doing, not what they decided. They're often written at the start of the evaluation process, before the decision has been made, and never updated when the decision is finalized. The ADR file was opened, the evaluation was written, the title was left as the placeholder that was written when the file was created.

The passive construction. "PostgreSQL selected for primary database." Passive constructions omit the decision-maker and, more importantly, omit the alternatives. The passive voice makes it impossible to include the rejected alternative naturally: "PostgreSQL selected over MongoDB" reads awkwardly; "Chose PostgreSQL over MongoDB" reads naturally. The passive construction is often a sign that the writer was uncomfortable claiming the decision as a decision — the passive voice distributes agency away from the record. An ADR is a claim that a decision was made; the title should own that claim directly.

The question format. "Should we use PostgreSQL or MongoDB?" These ADR titles appear in codebases where ADRs are used as pre-decision documents — the file is created before the decision is made and the title reflects the open question. This is a legitimate use of the ADR format as a pre-decision thinking tool, but the title should be updated when the decision is made. A record with a question title is a record that hasn't been finalized, and it's indistinguishable in a list from a record that was finalized but its title was never updated.

The too-specific title. "Chose PostgreSQL 15.2 over MongoDB 7.0.4 for the auth service database using the connection pool settings from the 2024-02 benchmark on the staging cluster." This title contains useful information — version numbers, benchmark source, specific service — but it's too long to be scannable and too version-specific to remain accurate. The version number belongs in the ADR body; the title should name the decision at the technology level, not the version level. "Chose PostgreSQL over MongoDB for the auth service database" is the scannable version; the benchmark details belong in the Context section.

The filename constraint

In codebases where ADRs live as markdown files in a decisions directory, the title and the filename are related: the filename is the title in kebab-case. This creates a constraint the title must satisfy that prose documents don't have: the filename must work as both a human-readable identifier and a URL slug.

"Chose PostgreSQL over MongoDB for primary persistence" → `0042-chose-postgres-over-mongodb-primary-persistence.md`. This filename is a usable identifier: it appears in git blame, directory listings, pull request diffs, and search results with enough context to be recognizable. It answers the question "what does this file contain?" without opening it.

"Primary database selection" → `0042-primary-database-selection.md`. This filename answers the question "what was this file's subject?" but not "what was decided." It's useful for filing; it's not useful for retrieval.

The kebab-case constraint also puts gentle pressure on title length: filenames above ~80 characters become unwieldy in directory listings and terminal output. This is a useful forcing function — if the decision statement is too long to be a filename, it's too long to be a title. The test: read the filename aloud; if it doesn't answer "what was decided and what was rejected?", the title needs revision.

In tools that display ADRs as web pages or in-app (like Notion-based decision logs), the filename constraint doesn't apply, but the same readability principle does: a title that requires opening the document to understand the decision is a title that has failed at its primary job.

The scale problem: 50 ADRs with topic titles

The cost of topic titles is low when the decision archive has 5 or 10 records. Every engineer on a small team has read most of the ADRs; the titles are memory aids, not retrieval tools. The cost becomes significant at 30-50 records, and severe at 100+, which is where most long-running engineering organizations end up.

At 50 topic-titled ADRs, a new engineer inheriting the codebase has no way to determine whether a decision has been made about a technology without opening each relevant ADR. The decision archive looks like a reading list, not a decision index. The new CTO facing this archive — trying to understand why the system is built the way it is — is doing an O(n) scan through records that could answer their questions in O(1) if the titles were decision statements.

The problem compounds because topic titles also make it impossible to detect duplicate decisions. If two ADRs both address the PostgreSQL/MongoDB comparison — written at different points in the codebase's history by engineers who didn't know about the earlier record — topic titles don't surface the duplication. "Primary database selection" and "Database technology for analytics pipeline" are both topic titles that might contain a PostgreSQL/MongoDB comparison. "Chose PostgreSQL over MongoDB for primary persistence" and "Chose PostgreSQL over MongoDB for the analytics pipeline" make the duplication immediately visible, and also make visible that two different PostgreSQL/MongoDB comparisons reached the same outcome in different contexts — which is useful information for a future engineer considering a third context.

Retrospective titling and AI chat extraction

The title convention problem is specific to ADRs written at decision time. It's different for retrospective ADRs — records written after the fact, documenting decisions that were made in the past without being recorded. Retrospective ADRs are common when teams adopt the ADR practice after accumulating several years of undocumented decisions, or when a post-mortem triggers the need to document the original decision that created a failure mode.

Retrospective ADRs written from memory tend to have better titles than contemporaneous ADRs, because the writer knows the outcome: they're not writing "Primary database selection" in a moment of open evaluation; they're writing "Chose PostgreSQL over MongoDB in 2022 for the core service persistence layer" from a position of knowing what was decided. The outcome is clear, the rejected alternative is known, and the title structure comes naturally.

Retrospective ADRs written from AI chat extraction tend to have the most accurate decision statement titles, because the extracted record identifies the exact decision, the alternatives that were actually on the table at deliberation time (not the ones the engineer remembers three years later), and the constraint that was decisive. When the ChatGPT export contains the original deliberation session, the title can be written against the actual comparison that was made, not the remembered version of it. "Chose PostgreSQL over MongoDB for primary persistence" written from the extracted session is more accurate than the same title written from three-year-old memory — and the difference in accuracy matters most for the rejected-alternative clause, which is the part most likely to be misremembered.

What MADR does differently

The MADR format's guidance on titles takes a different position from the Nygard convention. MADR recommends a short noun phrase as the title, not a decision statement. "PostgreSQL as the primary database" is a MADR-conformant title. This is a deliberate design choice in MADR: the decision statement is encoded in the "Decision Outcome" section, not in the title. The title identifies the subject; the body states the decision.

MADR's reasoning is that the title-as-decision-statement creates maintenance overhead: if the decision is later revisited and superseded, the title of the original ADR becomes misleading (it still says "Chose PostgreSQL" even though the team later migrated to CockroachDB). MADR's noun-phrase title stays accurate across supersession — "PostgreSQL as the primary database" remains an accurate description of the original record even after it's superseded, because it still describes what was being evaluated in the original context.

The trade-off is real. The Nygard convention prioritizes retrieval over maintenance: decision statement titles are more useful for scanning and retrieval; noun-phrase titles are more stable under supersession. The choice depends on whether your primary use case for the decision archive is retrieval (finding whether a decision has been made) or history (understanding the evolution of decisions over time). Most teams benefit more from retrieval — the archive is most often consulted when a new engineer is trying to understand existing decisions, not when reviewing the history of a specific technology's evolution. The ADR review process should handle the consistency of superseded records regardless of title convention.

Applying the convention to an existing archive

Retitling an existing archive of topic-titled ADRs is a one-time investment that pays returns at every future search. The practical approach:

Start with the most-referenced ADRs — the ones that appear in Alternatives Considered sections of other ADRs, the ones linked from the README, the ones that come up in onboarding conversations. These are the records where retrieval quality matters most, and retitling them first improves the most-used paths through the archive.

Apply the verb rule: if the record documents a choice, the title should start with "Chose." If it documents a rejection, "Rejected." If it documents a deferral, "Deferred." If it documents a retained approach under pressure to change, "Kept." The verb is usually determinable from the decision outcome section without reading the full record.

The ADR review process is the right place to enforce the title convention going forward: before merging a new ADR, check that the title is a decision statement (starts with a verb), names the rejected alternative, and scans correctly in a list. A title check takes thirty seconds and prevents years of accumulating topic titles in the archive.

For decisions extracted from AI chat history, the extracted title is usually already a decision statement — the extraction process identifies the decision outcome and the alternatives from the deliberation session. The extracted title can be used directly or lightly edited, and it's usually more specific about the rejected alternative than titles written from memory, because the deliberation session contains the alternatives that were actually considered rather than the ones the engineer remembers.

The title as a quality signal

A team that consistently writes decision statement titles is a team that has consistently thought through the decision clearly enough to name the outcome, the rejected alternative, and the context before writing the record. The title is the compressed encoding of the decision; a good title implies a decision that was made deliberately rather than by default or inertia.

A decision archive where you can scan the list and answer "has this comparison been made?" in under a minute is a decision archive that functions as a retrieval system rather than a document store. The new CTO, the senior engineer from another team, the engineer proposing a migration — they all benefit from the same property: the title answers the question before the file is opened.

The title convention is one piece of the broader practice of writing ADRs that are distinct from decision logs and RFCs — each document type serves a different retrieval need, and the title convention should match the retrieval need. An ADR answers "what was decided and why"; its title should answer the same question in compressed form. A decision log answers "what decisions have been made over time"; its entries are naturally decision statements. An RFC answers "what is proposed and what are the tradeoffs"; its title is appropriately a topic because the outcome isn't known at writing time.

The blank ADR is the right starting point. Open the template, write the title field last — after you've written the Context, listed the Alternatives Considered, and stated the decision outcome. The title should be easy to write at that point, because the decision statement is already present in the body; the title is just the compression of it. If the title is hard to write after the body is complete, it usually means the Alternatives Considered section is thin, or the decision outcome is stated passively, or the constraint that was decisive isn't named clearly enough to produce a title that encodes it. Hard-to-write titles are diagnostic, not just inconvenient.