Five Mechanisms for Capturing Reasoning
Most software organizations lose context faster than they accumulate it. People rotate, features ship, decisions that once had crisp rationale turn into cargo-culted conventions. SDD addresses this with five lightweight mechanisms — each designed to cost under a minute and pay back across months.
1. Decision Rationale
A required section in every Standard-and-above spec. Captures alternatives considered, constraints accepted, and trade-offs made — at the moment the decision is being made, not reconstructed later.
What it looks like in the spec
A structured block that names the chosen option, the rejected alternatives, the constraints that ruled those alternatives out, and the trade-offs the chosen path accepts.
Worked example: SPEC-034 (Preview Mode)
SPEC-034 added authentication to a previously-public tooling surface — a Critical-tier decision that had to be reconciled with ANCHOR-001’s standing "No custom authentication" rule.
Decision D4 documents the choice: custom login page with HMAC-signed session cookie, rather than Vercel Password Protection. The rationale explains why: Vercel Pro’s Password Protection is not path-scoped — applying it would have blocked the entire marketing site. The ANCHOR-001 concern ("solo operator cannot maintain custom auth securely at scale") was re-examined against the specific scope of this change (one user, one secret, one cookie scheme), and a carve-out was recorded rather than a silent override.
Six months from now, a reader asking "why does the preview tooling have its own login instead of the platform auth?" can answer the question in thirty seconds from the spec, without reconstructing the constraint from scratch.
2. Gate Annotations
When approving or rejecting at a gate, the operator briefly notes why — especially when overriding an agent recommendation or choosing between viable alternatives. One to three sentences, attached to the existing gate approval. No new files.
Good examples from the field
"Approved. Keeping this ungated despite marketing pressure — reach > leads at this stage."
"Approved. Chose ConvertKit direct POST over custom serverless because we don’t need to transform the data. Saves a function and a failure mode."
"Passed with known gap: manual browser test deferred to staging. Automated coverage sufficient for merge."
Worked example: SPEC-034 Arch Gate
The Architecture Gate on SPEC-034 originally approved Vercel Password Protection as the auth mechanism. When Phase 2B discovered the Pro-tier constraint (path-scoping requires Enterprise), the gate was amended rather than silently revised. The amendment annotation captured the trigger (discovery during implementation), the new choice (custom login + Astro middleware), and the continued compliance with the ANCHOR-001 constraint.
Without the annotation, the v1.3 spec would read as a clean plan with no visible learning. With it, a reader sees the decision under revision, the reason, and the constraint that still holds.
3. Post-Completion Retros
After a spec reaches production, the owner spends two to three minutes capturing what went well, what surprised them, and any process observations worth keeping. This is separate from learning events — those capture problems. A retro captures insights.
The rule
Required after every Standard-and-above spec in production. Optional for Trivial. Skip if nothing stands out — an empty retro is worse than no retro.
Worked example: the retro that would have caught an estimation gap
SPEC-021 (the SDD methodology brief PDF and campaign landing page) shipped with a human-effort estimate that missed two to three hours of test automation work. At the time, the process had no retro mechanism. Applying the template retroactively would have surfaced exactly that observation — "effort estimation step needs test automation line item" — and the process improvement that followed.
This is the pattern retros are designed to catch: not failures, but calibration gaps that are easy to shrug off in the moment and hard to recover later.
4. Learning Log
A single running file that tracks whether the methodology itself is earning its keep. Reviewed monthly. Mechanisms that aren’t paying back get simplified or removed.
Why a meta-mechanism
Methodology accumulates faster than it justifies itself. Without an explicit log, every addition becomes permanent by default. With one, every addition has to earn its continued presence at a known review cadence.
Worked example: the early signal on WHY comments
The Learning Log entry for 2026-02-24 captures the first real test of the five mechanisms — a production CSS fix across PRs #44 through #46 that was not a spec. Three of the four mechanisms fired naturally during the work (WHY comments, Stack Quirks, an escape event); the Learning Log itself was the one that had to be prompted.
That single observation — "the log gets forgotten when there’s no spec scaffolding to remind you" — shaped the subsequent process update: prompt for a learning log check after any production escape remediation, not just after spec completion.
The log’s own entries are the evidence of its value.
5. Stack Quirks
A one-liner log of platform and tool gotchas discovered through experience. Every quirk links back to the spec or commit where it was hit. Saves the next person (often future-you) from rediscovering the same trap.
What an entry looks like
Vercelroutesconflicts withheaders,rewrites,redirects,cleanUrls,trailingSlash. If both are present invercel.json, production deployments fail silently — no build error, just no deployment triggered. Discovered in SPEC-016 (root cause: SPEC-015 addedheaderswhile SPEC-010 hadroutes). Fix: removeroutes, userewritesinstead.
Worked example: the Astro 5 output mode quirk
During SPEC-034 Phase 2B, the implementer hit an Astro 5 configuration
error: output: "hybrid" had been removed from the
framework. The correct setting was output: "static" with
explicit prerender = false on SSR routes. Rather than
losing the discovery in a commit message, the fix was captured as a
Stack Quirks entry linked to the spec.
The next contributor to touch Astro config on this repo — which could easily be the same operator six months later — reads the one-liner and moves on. This is the cheapest, highest-ROI mechanism in the set.