Skip to content
C.W.K.
Stream
Lesson 04 of 04 · published

Name Your Reversal Condition

~13 min · decision-record, judgment, process, architecture

Level 0Loose Parts
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

The Sentence That Went Into the Document

When the vendoring decision was written down, it did not stop at the reasoning. It carried an escalation path: if the consumer count grows past roughly five, or if the kit starts needing its own dependency pins, revisit packaging — and record the outcome.

Two conditions, both observable by anyone, neither requiring the original author to be present. That is the whole feature. The conclusion is checkable because the premises are stated.

What Happened When It Was Actually Revisited

Eight days later, at the fourth consumer, somebody asked the question anyway — the stated trigger was five, so it had not fired yet. That is worth noticing: a written condition makes the question askable EARLY as well as on time, because it names what the question is about. The revisit produced the same answer — keep the copies — but the useful part is that it produced a new record rather than a shrug. The reasoning was re-run against current facts: the consumers are still loopback siblings on one machine, a package would still add install ceremony and version skew for zero isolation gain, and the drift tests already fail by name when a copy is edited. Then the next trigger was restated: a consumer that genuinely needs pinned kit dependencies.

Notice what that costs and what it buys. It costs ten minutes and a paragraph. It buys the difference between a decision that has been re-examined once and a decision that nobody has looked at since the day it was made — and from the outside, six months later, those two are indistinguishable unless one of them left a note.

A decision without a reversal condition decays into an identity. The reasoning is what makes a choice correct, and the reasoning is contingent on facts. Record only the conclusion and the next reader inherits "we don't do packages here" as a property of the team rather than a response to a situation. They will then either defend it past its expiry or overturn it without knowing which risk it was holding off.

Writing One That Is Actually Checkable

Most reversal conditions in the wild are unusable because they are moods. "Revisit if this becomes painful" cannot be evaluated — pain is continuous, nobody agrees on the threshold, and the person feeling it is usually too busy to file the observation. A usable condition has three properties:

  • Observable without judgment — a count, a presence, a fact you can query. Five consumers is a number. "Too much friction" is not.
  • Attached to the mechanism it would change — the condition names dependency pins because dependency pins are precisely what vendoring cannot express.
  • Written where the decision is read — in the architecture document, next to the reasoning, not in a ticket that closes.

And when it fires and the answer is unchanged, that is not a wasted check. A decision re-confirmed against current facts is meaningfully different from one that was never re-examined, even though the code is identical either way.

Code

The shape of a decision record that can outlive its author·text
DECISION: distribute the shared layer as vendored copies + a drift
          check, not as a published package.

CONTEXT (the facts the reasoning rests on, at the time of writing):
  - N consumers, all private repositories, all owned by one person
  - all checked out on one machine; they talk over localhost
  - deployed together, in one window; no consumer upgrades alone
  - the kit pins no dependencies of its own

REASONING:
  a package sells isolation across time and space. Neither exists
  here, and version skew - what a pin protects - is the exact defect
  this repository was created to remove.

CONSEQUENCES (what we accept):
  - every shared change requires a deploy step into each consumer
  - a hand-edited copy is possible, so the drift check is mandatory,
    not optional
  - the kit cannot express a dependency pin at all

REVERSAL CONDITIONS (check these, not your mood):
  [ ] consumer count > ~5
  [ ] the kit needs its own dependency pins
  [ ] a consumer must run a different revision on purpose

REVISIT LOG:
  <date, 8 days in, at the 4th consumer> - asked EARLY; the stated
           trigger (past ~5) had not fired. Outcome: KEEP. The
           consumers are still siblings on one machine and the drift
           tests already fail by name. Next trigger unchanged: a
           consumer that needs pinned kit dependencies.

External links

Exercise

Pick an architectural decision your project is currently living with that nobody has re-examined — a database choice, a framework, a build tool, a deployment target. Write its reversal conditions now, after the fact. Then evaluate them today. If any condition has already fired without anybody noticing, you have just found the highest-value conversation available to your team this week.
Hint
Write the CONTEXT section first, in the past tense, as the facts that were true when the choice was made. The reversal conditions usually fall straight out of it — they are simply those same facts, negated.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.