Record why an approach was rejected—and when to revisit it

Disclosure: I maintain Selvedge, an open-source decision-history tool. This article was prepared with AI assistance from Grok and Codex. The example below is hypothetical and uses plain Markdown; it does not require a particular product.

A repository can show what the code does while leaving out why an apparently reasonable alternative was rejected. A later coding session then has the implementation but lacks the reason behind it.

A useful decision record should help the next person answer two questions: why did we say no, and what evidence would justify revisiting that decision?

Here is a small workflow you can use with Markdown files in a repository.

Record the constraint behind the rejection

Suppose src/cache.py::load_profile reads profiles from a shared database. You consider process-local caching, but one worker could keep serving an old profile after another worker updates it. For this example, that would violate the application's consistency requirement.

Save the reasoning in a file such as docs/decisions/cache-001.md:

# CACHE-001: Defer process-local profile caching

Status: Rejected
Affected code: src/cache.py::load_profile
Approach considered: Cache profiles separately in each worker.

Constraint:
After an update completes, subsequent reads across workers must
observe the updated profile.

Reason for rejection:
A worker's cached profile can remain outdated after another
worker updates the database. We have no shared invalidation
mechanism that satisfies the constraint.

Current decision:
Keep the database read.

Revisit when:
A proposed invalidation design has evidence that it satisfies
the consistency requirement, including tests across workers.

The constraint matters more than a bare instruction such as “do not cache profiles.” It lets someone assess the reasoning instead of inheriting an unexplained rule.

Also distinguish an approach that was considered and declined from one that was implemented and rolled back. The latter can include a reproducer, failed test, or incident reference. Do not imply that an untried idea failed in production.

Find the record before changing the code

A file has little value if nobody reads it. Keep a short decision index, and give records concrete code paths or subsystem names that people can search.

For this example:

rg -n 'load_profile|profile caching' docs/decisions

Before editing, read the matched record and inspect the current code. Check whether the constraint still applies, whether the implementation has changed, and whether there are later records that amend the decision.

If you work with a coding agent, put this retrieval step in the task instructions. Check the result during review: can the agent identify the relevant record and explain its applicability? Having an instruction file does not guarantee that every tool or agent will follow it.

Separate a review trigger from a new decision

Now suppose a shared invalidation design has been implemented. That is a reason to review the rejection, not automatic proof that caching is safe.

The review should examine the requirement and the evidence. For the hypothetical cache, useful cases include an update in one worker followed by a read in another, delayed invalidation, and a worker that misses an invalidation message. Passing a few tests does not establish every property of a distributed system, so state the limits of the evidence.

Record the review in a linked file:

# CACHE-002: Reopen the profile-caching proposal

Reviews: CACHE-001 (cache-001.md)
Status: Reopened for evaluation

What changed:
A shared invalidation design is now available for review.

Evidence to assess:
The design, multi-worker tests, and failure behavior when
invalidation is delayed or missed.

Decision:
Reconsider the proposal. Caching is not yet approved.

Add a link from the first record to the review while preserving the original rationale. If the proposal is later accepted, record that decision and its supporting evidence separately.

The same mechanism works when the first rejection was simply wrong. Say which premise was mistaken and why. An accurately preserved record can still contain an incorrect judgment.

Deliver the qualification with the advice

When a decision is summarized for a later session, include its review state. “Caching was rejected” loses important context if a linked review has reopened the proposal.

A date or condition on a record only helps when someone checks it. If a condition cannot be evaluated, carry that uncertainty into the summary. Keep “needs review,” “reopened,” and “accepted” distinct.

For the next code review, try one small check: identify an earlier rejected approach, find its reason, and explain whether that reason still applies. That gives the record a concrete job in the development workflow.