That is the actual failure mode of documentation, and it is not staleness. A stale document is at least findable. This one is fine, correct, and unlocatable, because nothing about the way it is stored says what it is for.

Five documents, five questions

The fix that has held up for me is embarrassingly simple: give each kind of document exactly one question, and put it where that kind lives.

The mutability column is doing more work than it looks. A document that can be edited is a document whose history you do not have, and for four of these that is fine. For the fifth it is the whole point.

The three that get no document

This is the part teams find surprising, and it is the part that keeps the folder small enough to trust.

The API shape does not get a document. There is a schema file, both sides are generated from it, and a prose description would be a second source of truth that nothing checks. The architecture rules do not get a document either: there is a test, and it fails. The conventions an assistant needs on every turn live in the always-on context file, which is the only file with a price per turn, so anything look-up-able goes in a registry instead.

The rule generalises. If something is executable, describing it in prose creates a second version that will disagree with the first, and the one nobody runs is the one that will be wrong.

The order they get written in

requirements   why this is worth building, and what done means for a user
  -> journey      what the person actually does, step by step
    -> states       what each screen shows, including the bad ones
      -> issue        one implementable unit, with numbered requirements
        -> decision     written when a choice closed off alternatives

Only the issue is what somebody, or something, implements. The rest exist so the issue can be written well enough to be implementable, which is where most of the failure actually happens: a competent implementation of an ambiguous ticket is the most expensive thing a team can produce.

The decision record comes last on purpose. You cannot write it before the decision, and writing it during the argument produces advocacy rather than a record.

Why this got sharper recently

Two people onboarding a year apart used to be the whole audience for this. It is not any more, and the second reader has different economics.

A person who cannot find the retry decision loses twenty minutes, once. An assistant that cannot find it re-derives it from scratch on every task, forever, and produces something plausible each time. The cost of unlocatable documentation stopped being a one-off and became a subscription.

That is also why the folder having a README explaining which file answers which question is worth more than any individual file in it. It is the only page that tells a stranger, human or otherwise, where to start.

If your team writes documentation nobody can find, that’s the work I do.

It is also the moment your two components became one. Availability now cannot answer while bookings is down, cannot be deployed separately, and cannot be scaled for the read-heavy load it actually has. Nobody decided any of that, and nobody will notice until the day one of them matters.

Turn the arrow around

The alternative is that the write side announces what it did and the read side keeps its own answer.

// booking, when it succeeds
events.publish(new DeskBooked(booking.id(), deskId, date, clock.instant()));

// availability, which never calls booking
public void on(DeskBooked event) {
    occupied.occupy(event.deskId(), event.date());
}

Neither one calls the other now. The coupling is a data shape rather than a method signature, and a data shape is the thing that survives being put on a queue when you eventually need to.

Three decisions inside that, which are easy to get wrong

Publish facts, not aggregates. The event carries an id, a desk and a date. It does not carry the Booking. Pass the whole object and every field of an internal type becomes part of the contract between components, and the first rename is a breaking change nobody expected to be making.

Give the events a home other things may read. In my own service the rule is that availability may import booking.domain.event and nothing else in booking, and an architecture test says so. Without a named place, “published” and “internal” are the same package and the boundary lasts until somebody is in a hurry.

Make the handler idempotent, before you need it. In process an event arrives once. The day it comes from a broker it arrives at least once, sometimes twice, and a handler that increments rather than sets will drift. Write it so replaying changes nothing, and write the test that proves it while it still looks like paranoia.

The test that has to exist

Here is the failure that this design introduces, and it looks like nothing.

“Booking publishes an event” is testable. “The projection reacts to an event” is testable. Both can be green while nothing is subscribed, and then the read model is simply never updated. No error, no exception, no failing test. A desk that was taken an hour ago sits there looking free.

So one test boots the whole thing, books through the real use case, and asks the read side:

this.bookDesk.book(A01, TODAY, "ada@example.com");

assertThat(availabilityOf(A01)).isFalse();

It is the only test in that suite that needs a container, and it is the only one that would notice a missing subscription. Every design that decouples two things needs one test that puts them back together.

What it costs, said plainly

The read model becomes eventually consistent. In process the window is microseconds, and it is not zero, and you should say so out loud rather than discover it during an incident.

You also now have a delivery problem you did not have before: the write commits, then the event is published, and a crash in between loses it. That is solvable, and it is a real cost of this shape rather than a footnote.

The thing you get back is that the two halves can be separated later without a rewrite, because the only thing between them is a message. That is the same trade as putting the decidable half in a script: choose the shape that keeps a later decision open, and pay a small, visible cost now.

If two parts of your system are welded together by a call nobody remembers making, that’s the work I do.

Then you build it, and within an hour you need to know what it looks like while it is loading, what it says when the list is empty, and what happens when the thing the user just clicked was taken by somebody else four seconds ago. None of that is in the design, so you decide it, at four in the afternoon, alone.

The four that get skipped are the four that matter

A screen has more states than it has designs. The ones that get drawn are the ones where everything worked, and the ones that get improvised are the ones a person meets on the day the system is letting them down.

That is exactly backwards. Nobody remembers a list that loaded. Everybody remembers being told “an error occurred” while the thing they wanted disappeared.

So the rule is small and blunt: a feature is not designed until its loading, empty, conflict and failure states are written down. Four extra lines in the document, decided when there is time to think, instead of at the end when there is not.

What the conflict state is really for

Of the four, the conflict is the one teams argue about, because it feels rare. It usually is not. Any system where people choose from a shared pool has a moment where two of them choose the same thing, and if your users mostly act at the same time of day, that moment is not an edge case, it is a Tuesday.

It is also the only state where the system says no to somebody who did nothing wrong. That deserves better than a generic message, and it is where a requirement comes from:

Scenario: somebody else took it first
  Given a desk that was free when the page loaded
  When a member books it and it has since been taken
  Then the board says that desk went, keeps the date they had chosen,
    and shows the list already updated

Read that back as three product decisions. The message is specific. The context the user built up is not thrown away. And the screen is usable again immediately, without a reload.

None of that survives being decided at four in the afternoon.

Where the wording belongs

One rule saves more argument than any other: failure wording belongs to the API, not to the screen.

The client renders the message it was sent. It does not invent one, and it does not translate one. Break that and the same failure is worded three ways in three clients, drifts apart, and the support team learns three vocabularies for one event.

It has a useful side effect. Once the wording belongs to the API, a contract test should be strict about the status and loose about the text, because the text is not part of the coupling. A design decision made about a screen turns out to decide what a test asserts, which is the sort of thing you only notice when both are written down.

The cheapest version of this

You do not need a design system or a new document type. You need a table, in whatever file already describes the feature, with one row per state and one sentence about what is on screen and why.

Writing that took four minutes. It settles arguments that otherwise happen twice, once during build and once during review, and it gives the person building the screen something to check against rather than something to invent. That is the same reason a rule you can execute beats a rule you can read.

If your team’s designs stop at the happy path, that’s the work I do.

Guess which one gets addressed last, if at all. The author works down the list, the easy ones go first, and by the time they reach the eleventh they have been in the diff for forty minutes and want it merged.

The comments that should not exist

Every one of those first ten was decidable. Import order is a formatter. Naming is a lint rule or it is a preference nobody should be spending review on. Whether a class belongs in a package is an architecture rule, and if you cannot write that rule, the boundary was never agreed in the first place.

If a machine can decide it and the machine has not been asked, the fix is to ask the machine, not to ask a person every time forever.

Only the last row needs judgement. Everything above it arrives at the review already answered, and answering it again is not thoroughness.

Say it out loud, in the instructions

This is easy to agree with and hard to hold, because a reviewer who spots something feels obliged to mention it. So it is worth writing down as an instruction rather than a value.

The reviewer in my own harness is told, in as many words, what it may not do:

## What you must not review

Formatting, import order, naming style, architecture boundaries, coverage
percentages, mutation score. All of those are already decided by gates, and a
gate has already said yes or the diff would not be in front of you.
Re-reviewing them is reviewer fatigue, it buries the one comment that mattered,
and it teaches people that review is noise.

If you believe a gate is wrong, say so as a separate note. Do not enforce it
again by hand.

That last paragraph is the release valve. Disagreeing with a gate is legitimate and common. Doing it silently, one comment at a time, on somebody else’s change, is how a rule ends up meaning two things.

The failure it exists to catch

With everything mechanical settled, one question is left, and it has two links that both have to hold: is there a scenario covering each requirement, and is there a test that asserts it?

The second link is the one that goes wrong quietly. A test that runs the code and checks isNotNull on a method whose whole job is a boundary condition is coverage without verification. It passes every gate in the build. A mutation score catches some of it; a reader who knows what the ticket asked catches the rest.

That is the review worth a person’s attention, and it is exactly the thing that gets crowded out by a comment about a blank line.

Two more that stay with the human

Scope. Anything in the diff no requirement asked for is a defect, even when it is an improvement. Especially then: an unrequested improvement is a change nobody planned, tested against, or can attribute later.

The seam. If a diff changes a request or a response shape, the contract should have changed first. A wire change that starts anywhere else is a defect whether or not it happens to work, for the same reason a spec and a contract test answer different questions.

What to do about it on Monday

Take your last ten reviews and sort the comments into the two columns above. Most teams find eight in one and two in the other, and the two are the ones that prevented a defect.

Then pick the largest bucket on the left and make it a gate. You will get the review time back immediately, and the next person to read a review comment will find one that was worth writing.

If your reviews are long and your defects still ship, that’s the work I do.

That combination is confusing enough that teams usually conclude somebody skipped a step. Nobody did. A specification describes what an API may do, and that is a larger set than what any particular caller is relying on.

The change that proves it

Here is the one I ran deliberately, to find out whether the gap was real.

Booking a desk that is already taken answers 409. The spec documents 400 and 409 on that endpoint, because both are genuinely possible: a malformed body is one, a conflict is the other. So I changed the conflict path to answer 400.

Nothing in either build noticed. Both sides were individually correct, both were green, and they disagreed.

What the pact adds

A consumer contract is smaller and stricter than a spec, because it is written from the other end. It does not describe the API, it records what one caller would notice if it changed.

1) Verifying a pact between deskspace-frontend and deskspace-backend
   - a booking for a desk that is taken: has status code 409
     1.1) status: expected status of 409 but was 400

That is the only thing in either repository that said anything.

The part that stops it being annoying

A contract test that is strict about everything is a test somebody deletes. So it has to be strict about the coupling and loose about everything else, and knowing which is which is a design decision, not a mechanical one.

In the same service, changing the problem title from “Desk already booked” to “Conflict” does not fail verification, and it should not. The screen renders whatever title the API sends, which is written down as a rule: failure wording belongs to the API, not to the client, so it is worded once instead of three times in three clients. The title is therefore not part of the coupling.

The status is. So the pact pins the status and the shape, and matches the title by type.

Why not just tighten the spec

The obvious alternative is to delete 400 from that endpoint so 409 is the only failure. It works for this one case and it makes the document worse.

400 is genuinely possible there. Removing it to make the spec behave like a test means the spec is now false, and the next person reading it to find out what the API does gets a wrong answer. A permissive document plus a real gate beats a document that has been bent into a gate, for the same reason a script beats a paragraph: each thing should be doing the job it is good at.

What this costs

Provider verification needs the states each interaction assumes, set up through the real code paths rather than by writing rows directly. That is a real cost and it is where most of the work is.

One thing that is not optional: pin the clock. A pact names a specific date, and with a real clock that date drifts into the past until the service starts rejecting it, and the build goes red having been touched by nobody. A red build that nobody caused is the fastest way to teach a team to ignore a suite.

If your services agree on a schema and disagree in production, that’s the work I do.

So the honest description of local enforcement is that it works on the machines where somebody turned it on, and you cannot see which those are.

Two different promises

A local hook and a shared pipeline look like the same check written twice. They are answering different questions.

Both are worth having, for different reasons. The hook is for speed, and speed is what makes people keep a check rather than resent it. The pipeline is for truth, and it is the only one you can make a promise about.

The trap in writing it twice

A gate that runs before the action is only as good as the rule inside it, and the fastest way to rot the rule is to have two copies of it. Write the check once as a script and call that script from both places. The hook is four lines of shell around it. The pipeline job is a few lines of configuration around it.

If the hook and the pipeline ever disagree, you have the same failure as a rule in two directories: the local one passes, the shared one fails, and somebody starts arguing that the pipeline is broken.

The version worth copying is blunter than that. In deskspace there is one script, toolbox/verify, and both callers are one line:

# .github/workflows/verify.yml
- name: toolbox/verify --mutation
  run: toolbox/verify --mutation

# .githooks/pre-push
"$REPO/toolbox/verify"

The pipeline has no steps of its own. Not because listing them would be hard, but because a list is a second definition of done, and the two would agree right up until somebody added a gate to one of them.

That script decides everything: the registries, formatting, lint, the architecture rules, the tests, coverage, the consumer contract, whether the generated client still matches the spec, and the evals that check the gates themselves. One answer to “is it green”, with one place to change it.

Check what changed, not everything

The one design decision that decides whether this survives is scope. This site carries an archive written years before half the current rules existed, and a pipeline that swept the whole tree would fail on every single run.

A check that is always red stops being information. People learn its colour by heart, stop reading it, and eventually somebody deletes it during an unrelated cleanup and nobody objects. So the job checks the posts in the push and leaves the archive alone, and the archive’s exemption is a fact about the range, not a list of filenames somebody maintains.

Where this leaves the series

Nine parts, and the same move in every one of them. Reason about something once, encode the result, then put the encoding somewhere it runs without anyone choosing to run it.

The order was deliberate: a prompt is the least durable place, a script is more durable than a document, a named sequence beats a remembered one, an index makes it findable, and a gate makes it unavoidable. Each rung stores the same decision somewhere slightly harder to lose. What is left over at the top, the part that never becomes a script, is the part worth your attention, and it is smaller than it looks before you start.

If your team’s practices hold on the machines of the people who wrote them and nowhere else, that’s the work I do.

The fourth place will not help, and the reason is not that people are careless. The rule and its enforcement live in different places, and only one of those runs.

Sort your rules by when they fire

Take any rule your team has and ask one question about it: at what moment does something consult it? Not how good the rule is, not how well it is written. When does it get looked at, and what already exists by then.

The same rule, worded identically, sits in all four rows. What separates them is how much has already happened by the time anyone checks, and every row down that table is a smaller pile of things to undo.

Test-first, as a preference and as a gate

Take a rule every team claims to hold: write the test first. As a document it is uncontroversial and routinely skipped, because on a busy afternoon the test after is obviously fine and nobody is watching.

As a gate before the action it looks like this. A hook runs on every file edit an assistant attempts and refuses the ones touching production code on a branch with no test change:

BLOCKED by the harness: test-first, backend.

You are editing backend/src/main/java/.../BookDesk.java
and this branch has no new or changed backend test.

Write the failing test first, then implement. The test is the specification: if
you cannot express the requirement as a failing test, the requirement is not yet
clear enough to implement.

A test on the other side of the wire does not count. A component test does not
prove a booking rule, and a service test does not prove a screen.

This is a gate, not a preference.

Asking an assistant to work test-first gets compliance most of the time. A non-zero exit code gets it every time, and the difference between those two is the whole argument for this rung. Nothing was created and then reverted. The edit did not happen.

Read the fourth paragraph again, because it is the part that only shows up in a system with more than one deployable. Deskspace has a Java service and a React front end, and the gate answers per side of the wire. A backend test on the branch unlocks backend code and does not unlock a component; a component test does the reverse. A harness with one deployable has no reason to get that right, and is wrong the moment a second one appears.

The rung most people never build

Almost every team has rows one and two of that table. Plenty have row three. Row four is rare, and it is the only one where the wrong thing never exists.

Making an encoded rule findable matters here with the sign flipped. Every other kind of encoded rule has to be discovered before it helps. This is the one kind that does not: it arrives at the moment it is relevant, whether or not anybody opened the README.

Moving the gate is not passing it

A gate that can be edited by the thing it constrains is decoration. So the same harness denies a second, smaller set of actions outright: edits to the hooks, to the architecture rules test, to the coverage and mutation thresholds, and pushes carrying a flag that skips the local checks.

That deny list is short on purpose. It does not try to enumerate bad behaviour. It protects the small number of files whose whole job is to say no, on the theory that an assistant which cannot satisfy a gate will otherwise satisfy it by lowering it, and will do so with a clear and reasonable explanation.

The design constraint that keeps it alive

A gate with false positives gets switched off within a week, and takes the rule with it. So the test-first hook is deliberately narrow: it ignores edits to tests, docs, configuration and resources, fires only on production Java, and carries one documented environment variable for demos.

That last part is not a loophole if it is loud. A bypass that prints why it fired, in a variable nobody sets by accident, is different from a flag anybody can append to a command out of habit.

What it is not

This is not a security boundary, and reading it as one will get you into trouble. Anyone determined can open a second terminal, edit the file by hand, or work somewhere the gate is not watching.

It removes the accidental case: the tired Friday, the flag copied out of an answer online, the assistant helpfully working around an error it does not understand. That case is not the rare one. It is nearly all of them.

The question to ask

For each rule you have written down more than twice, ask what would have to be true for it to be unbreakable rather than agreed. Sometimes the answer is a type, sometimes a schema, sometimes a gate on the tool call. Often the answer is that it should not be a rule at all, because nobody can say precisely when it applies, and that is worth finding out too.

If your organisation keeps agreeing on practices that do not survive contact with a deadline, that’s the work I do.

The tooling is not the level. What decides it is a subtraction: something a person used to read, and no longer does.

The ladder, as a sequence of things you stopped reading

The levels-of-autonomy framing has converged across the industry over the last couple of years, and the clearest articulation of it is Ben Blackmore’s six levels of agentic software engineering. The levels are usually described by what the machine does. Read them instead by what the human stopped doing, and they turn into a test you can actually apply:

Every row is a transfer of attention, not an addition of capability. You are not gaining a reviewer. You are giving up a reader and asking something else to take the shift.

The claim that gives it away

The most common overstatement is a team that has adopted L3 behaviour with L2 evidence. People have stopped reading diffs properly, because reading a forty-file generated change is miserable and the assistant is usually right. But nothing was strengthened to replace them. The tests are the same tests. The scans are the same scans.

That is not L3. That is L2 with the review quietly switched off, and it holds until the first change that is plausible and wrong, which is the exact failure mode automated review is supposed to catch and unexamined review never will.

The honest version of the question is not “are we at L3?” It is: what would have caught it?

Making the answer specific

The good news is that the question has a concrete answer, and it looks like this:

$ ./gates.sh feature/new-pricing
  contract tests           pass    covers the changed endpoints
  mutation score           71%     threshold 70
  dependency scan          pass    no new advisories
  architecture rules       pass    no new inbound edges to billing
  migration reversible     FAIL    2 of 3 have no down step

Something like that is what a person at L3 reads instead of the diff. If your equivalent is “CI is green” with no statement of what green covers, you have not moved up a level. You have moved the reading somewhere nobody does it.

This is the same split as a deterministic core with reasoning at the edges, applied to review rather than to work: the decidable part of a review becomes a check with a name and a threshold, and human attention concentrates on the part no check can express.

Where the leverage actually is

L1 and L2 arrive on their own within weeks of buying licences, and most teams land there without any deliberate effort. What still varies wildly inside those levels is whether anyone states an exit condition before they start, which is the difference between a good day and a bad one and is worth fixing before anybody argues about levels. L5 is a useful horizon and a poor objective. The distance that pays is L2 to L3.5, and it is not a tooling project.

It is a trust project, and trust here has a measurable form. Every level above L2 is a claim that something automated is a good enough substitute for a person’s attention on a class of change. That claim is either supported by evidence about your checks, or it is a hope with a dashboard.

The two-minute version

Pick a change that merged last week. Ask who read it, what they read, and what they would have caught. Then ask what would have caught it if nobody had.

If the answer to the second question is silence, your level is one lower than the one on your slide, and the work is not to move up. It is to earn the level you are already behaving as though you have.

If you need a truthful placement for each of your teams rather than the one on the slide, that’s the work I do.

The hour is not the loss. The loss is that the rule now has two implementations, they disagree in one edge case, and the disagreement will surface as a bug report eight months from now that nobody can reproduce.

Encoding is half the job

A rule you have written down and encoded is not yet a rule your team follows. It is a rule you follow, and a file the next person has to stumble over.

Everything in this series so far has been about the first half: reason once, encode, replay. Turning a runbook into a command only pays if the second person knows the command exists, and that turns out to be a separate problem with a separate fix.

Three things make an encoded rule survive contact with a second person, and only the third one is usually missing:

The second reader changed the economics

This used to be a politeness problem. A colleague who cannot find your script loses an afternoon, once, and you feel vaguely bad about it.

An assistant that cannot find your script rediscovers the repository from scratch, on every task, forever. It gets there, you paid for it, and you will pay again next session, because nothing it worked out was written down anywhere.

That is the shift worth internalising. Discoverability stopped being courtesy and became a per-task cost with a recurring bill.

Four registries, four questions

Deskspace, a Spring Boot and React service I keep as a reference implementation, answers each of them with a file and a lookup tool rather than with a document somebody is supposed to read:

toolbox/tool_mapping.py list         # what tools exist, by key
toolbox/arch_map.py get booking      # where the code lives, and what may depend on it
toolbox/lexicon.py search "checkstyle"  # how we solved this before
toolbox/check_readmes.py             # does every directory explain itself

The architecture map is the clearest case. A package structure is a fact about the repository, so it belongs in a file rather than in a model’s reasoning. Ask an assistant to add a validation rule with no map and it opens half a dozen files to infer a layout that has not changed since the repo was created, then does it again next session. Ask with a map and it is told.

The lexicon is the only one of the four that makes the repository better over time rather than merely keeping it green. Gates stop bad things escaping; a record of how a recurring problem was solved stops the same afternoon being spent twice. Every entry in that one cost somebody real time: that a bare checkstyle:check silently runs Sun’s ruleset, that one code generator breaks against the current TypeScript, that two adapters onto the same upstream collide on a bean name at context startup rather than at compile time.

An index is load-bearing, so it drifts

The index is the piece that keeps working after everyone who built the thing has moved on, which is exactly why it decays unnoticed. Nothing breaks when an index goes stale. The build passes. The tests pass. The only symptom is somebody rebuilding something, months later, in another directory.

So the registry is checked rather than trusted. That repository fails its own build when a tool exists on disk without being registered, and when the architecture map disagrees with the actual package tree:

$ toolbox/tool_mapping.py check
  FAIL  coverage_gaps.py exists but is not registered in mapping.json:
        an unregistered tool is an undiscoverable tool

$ toolbox/arch_map.py check
  FAIL  map lists slice 'billing', no such package in src/main/java

Both directions fail differently. Something on disk missing from the index gets rebuilt. Something in the index missing from disk is worse: it sends the next reader, or the next agent, confidently to a place that does not exist, which is more expensive than having no map at all.

The way this check fails is the point

Moving those scripts into one directory broke the checker in the most instructive way available. It kept globbing the old path, and globbing a directory that no longer exists yields nothing, so nothing was ever unregistered, so the check reported ok.

Forever. The build was green and the index was unenforced, and there is no symptom for that.

What caught it was not the check. It was a test asserting that the check fails when a tool is unregistered. The happy-path test still passed and told us nothing, which is the general shape: a gate with only a happy-path test proves that it runs, not that it gates.

Write the index for both readers

There is no version of this that serves a person onboarding and not an assistant starting a task. Both arrive with no context, both need to know what already exists before building anything, and both give up in the same way when the answer is buried.

That is convenient rather than profound, but it settles an argument that used to take a while: there is no separate machine-readable index to maintain. There is the index, and it is checked, and the human-facing README is generated from it so the two cannot disagree.

The test

Delete the person who wrote it. Can the next one find it in under a minute, without asking anybody, starting from the file they were already going to open?

If the answer is no, the thing is not encoded yet. It is stored, which is not the same, and storage without retrieval is how a team ends up paying to keep a decision it no longer benefits from.

If your team keeps solving the same problem in two directories because nobody could find the first solution, that’s the work I do.

That is not a discipline problem. A boundary described in a document is checked by whoever remembers it at the moment they are in a hurry, which is the same as not being checked, and the drift is invisible because nothing goes red.

What a rule that runs actually is

An architecture test is a few sentences about packages, executed. The value is not the sentences, which you already had. It is that they now have a truth value.

@ArchTest
static final ArchRule availability_knows_booking_only_through_its_events =
    noClasses().that().resideInAPackage(AVAILABILITY)
        .should().dependOnClassesThat(
            resideInAPackage(BOOKING).and(resideOutsideOfPackage(PUBLISHED_EVENTS)))
        .because("events are the published language between these two; a call in "
               + "either direction would make them one deployable forever");

Note the because. When that fails at two in the morning, the reason it exists is in the failure message, not in an ADR somebody has to go and find.

The first run is the point

I wrote eleven rules for a service I had built the week before, to boundaries I had chosen and believed in. Four failed immediately, and every one was a design problem rather than a rule problem.

A shared type nobody meant to share. One slice’s outbound port returned another slice’s domain object. It reads as a saved class and it is a shared kernel: two supposedly independent slices now recompile together and neither owner knows. Fixed by giving the consumer its own small type and mapping in the adapter.

A package name that made the rule lie. A directory named desk inside the booking slice matched a rule about the desk slice, so the rule was quietly answering a different question than the one I asked. Renaming the package fixed the rule.

A real cycle, through the one place nobody watches. A single error-handling class imported every slice’s exceptions, and the shared package it lived in was imported by all of them. Each slice translates its own failures now.

A collision only a container notices. Two adapters onto the same upstream picked the same bean name and the context failed to start. That one is not architecture, and I only found it because these rules pushed me to boot the thing.

Four for eleven, on code written by somebody who was paying attention. That ratio is the argument.

Write the rule expecting it to fail

The practical advice is a small change in stance. Do not write a rule to confirm what you believe. Write it to find out, and read the first red carefully, because it is usually right and you are usually the thing that has to change.

Two failure modes to avoid while doing that:

• Do not weaken the rule to make it pass. If a violation is genuinely acceptable, that is an exception with a name and a reason, not a looser predicate. A rule with a hole nobody can see is worse than no rule.
• Do not assert what you cannot state. I tried to say “availability may depend on booking’s events and nothing else” and first wrote a rule that meant something different and passed. A rule that passes for the wrong reason is the most expensive kind, and it is the same failure as an assertion that tests existence when the invariant is uniqueness: green, and about the wrong thing.

Where to start on Monday

Pick the boundary your team argues about most and write one rule for it. Not a suite, one rule, with a because naming the consequence you are avoiding.

If it passes, you have learned something cheap and you have a rule that will keep being true. If it fails, you have learned something that was going to cost a lot more later, and you found it on a Monday instead of during an incident.

If your architecture is agreed in a document and contradicted in the code, that’s the work I do.