The decisions with no record

This repository has two documents that look like they record decisions, and neither one does.

What MEMORY.md has

659 lines of rules, stated with authority:

"Queries must be infrastructure-agnostic. Receive page and per_page, use .limit/.offset, and return records + total_count. Do not return Pagy objects."

That is a good rule and a clear one. Now try to answer three questions about it from the document:

When was this decided? Not stated.

What was the alternative? Not stated, and there was one, because Pagy's own documentation shows returning its objects, and the gem is in this Gemfile.

What would change the answer? Not stated. If pagination moved to a different gem tomorrow, would this rule still hold, or was it protecting something specific about Pagy?

A rule without those three is an instruction, not a decision record. It tells you what to do and gives you no way to tell whether it still applies.

What git has

The other half, and it has the opposite problem:

$ git log --diff-filter=A --format='%ad %h %s' --date=short -- app/queries | tail -1
2026-02-26 5bb5b08 feat(enrollment): namespace Enrollment domain — DashboardController and UserXpQuery

$ git log --diff-filter=A --format='%ad %h %s' --date=short -- app/services/execution/run_sandbox_service.rb | tail -1
2026-02-26 e0afeb7 feat: Implement Execution Sandbox with ruby.wasm and xterm.js

Dates and authorship, with no reasoning. e0afeb7 tells you that on 26 February someone decided to run student code in the browser with ruby.wasm. It does not tell you what the alternative was, why it lost, or what the decision costs.

flowchart TB
  M["MEMORY.md: the rule"] --> M1["what to do"]
  M --> M2["no date, no alternative, no expiry condition"]
  G["git log: the change"] --> G1["when, and by whom"]
  G --> G2["no reasoning, no alternative, no consequences"]
  M2 --> A["neither is a decision record"]
  G2 --> A

Four decisions worth a record

Reading the code and the history together, four decisions shaped this application and none of them is written down as a decision.

Run student code in the browser. e0afeb7, 26 February. ruby.wasm and Xterm.js, with no server-side sandbox at the time. Every challenge in the catalog was written stdlib-only because of it. Grading has since moved to the server; lesson 3 comes back to that.

Domain namespacing from day one. 5bb5b08, the same day as the Rails skeleton. Not a refactor that arrived later. The eighth of the forty-seven commits made that day, in a run of six domain-namespacing commits that began three commits after the Rails skeleton, already had Enrollment::.

Two authentication paths. has_secure_password in the skeleton, and GitHub OAuth added on 7 March in 9a38bf1. Both still exist, which is a decision to maintain two, and nothing says why.

Pagy for configuration, not for objects. The gem is used (Pagy::OPTIONS[:limit] appears inside three query objects as the source of the default page size) while MEMORY.md forbids returning its objects. That is a subtle, deliberate line, and a rules document flattens it into a prohibition that reads like a dislike of the gem.

Why the fourth is the best example

Because the rule and the code appear to contradict each other. A newcomer reads "do not return Pagy objects", greps for Pagy, finds it inside three queries, and now has to work out whether the rule is stale, the code is wrong, or there is a distinction nobody wrote down.

There is a distinction, it is a good one, and reconstructing it takes twenty minutes: reading three query objects and inferring the principle. An ADR would have been four sentences.

That twenty minutes is paid by every person who hits the question, forever. The cost of a missing decision record is not the writing; it is the re-derivation, multiplied by everyone who needs it.

Key takeaways

• MEMORY.md states rules with no date, no alternative and no condition that would change them.
• Git has dates and authorship with no reasoning, alternatives or consequences.
• Four decisions shaped this application: browser sandbox (since superseded), day-one namespacing, two auth paths, Pagy config but not objects.
• The Pagy rule and the Pagy code appear to contradict each other; the distinction is real and unwritten.
• The cost of a missing decision record is the re-derivation, multiplied by everyone who needs it.