Blog
Long-form essays on engineering decision records, ADR conventions, AI chat as a thinking tool, and how teams keep their reasoning findable. New posts ship roughly weekly. The narrative arc starts with the new-CTO onboarding problem and works outward.
2026-06-06 · ~11 min read
Most teams have either an overcrowded decision log or an empty one. The benchmarks: 3–6 per quarter for very early teams, 5–10 for small teams in active development, 8–15 per squad at scaling stage. "Too few" is a diagnostic signal — almost always a dormant log, not a quiet team. The difference between a quiet quarter (low activity, low decisions) and a dormant log (high activity, near-empty log), what decision debt costs and how it compounds, and how to use extraction data to measure the gap between decisions made and decisions documented.
2026-06-06 · ~10 min read
An ADR written in year one doesn't stay accurate forever. The library gets replaced. The team structure changes. The product pivots. The lifecycle states (Proposed, Accepted, Deprecated, Superseded), when to use each, how to write the links correctly so both records stay navigable, why you should never delete, and what AI chat extraction reveals about how fast decisions actually go stale — technology choices last about eight months before engineers start questioning them; architectural invariants last eighteen months or more.
2026-06-06 · ~10 min read
The most valuable and most commonly missing entry in a decision log is the deliberate choice not to build something. "Yes" decisions leave artifacts — code, PRs, deploys. "No" decisions leave nothing except the reasoning, which lives in a chat session that's impossible to search eight months later. Why AI chat captures rejection reasoning better than ADR tooling, what a "not building this" record looks like, the deferred-vs-permanent distinction that determines whether to write a revisit condition, and how to find these records in the quarterly triage pass.
2026-06-06 · ~10 min read
You extracted your first batch of decisions from AI chat. Now what? The exact 30-minute workflow: request your export the day before, run the extractor, triage the output into four buckets (Promote / Link / Park / Dismiss), write up the 2–5 records that rise to ADR level, archive and set the next quarter's reminder. Plus: which records actually warrant the full ADR treatment, three anti-patterns that kill decision logs, and what the second quarterly review looks like once you have an existing log to check against.
2026-06-05 · ~10 min read
The engineering story behind the WhyChose extractor: five heuristics that went in the bin (sentence-length thresholds, named-entity recognition, first-person verbs in isolation, message-count filtering, Q&A adjacency), four patterns that survived (question shapes, user commit phrases, trade-off markers, reversal markers), and what each failure mode revealed about how engineers actually think with AI. The two-pass architecture that makes it work — and why 3.1% is the right hit rate.
2026-06-05 · ~7 min read
MADR (Markdown Any Decision Record) is the ADR format the ecosystem has converged on — YAML frontmatter, a formal Considered Options section, and a structured Decision Outcome with an explicit "because" clause. What it adds over Nygard's original five-section format, what changed in 4.0 vs 3.x, when to use MADR vs Nygard, how AI chat output maps naturally onto MADR structure, and the tooling stack (Log4Brains, GitHub Action CI validation) that makes the format pay off at scale.
2026-06-05 · ~9 min read
18 months of ChatGPT history, 1,214 conversations, 47MB of export. The extractor surfaced 154 candidates and 38 durable decisions after the durability filter — a 3.1% hit rate. Here's the breakdown by category, the three findings that changed how we work, and what the extractor missed. Pure proof, no pitch.
2026-06-05 · ~8 min read
Three terms for capturing decisions, three different jobs. RFC is the pre-decision proposal (you want input before committing); ADR is the post-decision permanent record (immutable, captures the rejected options, answers "why" at staff turnover); decision log is the broader collection (ADRs plus the lighter product and operations calls). The practical disambiguation — which artifact for which situation — and what to do about the 90% of decisions that happened in AI chat without any of the three.
2026-04-29 · ~9 min read
Almost every team that adopts an ADR practice abandons it within two months. Not because the team is lazy — because the ceremony costs more per decision than people are willing to pay, and the cost compounds every time a record is skipped. The round-trip math, the broken-window effect, and the two-tier shape that actually sticks: extracted records for the 80%, hand-written ADRs only for the load-bearing 20%.
2026-04-25 · ~8 min read
You join a Series A as the new CTO. Six weeks in, someone asks why the stack was picked. The answer isn't in the wiki, isn't in the repo, isn't on the calendar. The reasoning happened — but it happened inside someone else's ChatGPT history, and now they're gone. Why this is the modal new-CTO experience in 2026, why ADR ceremony and Notion wikis don't fix it, and the three-line first-90-days plan that actually does.
Coming · weekly cadence
The onboarding use case: how new engineers use a decision log on day one
The new-CTO onboarding problem is the most vivid illustration of why decision logs matter, but it understates the everyday case: every new engineer who joins a team spends their first week asking "why is it built this way?" questions that a decision log could answer in sixty seconds. What the first-week experience looks like when a decision log exists vs. when it doesn't, how to structure the log so it's navigable by someone who doesn't yet know the codebase, and the specific questions that new engineers always ask that are almost never answered in a wiki or README.
