SERIES · decision-cycle
The single-decision cycle
The single-decision cycle · 8 posts on discipline for architectural decisions
-
The decision graveyard: why six months later nobody remembers why you picked one auth flow over another
Teams accumulate invisible debt not in their code, but in forgotten architectural decisions. Notion and Confluence don't fix this - you need a different format. I break down what this debt looks like on real cases and what a decision format must contain to still be useful a year later.
-
Before you fix it, write three versions of the cause: the detective's move that turns 30 minutes of guesswork into 5 minutes of accurate diagnosis
A good detective doesn't lock onto the first version of events. They propose three or four, describe what evidence each predicts, then go check. The same move - ADI - turns the hasty wrong fix into ten minutes of honest diagnosis. I walk through two real cases: a conversion drop and a slow search.
-
Averages lie: why the trust in a decision is capped by its weakest piece of evidence, not the average of all pieces
A vendor whitepaper and a Slack screenshot from a trusted colleague can score the same 'average quality' - but betting a decision on one vs the other is a different risk entirely. I break down R_eff: three axes of evidence, the weakest-link rule, context matching - and why one benchmark you ran yourself beats ten blog posts from strangers.
-
The motivation section for an architectural decision - making a record that opens itself for review a year later
A judge writes which evidence was considered, which was rejected, and why - so the case can be reopened a year later. Architectural decisions need exactly the same discipline. I break down the six sections of a DDR, with special attention to the one that's skipped most often: conditions for reopening.
-
An architect doesn't start with blueprints - four phases any non-trivial feature passes through, consciously or not
Between a one-line Slack message and a working feature there are four phases: expanding the solution space, breaking it into parts and edge cases, choosing an option, writing the contract document. The only question is whether a team runs these phases in a document in one day - or in code over two weeks of untangling consequences.
-
Spec is not PRD, it's the taste test - intent vs behavior, and why the difference is huge in practice
A recipe can sound delicious and still be unworkable. The final taste of a dish is only verified by eating it. A PRD is the recipe. A Specification is the taste test: verifiable system behavior, a delta format for changes like commit messages, a dependency graph between related specs.
-
POS terminal for methodologies - what Forgeplan is and why hold four ways of working in one plane
A waiter doesn't keep the price list, dish ingredients, taxes, and loyalty points in their head. They press buttons on a terminal, and the terminal remembers everything. Forgeplan is a POS terminal for methodologies: four ways of working in one plane, so you pick the content and the mechanics stay out of the way.
-
The full cycle on a single feature - from a one-liner in chat to a decision that opens itself for review a year later
Six months ago, one line in chat: 'we need streaming for model responses.' Today, a connected set of six files marked active, with measured trust and explicit review conditions. The series capstone: the path from that line to a decision, in seven steps on one real task.