{"slug": "record-why-an-approach-was-rejected-and-when-to-revisit-it", "title": "Record why an approach was rejected—and when to revisit it", "summary": "A developer maintaining the open-source decision-history tool Selvedge outlined a Markdown-based workflow for recording why a coding approach was rejected and under what evidence it should be revisited. The method stores decision records alongside code with explicit constraints, affected code paths, and revisit conditions, and recommends having coding agents retrieve and explain relevant records during review. The author notes the example is hypothetical and that the article was prepared with AI assistance from Grok and Codex.", "body_md": "*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.*\n\nA 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.\n\nA useful decision record should help the next person answer two questions: why did we say no, and what evidence would justify revisiting that decision?\n\nHere is a small workflow you can use with Markdown files in a repository.\n\nSuppose `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.\n\nSave the reasoning in a file such as `docs/decisions/cache-001.md`:\n\n```\n# CACHE-001: Defer process-local profile caching\n\nStatus: Rejected\nAffected code: src/cache.py::load_profile\nApproach considered: Cache profiles separately in each worker.\n\nConstraint:\nAfter an update completes, subsequent reads across workers must\nobserve the updated profile.\n\nReason for rejection:\nA worker's cached profile can remain outdated after another\nworker updates the database. We have no shared invalidation\nmechanism that satisfies the constraint.\n\nCurrent decision:\nKeep the database read.\n\nRevisit when:\nA proposed invalidation design has evidence that it satisfies\nthe consistency requirement, including tests across workers.\n```\n\nThe 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.\n\nAlso 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.\n\nA 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.\n\nFor this example:\n\n```\nrg -n 'load_profile|profile caching' docs/decisions\n```\n\nBefore 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.\n\nIf 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.\n\nNow suppose a shared invalidation design has been implemented. That is a reason to review the rejection, not automatic proof that caching is safe.\n\nThe 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.\n\nRecord the review in a linked file:\n\n```\n# CACHE-002: Reopen the profile-caching proposal\n\nReviews: CACHE-001 (cache-001.md)\nStatus: Reopened for evaluation\n\nWhat changed:\nA shared invalidation design is now available for review.\n\nEvidence to assess:\nThe design, multi-worker tests, and failure behavior when\ninvalidation is delayed or missed.\n\nDecision:\nReconsider the proposal. Caching is not yet approved.\n```\n\nAdd 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.\n\nThe 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.\n\nWhen 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.\n\nA 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.\n\nFor 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.", "url": "https://wpnews.pro/news/record-why-an-approach-was-rejected-and-when-to-revisit-it", "canonical_source": "https://dev.to/masondelan/record-why-an-approach-was-rejected-and-when-to-revisit-it-20op", "published_at": "2026-09-13 04:38:01+00:00", "updated_at": "2026-09-13 04:56:26.309168+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Selvedge", "Grok", "Codex"], "alternates": {"html": "https://wpnews.pro/news/record-why-an-approach-was-rejected-and-when-to-revisit-it", "markdown": "https://wpnews.pro/news/record-why-an-approach-was-rejected-and-when-to-revisit-it.md", "text": "https://wpnews.pro/news/record-why-an-approach-was-rejected-and-when-to-revisit-it.txt", "jsonld": "https://wpnews.pro/news/record-why-an-approach-was-rejected-and-when-to-revisit-it.jsonld"}}