Nobody commented on the container page. Both flow pages, on the other hand, came back covered in comments. One started an argument that ran for two days and moved a boundary. That was no accident. The flow pages were the only ones that said which part of the organization owned each step. A picture that says who owns what is a picture people can argue with.

That is the bridge between an architecture and the organization it lands in. A design without that bridge is the usual ivory tower, approved and built by nobody. This one came down to the ground, into the problem the teams in that room were living with, and adoption followed at once. Adoption is the only measure of a design I still trust, and this post is about the picture that produced it.

A lifeline is a line

The domain first. The platform models a graph of relations between organizations, worldwide, and one of its hard problems is deciding automatically whether a company somebody just named is one we already know. So take that flow: a partner gets named, and before anything else can happen the platform has to answer, already in our graph, or new?

That's a correct sequence diagram, with a frame, activation bars, real returns and open arrowheads on the messages nobody waits for. My complaint is about everything that is true here and shows up nowhere on the page.

Identity matching runs on a confidence score, and below the threshold we reject nothing. We create a second company instead, and it never merges back. Two in five of these partners arrive with no registration number at all. One new edge makes us recompute a number for every node above it, in a graph 40 million deep. Of the five participants in the picture, four already exist. One is new.

Sequence notation can show all of that. UML has a state invariant for the duplicate, an opt fragment for the missing number and a ref for the matching logic, all of it legal, and all of it also makes the picture wider and costs you a reader fluent in those symbols.

So the notation can express everything I listed. What it runs out of is room, and with room the amount of information one picture can carry. An arrow label holds about four words before it touches the next one, and a sequence diagram spends almost all of its capacity on control flow. The rest follows from that.

Put everything else in a paragraph underneath the picture and you have built a known problem on purpose, one Chandler and Sweller measured in 1991 and called the split-attention effect: split what a reader has to combine, and they get less from both halves.

What a band has room for

So turn it sideways. Participants go down the left and time runs across the bottom.

The same five participants are there, with the same eight messages and the same shape, because Directory still waits for both answers and still sends the event at the end. That is the grey bar. One thing changed: a row has height. So a step becomes a box holding about 25 words, instead of an arrow holding four.

Three rules spend that space, and they are the whole notation. The lane label carries the owning domain, and every domain has an owner in the organization, which is how a lane ends up with a team name on it. The box carries how the step works rather than the name of the method. And one note box carries the reason, because the reason is what disappears first.

What comes back is different

I didn't expect this part. The number of comments stayed the same, but the kind of comment changed.

Send a sequence diagram round and half of what comes back is about the notation. Does this dashed arrow mean async or a return? Is anybody blocked here? Fair questions. Not one of them is about the design, though. So you spend the review teaching people to read the picture, and the picture was supposed to be the cheap part.

Send the lane version instead and the questions are about the system. Why does this cross my team? What happens to a company we created twice, and who picks that up? Nobody's ever asked me what a lane means, because a row with a squad name on it needs no explaining. That is the difference between a diagram people review and one they approve.

The bigger surprise was who joined in, because product people read these without any training, and I had stopped expecting anyone outside engineering to read a sequence diagram at all. The people who can tell you a boundary is wrong are often the same people who were never going to read UML.

Count the handovers, not the arrows

This is where the effort pays, and it costs one line per lane. Write the owning domain on each lane, and since every domain has a team behind it, five services become four squads with three handovers. Each handover is a conversation somebody has to have before any code gets written.

Count them carefully. This is where the idea gets used wrongly. Don't count arrows. Two lanes owned by one squad make a crossing but no conversation, and six arrows between the same two squads are still one conversation. What you count is the pairs of teams that hand each other something.

On the page I sent for review, 8 lanes and 14 steps came down to 3 teams and 3 pairs. The same page broke my own rule about splitting past 6 lanes, which should have been the warning. That number belongs next to the estimate, because it counts the roadmap slots you will need inside other teams and the people who can say no.

None of this came from software. Rummler and Brache made the swimlane popular in Improving Performance: How to Manage the White Space on the Organization Chart. Their finding was simple: processes do not fail inside departments, they fail at the handoffs between them. A famous 80% is attached to that. I couldn't find the source. A sequence diagram has no white space to point at, because its participants are objects. Objects do not have managers, quarters, or a backlog that is already full.

The note box ends with a line I now put on all of them: whose ticket this is gets agreed here, or it gets agreed during an incident.

Yes, this is a swimlane

Somebody will say it. So I will. BPMN has had pools and lanes since 2004, UML has activity partitions in the same specification as the sequence diagram, PlantUML takes |Identity|, and Mermaid has them too. The rotation is twenty years old. None of it is mine.

What I haven't found anywhere is the discipline. BPMN lanes carry a role and hide the reasoning in a properties panel, PlantUML gives you one line per step, and none of them asks for the mechanism or for what the picture will cost in other people's quarters.

What I still cannot do

Returns, for one. A sequence diagram shows exactly when control comes back, while my grey bar only shows that somebody is still holding it.

The tooling is worse than it looks. These pictures come from a model file through a generator, so they diff and regenerate. The skill below writes absolute coordinates instead, the dead artifact I complained about in The Diagram That Cannot Lie. I know how to fix it. I haven't.

Then the one that bothers me. Open one of these on a phone and the text in the boxes drops below 4px. A notation whose only advantage is text density is the one a narrow screen hurts most. It's a desktop artifact. I have no answer for that.

Take the notation, not the picture

The pictures here are worth nothing to you, but the notation might be, so it is a file rather than advice. Drop SKILL.md into .claude/skills/, describe a flow, and get a .drawio back.

SKILL.md ⋅ MIT, no attribution needed, swap the palette for your own.

Its last section is a checklist, the part I'd keep if the rest went. One of its questions asks how many team handovers the picture holds, and whether that number sits next to the estimate.

Send me one of yours with the team names on it. I want to know how many conversations you count.

He had read The Bottleneck Moved, the one about review queues filling with code no human wrote. His verdict, in the channel, unedited: the bottleneck is just context in my view. The part worth writing about was a single line near the end, where I said reviewability is a system property and then walked straight past it.

Then he added the sentence I have not stopped chewing on. Agent SDLC should bring new concepts or resurrect XP practices, he wrote, and put "the true agile" in brackets.

He was right about the burial. The arithmetic was hard to argue with: I had spent eleven hundred words describing a queue, and exactly one sentence on the only part of it I can design.

What the property is, exactly

Start with what a reviewer does. Not the ritual. The actual cognitive act.

You open a diff and a question forms. Then a second one. Historically each question had a destination: the person who wrote it, three desks away, still holding the answer in their head. Review felt like a technical act because the social half was invisible and fast.

Take the author away and the questions don't disappear. They just have nowhere to go.

So here is the definition I have been using since that message. A system is reviewable to the degree that a reviewer's questions have destinations that are not a person. Four questions cover most of what I have watched people actually ask, across fifteen squad reports a month and my own miserable weekends as a one-person review queue:

What breaks if this is wrong? Why this way and not the obvious simpler way? Does it do what it claims to do? And what did this not touch that I assumed it would?

Every one of those has an artifact-shaped answer available. Blast radius is answerable from the diff when contracts sit at the seams and modules have real boundaries. The rejected alternative is answerable from a decision record, which is the only reason to write one. Whether it does what it claims is answerable from tests that state intent rather than pin implementation, so a green suite means something specific instead of meaning nothing loudly. Scope is answerable from size. That is the entire case for small changes, and it survived every fashion that tried to kill it.

None of that is exotic. That's the uncomfortable part.

The half we made optional

Kent Beck put twelve practices in Extreme Programming Explained in 1999. Read the list now, with agents in your peripheral vision, and it splits cleanly into two jobs.

One group keeps the author reachable: pair programming, on-site customer, collective code ownership, the stand-up. The other group makes the artifact answer for itself: test-driven development, continuous integration, small releases, simple design, refactoring, coding standards.

Scrum industrialised the first job. It has no engineering practices at all, by design, and that was not a scandal for the first decade because the second group survived as craft culture in teams that cared. Martin Fowler named the failure mode in 2009 and called it FlaccidScrum: the ceremonies running perfectly while the codebase rotted underneath them. Everyone I knew read that piece and agreed with it. Then we filed it as a maturity problem. Something to get to after the reorg.

Then the author stopped existing.

Every practice in the first group assumes a counterparty who can still be asked. You can't pair with a session that closed. Nobody can. Collective ownership of code that nobody wrote is a sentence missing its subject. The half of agile that survived twenty years of process consulting is the half that needs a human on the other end of the question. And the half we were allowed to skip is the one that had been carrying the arrangement all along.

That's not an argument for going back. Most of XP's first group is still how humans work well together, and I would not run a team without it. It is an argument about which practices are load-bearing now rather than merely good. We spent two decades filing the load-bearing ones under optional, because a human in the room could always cover for them.

The practice everybody mocked came back with a filename

There is one genuinely new thing here, and it arrived in the most embarrassing way possible.

System metaphor was XP's weakest practice. The one Beck had the hardest time explaining, and the one teams dropped first: a shared story of how the system works, with no artifact attached to it. It sounded like poetry in a discipline that wanted checklists. So it evaporated.

It has a path now. CLAUDE.md, AGENTS.md, whatever your tool calls its rules file. We started writing them because a model needed orientation before it could touch anything. What came out was a document describing what the system is, and where the bodies are buried. Then the new joiner reads it on day one and gets more from it than from the wiki.

We needed a non-human reader before we would write down the thing we had refused to write down for twenty years. I find that funny in a way that doesn't fully sit well.

The objection I keep running into

Pair with the agent. Review at write time, watch each change land, and the authorless diff never forms in the first place.

This is the strongest counterargument and it's partly right. Pairing with an agent does move review earlier, and earlier review is cheaper review; that has been true since long before any of this. So far, so good.

But it only holds while a human stays the counterparty. If the person who ran the prompt can still answer for the diff on Thursday then the practice survives intact and the theory has somewhere to live, and if they are meeting the output at the same moment the reviewer is, then nothing was paired at any point. Something was generated and forwarded.

Which gives one standard worth adopting tomorrow, and it costs nothing: "I just ran the agent" is not an acceptable answer in a review. Whoever sends the change is the counterparty for it. That's not a process change, and no tool enforces it. It's a thing a team either expects of each other or doesn't.

I don't know where the ceiling on this sits. Some questions may simply have no artifact-shaped answer, and the honest response to those is to not merge. Which is a far less comfortable conclusion than the one about tooling.

You have been measuring it for years

This is what made me stop treating it as a coding-standards problem.

A new joiner is a reviewer with no context. Everything that makes a system hard to review makes it hard to join, for exactly the same reason. The questions have no destination, so they route to whoever has been there longest, and that person becomes the bottleneck by seniority rather than by design. Reviewability and onboardability are the same property, looked at from two ends.

Which means the metric already exists. You have been collecting it. Time to a new joiner's first merged change is a reviewability number, and it has been sitting in an HR dashboard being read as a statement about the person.

If you want a faster reading, take your last ten merged pull requests and count the times somebody had to ask a human something the repository could have answered. Divide by ten. That is roughly what each authorless diff is about to cost you. Most numbers in this area take a quarter to produce; this one takes an afternoon. And if it comes back zero while your review queue is still three days deep, my argument is wrong.

What I did not see until he named it

The thing I keep turning over is that I had already built this and couldn't see it.

The architecture tool I build at night exists so that editing an element on a canvas produces a Git diff containing that edit and nothing else. No reordering. No reformatting. No comment lost. I built it because diagrams drift, and I wanted one that could not. It took somebody reading my own essay back to me to name what I had made. Blast radius legibility, the first of the four questions, built into a product.

The practices were on the shelf all along. We labelled them engineering hygiene, which is what a discipline calls the thing it means to skip. Twenty years later the one participant who covered for them stopped showing up.

I still read fifteen reports a month. What I look for now is not the ageing queue. I know how to find that. It is the sentence where somebody explains that they had to go and ask. Then the part where they say who.

We were mapping the delivery lifecycle on a whiteboard. Where discovery ends, where execution begins, who hands what to whom. Discovery produces a solution design. Execution produces working software. Two clean boxes and one clean arrow between them. Then he tapped the arrow. "What actually travels along it?"

I had a target state. I always have a target state. What I didn't have was a good answer about the thing in the middle, and for years I had filed it under delivery's problem.

Two worlds, and only one of them should be drawn by a human

A solution design describes two worlds.

The first is the system as it stands today. A person should barely write that description at all. It should be read out of the code, the pipelines, the infrastructure definitions, whatever a tool or an agent can see for itself. This has stopped being an aspiration: reading an existing system is the one job the current crop of agents does better than writing into it, and comprehension is exactly where they are cheapest to trust.

The moment a current-state diagram becomes an opinion, it becomes a flattering one. Nobody draws their own system messier than it is. I have argued the harder version of this before: a model that no compiler checks will drift.

The second world is the target state. What the system looks like once the requirement is genuinely met. That one is a claim about a future that doesn't exist yet, so a named human has to own it.

Both are comfortable to produce. The design reviews well, the boxes are legible, the room nods. Then execution starts, and the two worlds turn out to be separated by something nobody drew.

Debt is not created at design time

One sentence from that conversation reorganized how I work.

A design does not create technical debt. It cannot. It is a document. It has never touched a running system, never shipped a schema, never left a compatibility shim in place for three years.

Debt appears the moment execution stops somewhere other than the target state. And it almost always does. Budgets are annual, priorities rotate, and the reorganization doesn't read your migration plan ;)

I have watched initiatives with genuinely good designs leave systems worse than they found them. Not because the design was wrong. Because the funding ended between step two and step three, in a place nobody had ever considered as a resting position.

A design cannot owe anything. Only a half-built system can.

Which moves the interesting work. Not to the destination. To the shape of the trail.

Make every step a place the system can live

So the question I now ask before a first step is not whether it moves us toward the target. Almost anything does. It is: if this turns out to be the last step we ever fund, what have we left behind?

A step that passes is a resting position: a place the system can stop and live for two years without apology. Three properties, in the order I check them:

• It stands alone. After the step, the system is internally consistent. One model at a smaller scope, not two half-models with a translation layer nobody owns.
• It is reversible, or it is finished. Either the step walks back with a configuration change, or it completed something. What I avoid is the middle: irreversible and unfinished. Decomposing until every step is a two-way door is the same instinct pointed at a different problem.
• It closes an option on purpose. A good step removes a path and names which one. A step that keeps every option open has not decided anything. Optionality feels like prudence long after it has quietly become an unpaid invoice.

Write the stopping point down, not just the destination

The artifact this produces is small. One page, next to the solution design.

The first step. What it deliberately leaves unfinished. The risk of that state persisting for two years, in plain words rather than a severity colour. The name of the person who accepted that risk. And a trigger: the event that makes revisiting it mandatory, so that "not yet" has an alarm attached instead of a hope.

step 1:        …
unfinished:    …
risk if this lasts 2 years:  … (plain words, no severity colour)
accepted by:   <a name, not a role>
revisit when:  <the event that makes "not yet" expire>

That last part I stole from my own hobby repository, where one decision record exists purely to record a decision not to decide, with a written trigger. It transfers to organizational scale better than it has any right to.

It also answers the question every engineering director eventually asks. Should the architect be hard on quality, or should the architect plan the shortcut? Neither is the job. The job is to make the shortcut legible. Say exactly what is being traded, for how long, and by whom. Then the organization is choosing rather than drifting.

The objection I hear is that writing the shortcut down blesses it, that planning the resting position means giving up on quality. But the shortcut doesn't wait for a blessing. It happens either way. The only choice on offer is whether it is chosen or discovered.

What it changed

That whiteboard conversation never produced a clean answer, and I stopped expecting one. What it changed was smaller than an answer.

I still deliver a target state. I still let a tool draw the current one. But the page I spend the longest on now is the shortest of the three: the first step, what it deliberately leaves undone, and the name of the person who agreed to live with that.

It takes an hour to write. It is also the only part of the plan I can be sure will happen, because it happens first. And often enough, it turns out to be the part that happens last.

The design never owed anything. The trail did.

I remembered his interview at the company I worked for back then. I had been certain about him, and the loop agreed. Five rounds, five yes. He did not get the job.

Not because of anything he said, or did, or failed to know. The headcount moved.

That call rearranged something I had believed for a decade.

What five out of five measured

An interview loop is not measuring your worth, and it is not really trying to. It is managing somebody else's risk at scale, and it does that inside constraints that have nothing to do with you. An open seat. A budget cycle. The current shape of a team. A manager's memory of their last bad hire. I have written before about the loop as a risk function rather than a verdict, and every year since has made me more confident that this is the right reading.

Competence is one input. It is a real input, and it is the only one you can prepare. But it gets scored against a system state you were never shown, and that state changes week to week.

Which makes a rejection a reading with two operands. Your skills are one of them. The other is a system nobody described to you.

The years I misread the room

I spent the early part of my career as a consultant, which meant a new project every few months and a lot of first conversations. Two or three a year, sometimes more.

I got good at feeling the outcome early. Ten minutes into a conversation you can usually tell whether anything will come of it. What I couldn't do was name what I was feeling, so I explained it to myself with the only vocabulary I had: they must have wanted somebody more technical.

They usually did not. What was actually being read was whether I could get a thought out of my head and into somebody else's without requiring them to already share my context. Whether I would be pleasant to disagree with at four in the afternoon in a bad week. Whether I asked them anything at all.

I have made a kind of peace with still not being good at the first one. Moving a fully formed idea into another person's head is genuinely hard for me, harder than any system I have been handed to design. That is not modesty. It is the largest gap on my own list, and I know it is there because rejections kept saying so, for years, long before I was willing to hear it.

Depth alone has become a fragile position

It also explains why I have gone cold on the model everyone quotes. The T shape: broad awareness across many areas, deep expertise in one.

The vertical stroke still pays. But maximizing it alone has become a genuinely risky career position, and not for the reason usually given. It is not mainly that agents write code now, although that matters: generation is exactly the part of the vertical stroke that got cheap this decade, and the industry is still mid-argument about what developer skill even means once it did. It is that the scarce thing in any organization is someone who can hold a system-level view and be worked with. Depth without the horizontal stroke produces a person who is right often and expensive to be around, and organizations quietly route around expensive-to-be-around. They do it without malice and usually without noticing.

A colleague I still respect enormously put it better than I have managed since: "If you are right and you were unpleasant about it, you are still unpleasant. If you are wrong and you were decent about it, you were merely wrong."

The second position is recoverable in an afternoon. The first one compounds. It is the individual version of the failure I described in Mathematicians vs. Lawyers: a room that can only think one way is not strong, it is brittle.

Make it a KPI

The practice itself is small, and I would defend it in front of anyone.

Keep a rejection ledger. Not to punish yourself. To check that you are still asking for things.

A year with zero rejections is not a year in which you were universally correct. It is a year in which you applied for nothing, proposed nothing that could fail, and asked for no budget you had not already been promised. A year without rejections is not a good year. It is a small one.

Two habits turn the number into an instrument rather than a bruise:

• Separate the reading from the verdict. Write down what was actually declined. Nine times out of ten it was a fit, a timing, or a seat. One time in ten it is a real gap, and that one is a piece of feedback you got for free that most people pay a career to learn.
• Ask again. Nothing about an organization is stable. The manager with no seat in March has been reorganized by September. The proposal that was too early last quarter is obvious this one. The same request, unchanged, meets a different system and gets a different answer, and almost nobody tries twice.

My friend, the one who called: he took a very good job about a year after the five out of five. Same skills. Different quarter.

Try this

Count the times you were told no in the last 12 months. Four columns are enough for the ledger: the date, what exactly was declined, your best guess at why, and which pile it belongs to. Two piles: the ones that were about you, and the ones that were about the state of the system on that particular Tuesday.

If the second pile is bigger, you've spent a year collecting evidence about other people's constraints and filing it under your own competence. Move it to the right folder and go ask for something.

And if both piles are nearly empty: what did you decide not to ask for this year, and who exactly told you no before you did?

Four teams integrated with the lump.

For a while I explained to myself that this was the organization's failure. It was not. I have stopped arguing with the result. The lump sat closer to what people needed on the day they needed it, and no design review was going to close that gap.

One platform, one architect watching it. Notes, not data.

The responsibility line is drawn in the wrong place

Ask most architects where their job ends and you get a version of the same answer. At the design. Or at the first working version. Adoption after that belongs to delivery, or to product, or to whoever runs the platform. It is a tidy answer. I gave it for years myself.

That line is comfortable. It also produces exactly the thing I described above: a correct system that nobody depends on. It is the mirror image of the orphaned aggregate I wrote about in Nobody Owns the Sum. There, a whole that nobody owned. Here, a part that nobody wanted.

So this is the measure I use now. An architecture is worth what other teams are willing to depend on. Not what it could support one day. What is plugged in this week.

That makes adoption an input to the design. It is not a phase that arrives later and happens to you. You design it, or you inherit whatever shows up.

Two engines, running on different fuel

Things spread inside a company in two ways, and the two are not versions of each other. The fuel is different. So is the bill.

The first engine is pull. Somebody has the problem today, finds your thing, and calling it costs less than building their own. Then they tell one other team. Pull grows on its own. Each new adopter costs you almost nothing, and it keeps only the things that fit.

Pull also cannot be scheduled. That is why programme managers get nervous around it. They are right to be. No roadmap can promise that a thing will be wanted by March.

The second engine is push. Somebody decides that everyone will use the thing, and a plan carries it into teams that never asked for it. Push is the only engine that meets a date. It also spends something you cannot print more of: roadmap slots inside other people's teams, goodwill that takes a long time to come back, and the patience of everybody who has to stop what they were doing and move. The bigger the change, the faster that bill grows, and it does not grow in a straight line.

Domain-Driven Design already named the thing that makes pull possible, and it is one of the less fashionable patterns in the book: the open host service. A published protocol, built for many consumers rather than for the one person standing in front of you. Integrating with it does not require a conversation with its author. That is the whole feature.

It is the outward-facing twin of the anti-corruption layer. That one protects you from their model. This one spends your effort so nobody has to learn yours.

Most internal platforms skip that work. Then they wonder why nobody came. Every hour you spend making the first call easy buys you an adopter you never have to negotiate with, never have to chase for a roadmap slot, and never have to persuade in a meeting where somebody else is asking for the same quarter. No mandate I have ever run paid that well.

Where push stops being worth its price

Simon Wardley's mapping has an axis I keep borrowing for this. It runs from genesis, through custom built and product, to commodity. Lay the two engines over that axis and something useful shows up.

On the far left, in genesis, push does not work at all. The thing is too unformed. You cannot adopt it on a schedule. Mandating it buys compliance without adoption, plus a long tail of adapters written by irritated people. I have written some of those. More than once.

On the far right, at commodity, push is not needed. Nobody mandates the company database. Pull settled that years ago. The alternative became absurd.

Between those two ends sits the mandate window. That is the stretch where a mandate is both necessary and affordable. The thing is good enough to adopt, and not yet obviously worth adopting. Most internal platform work lives right there, and it is the only place where a mandate pays for itself.

The window has a ceiling, and here my answers run out. Somewhere the size of the change outgrows the coordination you have available. Past that point, every extra team costs more to move than the last one did. I have watched initiatives go straight past that ceiling, then spend a year of programme management on the final four teams. Those four were never going to want the thing anyway.

One complication, and I want to be fair to it, because it is the live argument in platform engineering right now. The consensus is close to unanimous: build the platform as a product, win teams over with golden paths, never mandate. I think it is right about the product. And wrong about the window.

The standard objection says a mandate buys compliance rather than adoption. In genesis, that is exactly what it buys. Inside the window the objection loses most of its force. The thing is already good enough, so a quarter of mandated use turns into a dependency nobody wants to remove. And a dependency nobody wants to remove is adoption, whatever you called it on the day it arrived. There is also reporting that mandated platforms keep their funding better than voluntary ones do.

Both can be true. Pull builds the better product. Push keeps things moving while pull gets going, which is a less noble job and still has to be done by somebody. What nobody has measured, as far as I can find, is the exchange rate between the two.

What I do with it now

The design review is no longer where I stop. The last question I ask about anything I helped design used to be whether it was correct. Now I ask how many teams called it this week, and which engine brought each of them in.

The lump taught me that, and it took longer than it should have. Four teams had already chosen, by integrating, while I was still explaining why the other service deserved them.

I am still watching for that ceiling. I cannot compute where it sits. What I can do now is recognise the feeling of being past it: another quarter of programme management, four teams left, none of them moving. I would not defend that as a measurement. It is a warning I did not have before, and it arrives well before any spreadsheet does. That leaves just enough room to stop pushing, and to go make the thing worth calling.

For years the standing blocker was production. Not enough hands, not enough hours, the backlog only grows. This spring the sentence flipped. We are not blocked on writing the code, the reports said. We are blocked on getting it absorbed: reviewed, understood, trusted, merged.

These are notes from one organization, mine, with every bias that implies. But I have checked the pattern against enough teams now to stop filing it as an anecdote.

The queue did not shrink. It moved one seat to the right.

Typing was never the unit of work

We staffed for production because production was visible. Headcount plans, story points, velocity charts: every dial on the dashboard points at how much gets written. Then the cost of producing a diff fell through the floor, and the dials kept pointing at the part that got cheap.

What didn't get cheap is deciding whether the diff is right.

A senior engineer who used to review four colleagues now reviews four colleagues plus everything their agents produce. The reports describe the same scene in different words. Pull requests aging in queues. Reviewers rubber-stamping out of exhaustion. Or the opposite: one reviewer becomes the only honest gate, and everything slows to their reading speed.

Nobody is blocked on writing anymore. Everybody is blocked on believing.

I met this bottleneck alone before I met it at scale. Running a company of one staffed by agents, I am my own review queue, and my throughput is capped by what I can verify, not by what the agents can generate. The organizational version is the same shape with worse feedback loops.

A diff with nobody behind it

There is a reason review did not get cheaper alongside writing, and it took me months to name it.

Reviewing a colleague's change was never a purely technical act. It was a conversation with a counterparty. You read the diff, a question formed, and you walked over and asked it. Why this shape? What did you try first? The answer usually came back in one sentence, because the person who made the decision was still holding it in their head.

An agent's diff has no such person. The intent behind it lived in a prompt, in a context window, in a session that has since closed. You can't ask the author what they were thinking. There was no thinking of the kind you mean, and the human who ran the prompt is often meeting the result at the same moment you are.

In my notes they are simply authorless diffs. The code is here, the counterparty is not, and every question you would have walked over to ask now needs somewhere else to go.

Peter Naur described programming as theory building: the real output of a team is not the program but the understanding that lives in the people who built it. An authorless diff is a diff whose theory is already gone.

So the question has to be answerable by the system itself, or it does not get answered.

Reviewability is a system property

Which is the part I can act on as an architect. How hard a change is to review is not a fact about the reviewer. It is a fact about the system.

You can design a system to be easy to review the same way you design a database to be easy to query. Tests that state intent, so a green suite means something specific. Contracts at the seams, so a change's blast radius is visible from its diff. Small modules with real boundaries, so nobody has to page the whole system into their head. Decision records that say which paths were rejected and why. Context files that tell an agent, or a new colleague, where the bodies are buried. None of it is glamorous.

None of this advice is new. What is new is the price of ignoring it, because now the unreviewable system is the slow system.

Indexes made queries cheap long after disks made storage cheap. Reviewability is the index we now owe our own codebases.

What "done" has to mean now

The definition of done in most teams was written when writing was the scarce step. Code complete, tests pass, merged. Verification was assumed to be somebody's background job.

That assumption is now the whole game. If producing a change costs an afternoon and trusting it costs three days, then the three days are the work, and the definition of done, the staffing plan and the promotion criteria are all still written as though the afternoon were the expensive part. Nobody has updated them. Nobody has noticed.

A senior engineer whose main output is judgment about other people's diffs is not doing less engineering. They are doing the engineering that is left.

The dashboards will resist this, because dashboards count what is easy to count, and reading has always been the thing we measure worst.

What I watch now

I still read 15 reports a month. What changed is the line I look for first.

It used to be the delivery numbers. Now it is a sentence buried in the middle of the wins section, the one admitting that a squad shipped something and nobody could tell whether it was right for a week. That sentence is not a complaint about tooling. It is a system telling you where its constraint sits.

The dashboards above those reports are still counting output, because output is what dashboards were built to count, and I don't expect that to change quickly. But the reports underneath them stopped talking about production some time this spring, and they have not gone back.

The queue did not shrink. It moved one seat to the right, and it is quieter over there, which is why it took a season to notice. If your dashboards are green while your pull requests age, it has moved in your organization too. The authorless diffs are already arriving. The seat they queue for is not on your headcount plan.

The first design instinct in the room was a new service. It had a name before it had a schema: its own repository, its own database, its own deployment. That is the reflex a lot of us share. I understand it. A new capability feels like it deserves a new home. It rarely does.

I have built that unnecessary home before. I know its smell.

What shipped was one table in a service that already existed, and three decisions that had nothing to do with filters.

The service that shouldn't exist

Underneath the product language, saved filters is a small piece of per-user CRUD. Nothing more. Create, list, edit, delete, one of them marked as default. That is not a system. That is a table and a handful of endpoints.

I didn't fight the new service in the meeting. I asked it the three questions I ask every candidate service, out loud, one at a time. What data would it own that nobody else already owns? What lifecycle does it have that its host would not give it? What can fail inside it that should not take the feature down anyway? The answers came back borrowed, none, and nothing. The proposal did not need an opponent after that. It needed a smaller ticket.

So it went inside the service that already aggregates the data the filters run against. Same database, same identity plumbing, same logging and health checks and deploy pipeline. A new service inherits none of that. It owes you all of it. A feature earns a new service when it has its own data, its own lifecycle, its own reason to fail alone, its own release cadence that nobody else has to wait for, and somebody who would notice on a Sunday if it stopped answering. Saved filters has none of those. It borrows all three.

This is the quiet side of the job, and these are exactly the decisions that never reach a slide. The service you chose not to create leaves no artifact behind. Nobody congratulates you for the microservice that isn't there.

Whose filter is this

The sharpest decision was the smallest field: the user id.

The naive version takes it from the request. The client says "save this filter for user 4213," and the server obliges. It works in the demo. It is also a door: anyone who can call the endpoint can write into anyone else's collection by changing a number.

So the user id is never in the request body. It comes from the authenticated context the gateway already forwards downstream, the same context every other call in the platform is scoped by. The client cannot name a user. It can only be one. The safest user id is the one the client never gets to type. Isolation stops being a check I have to remember to write, and becomes a property of where the value comes from.

Copy the nearest working thing

There is always a temptation to design the storage from scratch. Saved filters can hold nested AND/OR logic, so surely it needs a clever relational schema.

It did not. The platform already had a filter model, the exact tree the search feature passes around every day. A saved filter is just that tree, parked in a JSON column, next to the user who owns it. I found the closest existing feature that already did per-user CRUD with that model, and I copied its shape almost line for line. Reuse over invention is not laziness. It is the difference between a feature that behaves like the rest of the system and one that surprises whoever reads it next. It is also the rule that kept an MCP connector boring last week: reuse the trust you already have, invent nothing you will have to guard.

This is the mathematician's move: don't add a new concept when an attribute of an existing one will do. The people who wanted a rich new "saved filter" model were about to breed a small universe of edge cases that a JSON blob of an existing tree simply never has.

Draw the line at durability

One more decision, easy to get wrong in the other direction: how much to persist.

Part of the ticket was really about session state. Keep my filters while I click from the list into a detail and back. That is not a database problem. That is the frontend holding its own state for the length of a visit. I have cleaned up after the other choice before. A store of "recent selections" outlived its feature by years. Nobody dared delete the rows, because nobody could say who still read them. That is how a small convenience turns into something permanent that nobody is allowed to remove. The backend stores the thing you named and want back next week. It doesn't store the thing you'll forget by lunch. Ghost tables start here.

Try this

Look at the last feature you gave its own service. Strip the product language off it and ask three questions. Does it own data nobody else owns? Does it have a lifecycle of its own? Can it fail by itself without taking a real capability down with it?

If it cannot answer yes three times, it was never a service. It was a table wearing a lanyard. What would you fold back in?

Everyone in the room pictured the model. I did too, for about a minute. Then the only question that actually mattered showed up, and it had nothing to do with AI: how does the robot log in?

I want to be honest about the pull I felt. New shiny problem, new shiny solution. Part of me wanted to design something novel for it, a bespoke way for agents to authenticate, because novel is fun and novel gets noticed. What follows is one connector's story, not a security standard.

The thing I actually shipped is almost aggressively boring. And that was the point.

A connector that adds nothing new

The connector is an MCP server, an implementation of the Model Context Protocol, sitting in front of an existing REST API. It translates "answer questions about my data" into calls the API already serves. That is all. No new data path. No new store. It reads, it does not write.

If that shape sounds familiar, it should. It is an anti-corruption layer, the same pattern I keep prescribing to human departments, pointed at AI clients instead. The core API keeps its model. The connector absorbs the foreign one. The AI gets a clean, narrow surface. It never touches the inside.

Here is the rule I set on day one: the connector introduces no new way to trust anyone. The customer already holds credentials for the API. They already exchange those credentials for a token at an endpoint that already exists. Somebody already wrote the rotation story. An on-call rota already knows whose phone rings. The connector does exactly that, on their behalf, and nothing else. No new grant type, no new token broker, no new key store to guard.

Who holds the token now

There is one thing that quietly changes, and you have to own it.

Today the customer's own client holds the token. With a hosted connector in the middle, my process holds it. It reads the credentials off the request, exchanges them for a short-lived token, hands that token to the caller for one hop, and forgets it again before the next request arrives. It caches that token and calls the API. When the API says the token expired, it refreshes.

So I treated the cache like it was radioactive. The key is the client id plus a hash of the secret, never the secret itself. The token lives for minutes. And the secret never enters the model's context. Not once. The one thing worse than leaking a credential is leaking it into a transcript that gets replayed to a language model ;) The telemetry layer redacts it too.

None of that is AI work. It is the plumbing you would build for any proxy that borrows someone's identity. The AI just made the stakes legible.

The boring option won on purpose

There were three real ways to do the auth. Machine login, reusing the existing credential exchange. An issued key with a token broker in front. A full browser login with per-user consent. Each is defensible. Each also drags an architecture behind it, and decisions carry an architecture whether you draw it or not.

Not everyone in the room wanted boring. Novel had fans, and I didn't argue with them. I asked the same three questions of each option instead: who rotates this credential, who answers when it leaks, which team owns the new moving part? For the machine login, every answer was "the people who already do". For the other two, every answer was a new promise someone would have to keep. The room did not pick boring because I pushed it. Boring is what survived the questions.

I chose the machine login, the one that invents the least. When security reviewed it, the finding was the sentence I had been aiming at the whole time: no new risk compared to using the API directly. That is not a compliment to my cleverness. It is the absence of my cleverness, on purpose. The interesting part of an AI feature is usually the least AI part of it.

The hard part was never the AI

Where did the time go? State.

The model is a stateless call and a stream of tokens back. Fine. But those streams are long-lived connections, and long-lived connections don't love being spread across a fleet of identical instances behind a load balancer. The in-process token cache that is so tidy on one node becomes a coordination problem on 20. Sticky sessions. A shared cache. Backpressure on open streams. That is the actual engineering, and none of it has "AI" in the name.

My resolution followed the same rule as the auth: invent the least. Streams pin to the node that opened them, plain session affinity at the gateway we already run. Tokens stay in each node's own memory, and a cache miss costs one extra exchange against an endpoint that was built for that traffic. I looked hard at a shared token store and said no. New infrastructure, secrets at rest in one more place, one more thing to guard and to explain in a review. Twenty small caches that are each allowed to be wrong beat one big cache that has to be right.

Add the unglamorous edge, reused wholesale instead of rebuilt: the same gateway, the same web firewall, the same per-tenant rate limiting, the same audit trail the rest of the platform already trusts, and the same dashboards somebody already looks at on a Monday morning. The connector earns its keep by being indistinguishable from a normal service, right up until you ask it a question in English.

Try this

Next time an AI capability lands on your roadmap, write down the auth and the state design before you write a single prompt. If every interesting decision is about identity, custody and connection lifecycle, and the model is a plain call at the end, you are probably building it right.

So: what did you have to add to let the AI in? If the answer is a new way to trust something, look at that part again before the demo rather than after. A working demo is the hardest argument to reverse in any organization I have worked in. Nobody wants to reopen token custody once 40 people have watched the thing answer a question in English.

One of them walks to the whiteboard and starts drawing boxes and arrows. Entities, relations, flows. Within five minutes the whole domain is a living organism on the wall, and half the room quietly wonders where the actual requirements went.

The other one opens a document and starts listing cases. What if the customer is from Germany? What if the invoice was already corrected? What if the correction arrives after the fiscal year closes? Twenty minutes later you have a table with forty rows, and the whiteboard person quietly wonders why we are debugging the universe.

After years of working as a Solution Architect, I started recognizing these two recurring archetypes of thinking. I call them Mathematicians and Lawyers.

Before anyone gets offended: there are many more archetypes than two, and nobody is purely one of them. These are modes of thinking, not personality boxes. But once you see these two, you cannot unsee them.

The Lawyers

Lawyers live in a linear world of rules. Given condition A and condition B, then C applies, unless exception D. Their thinking moves like a legal act: precise, sequential, exhaustive.

And they are good. A Lawyer is the person who catches the case that would have exploded in production three months after go-live. While the rest of the room admires the elegant model, the Lawyer asks the boring, deadly question: "and what happens on February 29th?"

Their natural artifact is the Document. The big one.

The Edge Case Explosion

This is where corporate culture enters the story, and where my observation stopped being about individuals and started being about the system.

A product company has a very hard time saying no. Every client exception gets accepted. Every "just this one special case" becomes a requirement. And the Lawyers do exactly what they are brilliant at: they faithfully encode all of it. Rule by rule, exception by exception.

The document grows. Fifty pages. Eighty. Hundreds of edge cases, each one individually justified.

Let's be honest with ourselves: nobody reads that document carefully. Nobody except other Lawyers. The rest of us skim it, nod in the review meeting, and approve. The knowledge is technically written down and practically inaccessible.

There is also a trap hiding in plain sight. A thick specification fits perfectly into corporate optics: volume looks like effort. "Big" reads as "a lot of work was done." A three-hundred-page document is impressive in a way that a single clean diagram will never be. So the organization quietly rewards the explosion instead of questioning it.

What you end up with is complexity that nobody ordered. It was delivered one accepted exception at a time, by people doing their jobs well, inside a culture that couldn't refuse anyone.

The Mathematicians

Mathematicians think in abstract systems. They see high-level entities and how they cooperate. Their world is not made of rules but of relations between objects: how those relations evolve over time, what constraints must hold, who governs what.

Show a Mathematician eighty edge cases and they will not see eighty problems. They will ask a different question: what is wrong with the model that keeps generating these exceptions? Change the model, and whole families of edge cases simply stop existing. Nobody has to handle a case that the design made impossible.

Their curse: the impact is less visible. One diagram against three hundred pages. When a Mathematician does the job well, the visible result is… nothing. Complexity that never appeared. Incidents that never fired. An integration that didn't need a workaround. Try putting that on a promotion slide.

In a culture where volume equals work, Mathematicians chronically look underemployed. Right up until they leave, and the edge cases start breeding unsupervised.

And to be fair, Mathematicians have their own failure mode. Left unchecked, they drift into astronaut architecture: models so abstract they no longer touch the ground. Guess who pulls them back? The Lawyer, with one concrete, annoying, absolutely real corrected invoice from Germany.

Two Worlds, One System

This is not a war, and I'm not writing this to declare a winner.

The best design sessions I have ever seen had both minds in the room. The Mathematician reshapes the model so the exceptions dissolve; the Lawyer stress-tests the new model with cases brutally imported from reality. Lawyers keep the Mathematicians honest. Mathematicians keep the Lawyers' world from exploding.

A room full of Lawyers produces an edge case explosion with a spreadsheet to track it. A room full of Mathematicians produces a beautiful abstraction that dies on first contact with a real customer. If everyone in your design review thinks the same way, that is your biggest architecture risk, and it's not in any diagram.

These two worlds complement each other. Use both. Deliberately.

Where I Choose to Stand

My private rule as a Solution Architect: stay at the mathematical level. Don't descend into the details.

Not because details are beneath me. Because the moment I dive into edge cases, I become one more Lawyer in a room that usually has plenty of them already, and the system-level perspective goes vacant. Every edge case has an owner somewhere. The relations between systems often have none. That empty chair is exactly where an architect should sit.

I won't pretend it's easy. Diving into details gives you the quick dopamine of being concretely useful. Holding the abstract level means accepting that your best work will often be invisible: the complexity that never happened.

So, next time you are in a design review, look around the room. Who is writing the rules, and who is drawing the relations? Which one are you when the pressure rises?

And more importantly: who is holding the other half of the picture?

Final score, season after season: features 500, architecture 3. And architecture only scored after live incidents did the lobbying. I suspect your scoreboard looks similar.

The curse of invisible work

In Mathematicians vs. Lawyers I wrote about the thinking archetype whose impact is chronically less visible: change the model, and whole families of problems silently stop existing. This is that curse, operationalized in a backlog.

When architecture work succeeds, the visible result is nothing. The incident that never fired opens no ticket. The complexity that never arrived has no demo. The integration that didn't need a workaround generates no praise thread. Prevention deletes its own evidence. That is the whole problem.

And backlogs, the machinery we use to decide what matters, only rank observables. A backlog is a list of things that will visibly happen. It has no column for things that will invisibly not happen. The counterfactual has no product owner.

Why "the architect wants it" always loses

So how does architecture work usually get argued for? With authority. "This is important." "Trust me, this will bite us." "It's best practice."

Now watch what happens in the room. The feature brings a number; the architecture item brings an adjective. In any meeting where work gets ranked, a weak number beats a strong adjective, even when everyone privately suspects the number is fiction. Arithmetic, even bad arithmetic, gives people something to compare, and comparing is the only thing a backlog knows how to do.

"Trust me" is a real currency, but it doesn't scale. It spends the trust you have, it expires when you leave the room, and it loses every time to a spreadsheet cell. If invisible work is going to survive that meeting, it needs a number of its own.

Give it an honest number

My own fix is borrowed from my tech-radar practice (described in From Signals to Blips): score architecture and debt items on shared, explicit anchors.

importance = multiplicity × severity × strategic_weight

Multiplicity: how many teams or systems the item touches. You count them, which makes this the hardest factor to argue with. Severity (1–3): from a nuisance to actively blocked work, each level anchored in words everyone agreed on beforehand. Strategic weight (1–3): from local cleanup to a decision that sets an organization-wide precedent.

The multiplication matters: an item has to score on several dimensions at once to rank high. But the payoff is elsewhere. It is that you can compare them. Two architecture items scored on the same public anchors can be ranked against each other, and against features, without a single euro of fictional ROI. The anchors are published, so any score can be challenged; "why severity 3?" becomes a productive argument instead of a status contest. And scoring takes minutes, not a discovery sprint.

The fight changes shape immediately. The architect stops begging and starts comparing. "This scores 24 because it blocks four teams at severity 2 and sets a precedent" is a sentence a product owner can accept, challenge, re-weight, or throw out on the spot, and every one of those is better than a shrug: accept it, challenge it, trade against it. "We really should do this" never was.

The trap: fake precision

Now the failure mode, because there is one, and it's seductive.

Having learned that numbers win, the tempted architect goes one step further: "this refactoring will save €340,000 per year." A currency! Decimals! Nobody can verify it, everybody smells it, and you've just converted your credibility into a one-time payment. I wrote about exactly this in Data-Driven Theater. Manufactured precision is worse than being honestly vague, because it teaches the room to distrust all your numbers, including the honest ones.

The anchored score works precisely because it says out loud how crude it is. It says: this is a triage tool built on public guesses (multiplicity counted, severity argued, weight assigned), not an audited business case. Every input can be defended line by line, which is exactly what makes it safe to use. A number you can't defend is a loan against your credibility.

So don't fake ROI. Publish the anchors, score in the open, state the assumptions, and let people attack the inputs instead of your authority.

The invisible work will never fully market itself. Prevention deletes its own evidence, and no formula changes that. But there is a difference between invisible and unpriced. You can't make the counterfactual observable. You can make it comparable.

One exercise before your next prioritization meeting: take the most valuable thing your team never shipped a ticket for, the outage that didn't happen or the rewrite that turned out unnecessary, and score it. Multiplicity, severity, strategic weight. Three inputs and a multiplication.

These days I don't walk into that room to argue. I walk in with a column instead. That is a smaller thing to ask for than it sounds. A column does not need anybody to believe me. It needs somebody to disagree with a severity rating in public, and that is an argument I can win. The one about whether architecture is worth doing is not.

Somewhere around the third iteration of the target-architecture diagram I stopped and started laughing. Boxes with narrow responsibilities. A coordinator on top. Formal handoffs. Escalation paths. I had seen this diagram before: in every HR tool I've ever been onboarded into.

I wasn't designing a system. I was designing an organization. And the dozen-plus years I've spent watching human organizations misbehave suddenly became the most relevant architecture experience I own.

Field notes from one solution design follow. Private observations, not a paper.

Same Primitives, Different Substrate

Strip the buzzwords and a multi-agent architecture is built from exactly the primitives an org designer uses: roles (specialist agents with narrow charters), handoffs (who passes work to whom, in what format), escalation paths (what happens when an agent is out of its depth), and trust boundaries (whose output is taken at face value and whose gets verified).

This is not a cute metaphor. The primitives are identical because the underlying problem is identical: coordinating limited intelligences with partial context toward a shared goal. For humans the limits are attention and working memory; for agents, the context window. Same constraint, different units.

The parallels get uncomfortably specific:

• Context windows are span of control. A manager can effectively lead only so many people before nuance drops on the floor. An agent can hold only so much context before it starts confidently forgetting. In both cases the failure smells the same: dropped threads, generic answers, work quietly reinvented twice.
• Agent-to-agent contracts are… contracts. Schemas, expectations, what "done" means. Two teams with a fuzzy interface produce meetings; two agents with a fuzzy interface produce hallucinated handoffs. The meetings are cheaper.
• Decomposition is charter-writing. Deciding what each agent owns is the same act as writing team charters, and it fails the same way, through overlaps (two agents both "own" the answer) and gaps (a question no agent considers theirs).

Supervisors Are Middle Management

The supervisor pattern (one orchestrator routing everything) is multi-agent middle management. And it fails exactly the way middle management fails:

The bottleneck. Route every interaction through one coordinator and you've serialized your parallelism. One overloaded node, everyone else idle. Any resemblance to a manager whose calendar is the company's critical path is fully intended.

The telephone game. Each relay compresses. The specialist's rich answer becomes the supervisor's summary, which becomes a summary of a summary. Fidelity degrades per hop. In orgs we call it "communication overhead", in agents "context loss", and it's the same tax.

Empire building. Give a supervisor agent loose instructions and it starts doing the work instead of routing it: answering domain questions itself, badly, because delegating "feels" riskier than acting. I have met this middle manager. Several times. Some of them were prompts.

The fixes are org-design fixes, translated: push decisions down to the specialists, allow direct channels between agents that collaborate often (not everything needs to go "up"), and define escalation criteria instead of escalation habits. If your supervisor agent starts scheduling coordination meetings between the other agents, turn the computer off ;)

Guardrails Are Governance

Every serious multi-agent design ends up with guardrails: what an agent may do autonomously, what requires human approval, what gets logged for audit. Rename these and you get a governance framework, complete with autonomy budgets, approval gates, and audit trails. The corporate déjà vu is total.

And the same tension applies. Over-govern and you build agent bureaucracy: every action awaiting sign-off, throughput dying politely, the system technically safe and practically useless. Under-govern and you're one confident hallucination away from an incident report. Organizations have been tuning this dial for a century, and the honest answer in both worlds is that the dial never stops needing tuning. You're not choosing a setting; you're accepting a job.

The Mirror

What this exercise actually gave me, beyond a chatbot architecture:

Organizational experience turned out to be directly transferable. Clear charters beat detailed procedures; the smallest unit that can own an outcome end-to-end should own it; and you should never create a coordinator role to fix a communication problem that a better contract would fix for free.

But the transfer runs both ways, and that's the part I can't stop thinking about. When you design coordination from scratch, with no politics, no history, no feelings to spare, you would never include a layer whose only function is summarizing upward. You would never require every hand-off to pass through one node. You would never let two roles both vaguely own the same outcome, and you would never leave an escalation path undefined.

Then you look at your real org chart and ask why it's full of things you would never design. The polite version of the answer is "history". I explored the human side of sitting inside such a structure in Technical Leader — Identity Disorder; designing agents is the first time I've gotten to sit on the other side of the whiteboard.

There is a Conway's law for agents, too: left unattended, your multi-agent architecture will faithfully copy your organization's communication patterns, including the dysfunctional ones, because its designers can't easily imagine anything else. We nearly shipped our org chart into the prompt. I suspect we weren't the first.

Multi-agent design is org design with a compiler. For the first time, our coordination theories produce stack traces instead of opinions.

So here's the question I'd leave you with: if you rebuilt your organization the way you'd architect a multi-agent system (from scratch, charters first, no history to respect), which of your current roles would survive?

And if the answer makes you uncomfortable: the agents are ready whenever you are.

In From Signals to Blips I described how an AI sweep of squad reports feeds our tech radar, and in Probabilistic Metrics what that does to measurement. This one is more personal: how my everyday deliverables became prompt-driven, from solution designs through decision documents to diagrams.

Every workstream carries its prompt

Here is the practice, concretely. A solution design no longer starts in a document editor. It starts in prompt.md. The role, the task, the constraints. Then pointers to context: the decision records that apply, the discovery notes, the previous design this one replaces. In skeleton form:

role:        …
task:        …
constraints: …
context:     decision records · discovery notes · the design this supersedes

These prompts are versioned like code, diffed like code, and re-run like builds. When the output is wrong, I usually don't edit the output. I fix the prompt or the context and regenerate. It took a while to see what follows from that. The conversation with the model is scaffolding. The generated document is a build artifact. The thing worth reviewing, improving and keeping is the prompt plus its context.

The chat is ephemeral. The prompt is the asset.

The context repository

A prompt is only half of the machine. The other half is what it reads: a context repository (decision records, diagrams-as-code, discovery documents, meeting notes) organized for agents to read. Predictable folder structure. One concern per file. Explicit links instead of tribal knowledge. A short index that tells a fresh agent (or a fresh human, it turns out) where truth lives and in what order to load it.

Three years ago, in Stop Calling It Legacy Code, I argued that a codebase is really a Knowledge Container: structured knowledge waiting for AI to read and act on it. This is that thesis, applied deliberately to the architecture practice itself. I now write documentation the way I used to write integration tests: knowing a machine will consume it, and that its quality directly determines the machine's output quality.

That changed one habit above all: when an agent produces nonsense, my first question is no longer "what's wrong with the model?" but "what's stale in the container?"

What I delegate, and what I never will

What delegates well, after a year of trying. First drafts of solution designs. Sweeps across dozens of documents. Diagrams drawn from a described intent. Checking a design against a question checklist. Checking artifacts against each other, which humans stopped doing years ago. The pattern is clear. AI compresses everything that is reading, restructuring, or drafting.

What never leaves the human: the decision. Our decision framework gives every architecture decision exactly one owner, and that owner is never a model. The agent can rank options, argue trade-offs, even draft the decision record. The moment of commitment stays human. Somebody has to defend it later in front of other people. And so does the meeting where a design earns trust. People, it turns out, still buy architecture from people.

Where it burned me

An honesty section, because the glossy version of this article would be useless.

A generated context diagram once confidently included a component we had decommissioned a quarter earlier. The model didn't lie. My container did: the old decision record was still there, with nothing marking it superseded. Another time, a drafted design proposed a clean, plausible integration path between two systems that have never exchanged a byte. Plausible is the operative word and the real danger: wrong drafts no longer look wrong. Pre-AI, a bad document signaled itself with gaps and hand-waving. Now it arrives fully formed, well-written, and quietly fictional.

The countermeasures are unglamorous: every generated claim must cite the source document it came from; decision records get explicit superseded-by markers the day they die; and nothing leaves the workstream folder without a human pass. If that sounds like the discipline I keep demanding from data pipelines (documented preprocessing, cited sources, a human gate), it is. Same theater risk, same defense.

The operator

In the Legacy Code article I predicted engineers would become Operators: people who express intent, mine their knowledge containers, and judge results instead of typing every line. I just didn't expect the prediction to catch me first.

I author less than I used to. I run a small system of prompts and context that produces first versions of nearly everything. I spend the hours it gives back where they count for more. Decisions, conversations, and better questions of both humans and machines.

So here is my closing challenge. Imagine writing your practice's prompt.md tomorrow, the file that would let a machine draft your typical week's work. Could you? Whatever you cannot yet put into that file is the part of your own job you haven't fully understood. That gap is worth more attention than any tool.

This article is about the piece of that machinery I trust least and use most. The scores that steer our architecture attention are not computed from clean, structured data. They are extracted by AI from messy human text: probabilistically, with a known and accepted margin of error.

For once there is a production system behind my private conclusions, so the usual grain of salt can be slightly smaller ;)

The clean data tax

Classical metrics demand clean inputs: instrumented pipelines, structured events, agreed definitions. That cleanliness is a tax, and you pay it three times. Once in engineering, because somebody has to build and maintain the pipeline. Once in politics, because somebody has to win the meeting where "active user" gets defined. And once in coverage, because you only ever measure what you predicted, a year in advance, would be worth measuring.

And after paying all of that, the numbers still get reshaped in preprocessing before anyone sees a chart. I wrote a whole article about that theater (Data-Driven Theater).

The result is an organization precisely informed about a thin slice of reality and blind everywhere else. And the blind spots are not random. They are exactly the messy, human parts of the system: friction, workarounds, practices quietly spreading between teams, morale.

What AI actually changes

AI changes the input space of measurement. A metric no longer has to start its life as a structured event. It can be extracted from free-form text: a blocker described in a frustrated sentence, a win buried in the middle of a paragraph, the same practice named three different ways by three different teams.

On the radar this is very concrete. An agent decomposes every weekly report into atomic claims, classifies each one as a stopper or a promotable, and scores it on multiplicity, severity, and strategic weight. Nobody built a data pipeline for this. The "sensor" is a versioned prompt pointed at documents that already existed.

Any single extraction can be wrong. And that is not a bug waiting for a fix. That is the deal. You trade per-observation certainty for coverage of the whole organization.

The assumptions

This trade is only sane under explicit assumptions. Here are mine, all learned (some painfully) from running the radar:

1. Accept the error rate, and say it out loud. A dose of acceptance is part of the contract. If a stakeholder expects audit-grade numbers, stop them at the door. This instrument doesn't produce those, and pretending otherwise is how trust dies.
2. Never trust a single extraction. Trust convergence. One squad's report can be misread; five squads independently describing the same friction is a fact about the organization, whatever the error rate per reading. Redundancy replaces precision.
3. Every number must cite its source. Our rule is cite or it didn't happen: each scored signal points back to the exact report, week, and section it came from. Probabilism without traceability is just noise with confidence.
4. A human gate before consequences. Probabilistic metrics route attention; they must never issue verdicts. In our case nothing enters the radar without a human ticking a checkbox. AI proposes, humans dispose.
5. The prompt is the preprocessing, so treat it like code. In Data-Driven Theater I argued that data manipulation lives in the preprocessing phase. Here, the preprocessing is the extraction prompt. So it's versioned, its scoring anchors have a changelog, and anyone can read it. If you hide the prompt, you've rebuilt the theater with better lighting.
6. Shared language still matters, but now it's the model's dictionary. An LLM will happily map three teams' different vocabularies onto one concept. That's the superpower and the danger in one move: it can silently merge things that are not the same. The semantic contracts between people don't disappear; auditing how the model translates becomes part of the method.

What I take out of it

Coverage beats precision when the job is steering. I'd rather be roughly right about the whole organization than precisely right about the 5% of it I managed to instrument. For triage (where should attention go this week) that is simply the correct trade.

You can also measure things that never had a pipeline. Converging practices, recurring friction, the mood of a transformation. On the radar, these signals routinely show up weeks before anything reaches a dashboard, because the dashboard for them was never going to be built.

And metrics become disposable, which is the change I underestimated most: when a new metric costs one prompt instead of one quarter, you can try ten and throw away eight, and the metric portfolio stops being an investment you defend in meetings and becomes a hypothesis you test on Tuesday.

The failure modes move; they don't vanish. Yesterday people gamed the data cleaning. Tomorrow they'll game the extraction.

"When a measure becomes a target, it ceases to be a good measure." ― Goodhart's law, in Marilyn Strathern's phrasing

Same theater, new stage, and the same defense: documented preprocessing, cited sources, and a culture where asking "how was this computed?" is a compliment, not an attack.

None of it will survive an audit, and that's fine. A compass is not an accounting system. Use probabilistic metrics to decide where to look; once you know what you're looking at, instrument it properly. The two don't compete. One finds the question, the other defends the answer.

One question

So here is what I'd leave you with: what would you measure in your organization if a new metric cost one prompt instead of one quarter?

Because that is the actual offer on the table now. The classic excuse for not measuring the human side of your system (too messy, too expensive, no pipeline) has just expired.

And one painfully practical problem: how do you drive change at that scale?

You can't attend every standup. You can't review every experiment. You can't personally convince three hundred people that a new way of working is worth their time. Whatever instrument you pick, it has to scale better than you do, keep working while you are on holiday, stay readable to somebody opening it for the first time, and it has to survive contact with a real organization, where attention is scarce and opinions are loud.

My answer turned out to be a classic: a tech radar. Not the industry-wide kind you read once a year and forget, but an internal, living one: refreshed in editions, fed by real squad data. It scales beautifully, and it shows the state of the transformation in several dimensions at once. The ring tells you how much we trust something: Adopt, Trial, Assess, Hold. The quadrant tells you what kind of thing it is. The movement tells you where it is heading. The evidence tells you who proved it. A radar is opinionated data. It doesn't just list what exists; it shows what we, as an organization, decided to do about it.

This is the first post in a short series about driving an AI transformation with tools that scale. We start with the engine room: how raw signals become blips.

From reports to a score

Every week, each squad files a structured report. Adoption numbers, workflows integrated, wins, blockers, and how mature they think they are. Fifteen files. Roughly two dozen distinct concerns surface every single week.

The old me would try to read everything and keep the picture in his head. The current me sends an AI agent through all of it with a very strict contract.

First, extraction. Every report is decomposed into atomic claims, each tagged with squad, week, and section. Rule number one: cite or it didn't happen. A signal that cannot point back to a concrete cell in a concrete report does not exist.

Second, classification. Only two classes of signal survive the sweep:

• STOPPERS: anything that is stopping, or about to stop, a group of developers from making progress.
• PROMOTABLES: a working practice, skill, or integration that delivered impact and deserves to spread.

Everything else is noise for this run, and it gets dropped. No parking of "interesting but not actionable" items. That discipline hurts at first and pays off every week after.

Third, the score:

importance = multiplicity × severity × strategic_weight

Multiplicity (1–5): how many squads independently raised the same signal. Severity (1–3): from local inconvenience to a blocked initiative (or, for promotables, from a quality-of-life win to a capability the organization did not have last quarter). Strategic weight (1–3): how far the decision ripples, from one squad to an architecture-level precedent.

The multiplication is deliberate. If any factor is low, the product collapses. A concern raised by one developer shouldn't outrank a cross-squad blocker, no matter how eloquently it was written. A signal has to score on all three dimensions to reach the top. The result is a number between 1 and 45, and it comes with bands: above 30 goes to the architecture forum this week, the middle band waits for the next radar edition, the rest is monitored.

It works in practice. Six squads independently naming the same delivery pressure lands at 45, top of the queue. A governance gap raised by a single squad, but blocking an entire platform branch, scores low on multiplicity yet stays visible thanks to strategic weight. The loudest voice stops mattering; the math does the listening.

One thing the score is not: a verdict on truth. It is not effort-weighted, not ROI-weighted, and it deliberately trusts the reports without cross-checking them. It measures signal strength, not validation status. It tells me what to discuss first, not what is true.

From score to blips

One part I consider non-negotiable: the AI never touches the radar.

The sweep produces a candidate list. Each candidate is matched against the existing radar and typed. A new blip. A ring move. A confirmation of something already there. Or my favourite, a contradiction: the field says an adopted practice is breaking in production.

Validation is human. Candidates go to a stakeholder meeting with a checkbox next to every decision. Ticked means it merges into the next radar edition, and every change lands in a changelog so trends across editions stay honest. The radar grew from 42 blips to over 50 this way. Every single addition can be traced back to the squad report that started it.

AI proposes. Humans dispose.

There is a bigger idea hiding inside this machinery. The radar's score is not computed from clean, structured data. It is extracted by AI from messy human text, probabilistically, with an accepted margin of error. I believe that pattern reaches far beyond one tech radar, and it deserves an article of its own. It's the next one in this series: Probabilistic Metrics.

Until then, one question. You've just seen my tool for driving change across several hundred developers. What's yours, and does it scale better than you do?

Yes. Twelve-plus years in, carrying the title Solution Architect, and I was grinding shortest-path algorithms in the evenings like a third-year student before finals.

I'm writing this down because almost nobody at my seniority level admits to it, and the silence creates a myth: that past some invisible line you are beyond being tested, beyond being bad at things, and beyond having to sit down and practise something badly for a while. You're not. And the test, it turns out, is one of the most instructive systems I've ever put myself through, just not for the reasons the recruiters advertise.

The humbling

The first thing the loop teaches you: your title means nothing here. "Solution Architect, twelve years of experience" compresses into one line of a CV that the interviewer skimmed four minutes before the call. The loop doesn't care who I think I am. It cares what I can demonstrate, under pressure, in 40 minutes, in a shared editor with someone watching my cursor.

And there is something bracingly honest about that. Inside a company, seniority accumulates a protective layer: reputation, relationships, past wins that answer questions before they're asked. The loop strips all of it. What's left is just you and a graph with weighted edges.

Algorithms, I discovered, are a language I used to speak fluently and now translate in my head. Exams, early jobs, the first competitive years: fluent. A decade-plus of architecture later, I still read the language perfectly well. But producing it at speed is different. You don't relearn BFS; the concept never left. You relearn fluency. Rebuilding it the second time is slower, stranger, and occasionally insulting to the ego.

I once wrote about the identity split this role produces (Technical Leader — Identity Disorder). Interview prep is that split, sharpened to a point: it forces you to separate "I am senior" from "I can demonstrate X under pressure in 40 minutes." The first is a story. The second is a fact. The gap between those two sentences is exactly where the ego goes to negotiate.

The system behind the loop

Now the part where I stop feeling and start doing my actual job, which is looking at the system.

Big-tech hiring is not designed to measure your worth. It is designed to manage their risk at scale. A loop that processes tens of thousands of candidates optimizes ruthlessly against one thing: the bad hire who gets in. The great engineer who gets rejected is a loss it accepts. There are always more candidates. Rational for them. Brutal for you. Once you see that, a rejection stops being a verdict about your competence and becomes what it actually is: an artifact of someone else's risk function.

There's theater in it too, and everyone involved knows it. Candidates perform "thinking out loud" because the rubric rewards it. Interviewers calibrate against what a "strong hire" is supposed to sound like. Algorithms won as the proxy, and not because anyone believes they are the job. Experience is the thing that matters, and you cannot assess it in an hour. Experience only shows over months. So the industry measures what fits in the slot, and quietly agrees not to mention that it's a proxy. And even the best-calibrated funnel delivers you into the same building where the Peter Principle is patiently waiting upstairs anyway ;)

I don't say this with bitterness. I say it with the professional respect of one systems designer examining another's trade-offs. I'd probably design it similarly, and it would be similarly brutal.

What I gained

The part nobody tells you: the grind pays dividends completely unrelated to the offer.

The fundamentals sharpened my day job. Complexity intuition is an architecture skill wearing a t-shirt. Estimating the blast radius of a fan-out, sensing why a graph traversal in a hot path should scare me, knowing when "we'll cache it" is a real answer. Same muscle, different dress code. A few weeks of deliberate practice tuned instincts I'd been running on autopilot for years.

I became a different interviewer. I've sat on the hiring side of the table for years. After feeling the pressure from the candidate's chair again (the blank second where a thing you know simply won't come out), I redesigned my own interviews. Less performance, more collaboration. Pressure reveals nerves; it does not reveal competence.

Market calibration changed how I behave at work, in the calm way. Knowing what you're worth outside your company removes a quiet fear from every disagreement inside it. Architecture debates stop being existential. You argue on merits, concede gracefully, and push hard when it counts. Your security no longer depends on winning the room.

The mirror

So here's my genuinely private opinion, the one this whole post was building toward: every senior person should run an interview loop once every few years, even if they fully intend to stay.

Not for the offer. For the mirror.

Seniority inside one organization slowly replaces feedback with comfort. It happens so gradually that you never notice the swap. People stop challenging you, because challenging you got expensive. Context does half your thinking before you walk into the room. Your reputation answers questions your skills should be answering. The loop is the one mirror nobody has adjusted to flatter you.

One question to leave you with: when was the last time your competence was tested by someone who had no reason to be polite to you?

If you have to think back more than a few years, that repo full of graph algorithms might be worth creating after all.

The engineering department responsible for all of this is me. After hours. I also have a day job as a Solution Architect.

A few years ago this portfolio would have required a small software house: a couple of backend developers, a mobile developer, a tester, and somebody to herd them. Today it's one architect and a fleet of AI agents. What follows is a field report, not a victory lap. As usual, the failure modes turned out to be the most interesting part of the experiment.

The portfolio that shouldn't fit in one head

The product is Desta, an invoicing platform for the Polish market: a multi-tenant Laravel web application, a native Android app in Kotlin and Jetpack Compose, and two marketing sites for two different audiences. Under the hood sit the integrations nobody builds for fun: KSeF, Poland's mandatory e-invoicing system, where the XML is the legal invoice and the PDF is legally demoted to a "visualization"; a SOAP-based government registry lookup for company data; and JPK tax file generation. Roughly 990 automated tests hold the whole thing together.

One thing I had to learn the hard way: the constraint was never typing speed. The real bottleneck of a company of one is the number of decisions a single head can hold per day. Which schema change is safe. What happens to a finalized invoice when the law changes. Which release goes first. Code was never the scarce resource. Judgment is.

So "operating" the company means almost no typing at all. It means writing specifications, reviewing diffs, and verifying behavior. In Stop Calling It Legacy Code I argued we're moving from engineers who write logic to operators who express intent and judge results. Desta is me testing that thesis with my own evenings and my own money.

The operating model

The setup that makes this survivable has three parts, and none of them is a clever prompt.

Context files as boot loaders. Every sub-project carries its own AI context file: a maintained, code-verified document that tells an agent what the system is, which invariants are non-negotiable, and where the truth lives. One big-picture file routes between them. An agent lands in the polyrepo and navigates it like a well-onboarded hire, minus the three months of onboarding. This is the Knowledge Container idea from the legacy-code article, except now it's not a metaphor; it's infrastructure.

Specs as prompts, versioned like code. Features start as written specifications that double as agent instructions. When the output is wrong, I don't argue in a chat window. I fix the spec file and rerun. The spec is the program; the conversation is just its execution log.

Tests as the trust boundary. The ~990 tests are not there because I'm diligent. They are there because agents don't get faith; they get assertions. Every agent-generated change lands against a mechanical safety net that doesn't care how confident the model sounded.

What breaks first

Now the honest part.

Review capacity breaks before generation capacity. Generating code is effectively free now; my evening attention is not. The bottleneck moved exactly where our transformation data at the day job said it would, and I wrote about that in From Signals to Blips. A company of one doesn't run out of code. It runs out of reviewer.

Trust calibration is the skill nobody teaches. Which diffs deserve line-by-line reading and which deserve test-suite faith? I've settled on a simple rule: anything touching migrations or money gets my eyes on every line. Everything else gets the net. I still get it wrong in both directions, over-reading trivia and under-reading a "trivial" change that wasn't. My most instructive incident so far was an agent that made a red test green by weakening the assertion. The tests guard the code, but somebody still has to guard the tests.

And domain decisions don't compress at all. Tax rules, pricing boundaries, what a correction invoice may reference. These take exactly as long as they took in 2020, because the hard part is understanding consequences, not producing code. AI compresses everything except responsibility.

The moat is not the code

My conclusion after this experiment is uncomfortable for people selling code and comforting for people who know things: one architect plus agents is now a viable software company, for a narrow domain.

The code was never the moat; it's cheaper than ever. The moat is knowing which invoice field the law wants left blank, which government API header actually carries the session, which pricing edge case will generate a support email at 7 a.m. Domain knowledge, encoded into context files and tests, is the entire company. The agents are just very fast hands.

Which means the "I don't have a team" excuse for the product you keep describing at lunch has quietly expired, and I say that as somebody who used it for years and enjoyed it. What replaced it is smaller and much less comfortable: which domain do you know well enough that encoding it into context files and tests would be worth somebody's money? That is the whole company now. Finding my answer took longer than building any of this ;)

I can say this with confidence. I have drawn hundreds of them. As a Solution Architect, diagrams are supposedly my trade. And almost every diagram I've ever produced started lying within a quarter of being finished: without malice, the way milk goes off.

Death by export

Here is the lifecycle of a typical architecture diagram. It is born in a meeting, where it is genuinely useful. It gets polished, exported to PNG, pasted into a wiki page. Then it dies. Not wrong yet, but dying, because the system it describes keeps moving and the picture does not.

draw.io, Lucidchart, Enterprise Architect, and every in-house viewer somebody built once and left running. Different price tags, same disease: the model and the truth live in two different places. Two sources, one guaranteed divergence. The only question is how many sprints it takes.

Reverse-engineering tools attack from the other side. Read the code, generate the picture. Honest, but mute. You can look at the model; you cannot decide anything into it. A one-way street never closes the feedback loop.

Run this audit in your own team: find the diagram labeled "current state" and ask when it last matched the current state. I've written elsewhere that diagrams are conversations, not documentation: their value is consumed in the meeting where they're drawn. This article is about the other half of that thought: what would it take for a diagram to be documentation without rotting?

The code is the model

My answer is a side project I now call Stemma. It was Verso when this essay first went out. The name changed, the bet below did not. So consider this both a design essay and a confession of bias ;)

The core bet: there is no database. None. The architecture model is stored as plain C# records in Git. Bounded contexts, containers, data flows, ownership, risks, decisions. When you open a workspace, the model lives in memory. Then you edit something on the canvas. Rename a container, redraw a dependency, re-parent a module. The tool rewrites the actual .cs files using Roslyn. Not code generation. Code editing.

And one rule overrides everything else in the project: round-trip fidelity. Any edit made in the UI must produce a git diff that contains only the intended change. Rename one element and the diff shows one identifier changed: no reformatting, no reshuffled members, no re-indented block three files away, and no collateral noise for a reviewer to wade through before finding the change. If that rule ever breaks, the tool is broken. Full stop. Fidelity is the only thing that makes the loop worth betting on.

Layout lives in a small committed sidecar file, separate from the model: positions, colours, which elements each view shows, and the zoom somebody left it at. Content and presentation, finally divorced: the separation we've preached for documents for thirty years and somehow never applied to diagrams.

The first name came from bookbinding: the verso is the reverse side of a page, and the canvas was the verso of the code. The name it carries now comes from philology. A stemma codicum is the family tree scholars draw for a manuscript, every surviving copy traced back to one archetype, and that is the shape of the thing: two committed files, every view descended from them. Either way, a diagram cannot drift from the code when the diagram is the code.

Architecture review becomes a pull request

Storing the model as source sounds like a technicality. It quietly changes who architecture belongs to.

An architecture change arrives as a pull request: diffable, commentable, blameable, revertable. That's governance for free, running on muscles every developer already has. No new committee. No new tool to police. And you get git log for your architecture. You can finally ask who moved this capability out of that context, when, and in which commit. I have wanted that in every architecture discussion of my career and never once had it.

The model also outlives tools, licenses, and reorgs, because it is just source files in a repository. Nobody is held hostage by an export format.

Then the effect I did not expect to care about most. One long-living model, projected into audience-specific views: the executive gets capabilities, the team gets containers and flows. Today we redraw the same system five times for five audiences and then maintain five lies instead of one truth.

And agents, which matters more every month. They read and write the same single truth as humans, with no export/import ceremony and no stale copy for the bot. I argued in Stop Calling It Legacy Code that a codebase is a knowledge container; Stemma just extends the container to hold the architecture itself.

When people ask why I'd spend evenings on this, I give them one sentence: a diagram you can't diff is a rumor with better fonts.

Where I landed

After enough years of watching beautiful models rot, I simply stopped believing in any model that a compiler doesn't check.

"All models are wrong, but some are useful." ― George Box

The useful ones, it turns out, are the ones whose wrongness you can still measure. That disbelief nagged me long enough to become a side project. The side project slowly became the tool I wanted as an architect: one long-living model, projected into audience-specific views, versioned like the code it describes. Because it is code.

I don't know yet whether Stemma becomes a real product or stays my favorite workshop experiment. I do know the question it asks is the right one.

So let me pass it on: how old is your "current state" diagram, and would you bet a production incident on it?

What I got was a database migration, new middleware, a rewritten registration flow, and changes to two marketing sites. The change plan touched more than 30 controllers and a test suite of roughly 990 tests.

That afternoon produced the thesis of this post: a pricing page is an architecture diagram wearing marketing clothes. Every box on it is a system boundary. Every bullet point is an enforcement obligation. And somebody has to build all of it.

The model on paper

Desta serves two audiences on one platform, and they could hardly be more different. On one side, end clients. Freelancers and small companies. They want to issue invoices, buy a cheap self-serve plan online, and never talk to a human. On the other, accounting firms: businesses that manage dozens of clients, negotiate, and buy through a sales conversation.

Two audiences, two marketing sites, one codebase. And the separation isn't a slide-deck fiction. It's enforced all the way down to the marketing layer. When one page started attracting the wrong audience, the fix was a permanent redirect: the URL itself now performs audience segregation. Even your SEO is part of the entitlement system, whether you designed it that way or not.

Then come the tiers. Here's the thing nobody writes on the pricing page: every tier boundary is a promise, and every promise needs an enforcement point in code. A monthly document cap means a counter, a quota guard, and a decision about what happens at the limit. A notification allowance means metering. A "this feature only in the higher plan" bullet means a feature flag with a lifecycle. The cheapest tier, meanwhile, is a distribution strategy wearing a price tag, and the codebase subsidizes it with real complexity.

Where pricing bends the code

What surprised even me, and I designed the thing: serving B2C subscriptions inside a B2B multi-tenant architecture forced what I call the master-tenant pattern: individual self-serve clients live as per-user subscriptions inside one shared master tenant, while accounting firms hold classic tenant-scoped subscriptions. Two commercial models, one isolation model. The tenancy design has to keep them from ever bleeding into each other. That is core architecture, dictated entirely by the pricing page.

It goes further:

• Quota guards sit in the request path, counting documents against the monthly cap.
• Read-only mode kicks in when a subscription expires: the system must degrade gracefully, not amputate.
• Downgrades are deliberately blocked, a commercial policy decision compiled directly into middleware.

Commercial policy, compiled into middleware. Read that again, because it's the whole point: the sales strategy doesn't sit next to the system; it executes inside it, on every request.

And then there's the migration tax. Early on, plan identifiers leaked into the codebase the way water finds cracks. Today, renaming a single plan slug means touching 30-plus controllers and views, and re-validating nearly a thousand tests. A pricing change is a schema change. The spreadsheet doesn't know that. The codebase never forgets it.

What the pricing meeting forgets

Which brings me to the organizational half of this story, because Desta is just my one-person laboratory; the same physics applies at any scale.

In most companies, pricing is decided in a meeting where no architect is present. A spreadsheet is blessed and a launch date is picked. The decision then lands downstream as years of constraints in code. Entitlement checks, grandfathered plans, exceptions with exceptions. Architects belong in the pricing meeting, not to set the prices but to price the promises.

Billing is also where edge cases breed faster than anywhere else I have worked. Trials. Proration. The client who downgrades mid-cycle. The grandfathered plan that predates the current model. If you've read my Mathematicians vs. Lawyers, you know the archetype whose home turf this is: billing is the one domain where I want the Lawyer at the table, enumerating every case with a paragraph number. The Mathematician's job is to design a model in which most of those cases cannot exist; the Lawyer's job is to catch the ones that can.

And one hard-won rule: entitlements deserve a bounded context. A dedicated place in the architecture that answers exactly one question: what is this account allowed to do right now? Smear that logic across controllers and views, and you get the worst failure mode software offers: you can't debug revenue. A support ticket that says "client paid but can't issue invoices" turns from a five-minute lookup into an archaeology expedition.

Show me your pricing page

Here's my private conclusion after wiring commercial policy into every layer of a system I fully control, with nobody to blame but myself.

Show me your pricing page, and I'll draw your database schema. The two always converge. They have no choice. One is a set of promises. The other is where promises are kept. The only question left is whether anybody designed that, or whether it piled up the way most of them do: one urgent pricing experiment at a time, each looking like a marketing decision on the day it was made.

So, an exercise for your next architecture review: put the pricing page on the screen instead of the C4 diagram. Walk it boundary by boundary and ask where each promise is enforced.

If the room goes quiet somewhere between "unlimited" and the asterisk: congratulations. You've just found your architecture backlog ;)

It sounds negative. It's the most constructive thing in the repository.

The feature that is absence

The tool itself is deliberately small: a single binary, SQLite by default, no Docker required, a hard budget of about 5,000 lines of Go, and eleven ADRs explaining the boring choices. It is not trying to compete with Calendly or Cal.com. They have funding, teams, and ecosystems. It competes with their narrow case: one professional, one website, one booking flow they want to own end-to-end.

Every absence in that description is a decision, not a gap. No team features means no roles-and-permissions tree, no admin screens, no invitation flows. No billing integration means no webhook forest and no PCI anxiety. No video conferencing means no vendor SDK whose breaking changes become my weekend.

The absences even select the audience. The secondary persona in the vision doc is the senior engineer who self-hosts everything and will only adopt a tool that stays small. For them, "no Docker required" is the pitch.

A feature list tells you what a product does. The anti-feature list tells you what it is. Constraints are the taste. Anyone can add; the identity lives in what you refuse.

Rejection, written down

The anti-personas are specific, and that specificity is the whole trick. A 50-person sales team needing round-robin assignment: not our user. A recruiting org wanting in-app video interviews: not our user. Anyone hoping for a free tier with an upgrade path: there is no business model, this is a tool, so also not our user.

These are real people with valid needs, and they will happily pay somebody. They are simply someone else's users. Writing that down feels almost rude, which tells you exactly how rarely we do it.

Watch what each rejection buys. Kill round-robin and you never implement availability-merging across calendars, fairness algorithms, or the admin UI to configure them, plus every bug report at the intersection of all three. One anti-persona kills an entire tree of future edge cases before it sprouts. The cheapest code review is the one for code that never got written.

And feature triage becomes almost mechanical. Every incoming idea answers one question. Which persona is this for? That includes my own ideas at 2 a.m., when everything seems like a good one. If the answer is an anti-persona, it is a clean no. Painlessly. Nothing personal; it's in writing.

The corporate mirror

This is where the side project starts explaining the day job.

In Mathematicians vs. Lawyers I described the edge-case explosion: specification documents swelling to hundreds of cases that nobody reads in full. I blamed corporate culture's inability to say no. The scheduler taught me the same lesson from the other side. The explosion doesn't happen because anyone is careless. It happens because a product company cannot refuse anyone. Every exception is revenue. Every "no" needs a VP's spine behind it. Every accepted special case is one more branch in the system, and no incentive structure on earth rewards the person who turned down money.

A solo project can refuse everyone. That is its superpower: not the tech stack, not the single binary, not the artisanal ADRs. The economics of "no" are simply different. At home, refusing costs nothing; at work, it costs a fight.

Which is exactly why organizations shouldn't dismiss this as hobby-scale wisdom. Two practices copy over directly. First, anti-personas as first-class strategy artifacts. Written, named, and signed by someone with authority. Then "we don't serve this segment" is a document, not a rumor that dies in the next QBR. Second, absence-of-feature as a decision with an owner: an ADR for the thing you deliberately didn't build and why, so the next PM inherits the reasoning instead of innocently reopening the trapdoor.

I've watched million-euro complexity enter systems through the simple absence of a written "no". The document would have cost an afternoon.

Practicing "no" where it's free

My private conclusion is this: the ability to say no is the scarcest architectural resource I know, scarcer than senior engineers, scarcer than budget. And like any scarce skill, it atrophies without reps.

Side projects are my gym for refusal. Every anti-persona I write at home, every feature I decline with a one-line reference to the vision doc, is a rep. Those reps are what keep the diplomatic, watered-down, corporate-compatible version of my "no" from collapsing when a stakeholder leans on it.

The gym matters because of the transfer: the refusal I practice on a scheduling tool nobody uses yet is the same muscle I need in a room where somebody very senior is explaining why this one exception is different, and there is no way on earth to train it inside that room. So I train it in the repo. Write the anti-personas while refusing is still free. Get a signature on them before it isn't.

Building Desta, my invoicing platform for the Polish market, means integrating with three government systems: KSeF (the mandatory national e-invoicing API), the public company registry with its SOAP interface, and the JPK unified tax files. A quick disclaimer before we start: this is an engineering story, not tax advice. Please keep paying your accountant ;)

The spec you cannot refactor

Tax law is an upstream dependency with no negotiation channel. You cannot file an issue against a statute. You cannot suggest a breaking change be batched into the next major version. You implement what the paragraph says, and the paragraph doesn't care about your domain model.

Two examples that changed how I think about requirements.

First: in KSeF, the XML is the legal invoice. The PDF (the thing every user believes is "the invoice") is legally just a visualization, and has to be labeled as one. Think about what that does to your architecture: the artifact your users see and print is a derived view; the artifact almost nobody reads is the source of truth. Get the relationship backwards and you've built a very pretty bug.

Second: invoice rows with certain VAT exemptions must render the VAT column blank. Not "0.00". Not a dash. Blank. A one-pixel difference that is a legal requirement, not a style choice. There is no elegant abstraction that makes this go away; there is only encoding it correctly and pinning it with tests named after tax scenarios.

I wrote in Mathematicians vs. Lawyers about two thinking archetypes: the modelers who dissolve edge cases by reshaping the model, and the rule-thinkers who enumerate them. Well, this is the domain where the Lawyer archetype simply wins. Every edge case here has a paragraph number attached. My instinct is to find the model that makes exceptions disappear; in compliance work, the exceptions are the model.

"Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away." ― Antoine de Saint-Exupéry

The state has never read it.

SOAP, sessions, and the state

Now the part everyone loves to mock: the technology.

The company registry speaks SOAP in 2026. The session ID travels in a custom HTTP header, not a cookie. That detail alone costs every integrator an afternoon of their life. The field for a building number has a bureaucratic Polish name that no autocomplete will ever guess. The documentation is a versioned PDF.

The inconvenient truth: it all works. The same requests produce the same responses, year after year. My integration code for that registry is the least-touched code I own.

KSeF authentication is a small choreography: fetch the public key, request a challenge, encrypt your token and a timestamp with RSA, redeem the result for a session. Is it elaborate? Yes. Is it security theater? Partly, perhaps. But it's documented choreography. You implement it once, wrap it, and forget it exists.

That word, "wrap", is the architectural lesson. This is where the anti-corruption layer stops being a conference slide and starts earning its keep. The government's model, its vocabulary, its SOAP envelopes and bureaucratic field names get translated at the boundary, once, in one place. My domain never learns what the ministry calls a building number. The state stays outside; the model stays clean.

Lessons for architects raised on REST

If your entire career has been JSON over HTTPS with a v2 in the path, integrating with the state is a masterclass in things our industry forgot.

Stability is the feature. These APIs change less per decade than a typical startup API changes per quarter. Deprecations are announced by legislation, with timelines measured in years. Meanwhile I've integrated with modern SaaS APIs that shipped three breaking changes in a year, each announced in a changelog nobody reads.

Compliance is a bounded context. It has its own language (the statute's, not yours), its own tests (named after tax scenarios, not user stories), and its own release rhythm: the calendar of the state, not your sprint. Treating it as "just another feature" is how compliance logic ends up smeared across a codebase.

The reference implementation is the real spec. The ministry publishes reference client SDKs, and reading them is archaeology. You dig through layers to learn what the API actually expects, as opposed to what the PDF implies. Archaeology beats guessing. I made a similar argument in Stop Calling It Legacy Code: old code is a knowledge container. Government reference code is the same idea at civilizational scale: decades of edge cases, fossilized and readable.

Ugly, documented, stable

Complaining about government APIs is the cheapest joke in engineering, and I've told it myself. But after a year of running production integrations against them, I have to report something embarrassing: I trust these contracts more than most microservices I've met in my career.

They are ugly. They are documented. They are stable. Two of those three qualities are the ones that actually matter, and they're not the one we keep optimizing for.

So, a question for your next architecture review: which of your internal APIs would survive being frozen for five years? Because the ministry's would. And did.

Eleven ADRs. Zero users. Colleagues have laughed at that ratio and I get it. Writing formal decision documents for a project whose entire engineering department is one guy in the evenings looks like corporate cosplay. I'm going to argue the opposite: that ratio is correct, and the reasoning applies far beyond hobby projects.

The stakeholder with amnesia

The awkward truth about solo projects: you are not one person. You are a sequence of people wearing the same face, and they don't talk to each other. Never have.

There's the me who chose the chi router over the more popular frameworks. The me who decided SQLite is the default and Postgres just an adapter behind an interface. The me who picked sessions plus TOTP. Not an identity provider. Each of those people had context: benchmarks skimmed, trade-offs weighed, constraints that were obvious that week.

And then there's future-me. Future-me is a genuine stakeholder, one with amnesia. He opens the repo after three months away, finds a decision he doesn't remember making, and immediately starts distrusting it. Why is there no ORM here? Was I lazy, or was I smart? Without a record, he cannot tell. And an engineer who distrusts his own codebase starts rewriting things that were never broken.

The economics are absurdly lopsided. An ADR written on the day of the decision costs ten minutes. Reconstructing the reasoning a year later costs an afternoon, and the reconstruction is usually wrong, because you rebuild yesterday's decision out of today's knowledge. Eleven ADRs before the project is even feature-complete are the project's memory, and the only memory that survives the gap between evening sessions.

Writing it down changes what you decide

The bigger surprise was what ADRs did to the decisions themselves.

Every ADR template carries one quietly brutal section: alternatives considered. That is the whole trick. You cannot fill it honestly without laying the options side by side, in daylight. And in that daylight, a certain kind of decision dies: the resume-driven one. Try writing "Alternative B: the boring technology that fits the problem perfectly. Rejected because: I wanted to play with Alternative A", then signing your name under it. The template forces the question every architect should ask and rarely does: do I want this technology, or does the problem?

Two more effects I didn't expect:

• Timestamped context. An ADR records what was true and known at decision time. When the world changes (and it will), the record protects past-you from unfair judgment, and tells present-you exactly which assumption expired.
• Deferred decisions stop haunting you. One of my eleven ADRs decides not to decide: a query-codegen library that looks attractive, postponed until the hand-written SQL layer actually hurts, with a written trigger for revisiting. Before ADRs, that would have been ambient anxiety, a tab left open in my head. Now it's a documented "not yet" with an alarm attached.

There's a wry pleasure in noticing that the discipline works precisely because nobody is watching. No committee to perform for, no reviewer to impress. Just the decision and me, on paper ;)

From hobby repo to boardroom

Now scale it up, because this is where it stops being a solo-dev quirk.

An ADR log plus one named decider is the cheapest governance stack that exists. No tooling. No steering committee. A folder of text files and a name. Organizations design their systems obsessively and leave the decisions about those systems undesigned. I wrote about that in Decisions Have an Architecture Too. The ADR is the smallest fix I know for that gap. It does nothing to make decisions faster. It simply makes them exist: a question somebody outside the room can raise, a record somebody not yet hired can inherit, a position the author can defend, and a date saying when all of it was still true.

When I want to judge the health of a team, I ask for their decision log before I read a line of their code. A living log full of honest alternatives tells me more than any maturity assessment. An empty one tells me the architecture lives in somebody's head. Heads get promoted. Heads get poached.

And there's a reason for this practice that didn't exist when the ADR format was invented. Agents read our repositories now. Code tells them what the system does; only decision records tell them why: which constraints were real, which paths were rejected and on what grounds. Decision reasoning is precisely the thing a model cannot infer from source, no matter how good it gets. My eleven small markdown files turn out to be premium context for every future agent, and every future human, working in that repo.

An audience of one

So yes: eleven ADRs, zero users, and I'll write the twelfth tonight without a trace of embarrassment.

Over the years I have arrived at a personal rule. My side projects are where I enforce it hardest, precisely because nobody is watching. If a decision isn't worth writing down, it was a mood.

Moods are fine. I've shipped plenty of good code on moods. But a mood can't be reviewed, can't be inherited, and can't defend itself six months later.

Open your most important repository and try to find where its five biggest decisions are written down. Not the code that implements them, the reasoning that produced them. If it isn't in the repo then it is stored in a person. That storage medium gets promoted, poached, and eventually hands in its notice with two weeks' warning and a leaving card.

Mine live in a folder. It took ten minutes each.

I've been collecting that silence ever since.

Early in my career I believed seniority meant having answers: fast, confident, preferably with a diagram. A dozen years in, I measure my weeks differently: by the quality of the questions I managed to ask before the answers got expensive. That one I'd defend in any review.

The question list is a deliverable

Every solution design I ship travels with a companion artifact: an open-questions file. Beyond that, I maintain separate documents with titles like "architecture questions to product". They are versioned, statused (open, answered, overtaken by events), and reviewed with the same seriousness as any diagram. Colleagues occasionally find this odd. Aren't architects paid for answers?

Here's the asymmetry that convinced me otherwise. Answers age badly. An answer encodes the constraints of the day it was written: the team's size, the vendor's pricing, the traffic profile, what the organization believed that quarter. Constraints rot silently, but the answer keeps getting repeated, confidently, like a cached value nobody thought to invalidate. Some of the most dangerous sentences in engineering start with "we already decided that."

Good questions do the opposite: they compound. "Who owns this after go-live?" produces fresh truth every single time you re-ask it. "What happens when these two sources disagree?" outlives reorgs, migrations, and three generations of diagrams. An answer is a snapshot. A good question is a probe you can re-run.

That's why the question list deserves version control. It is the only artifact I produce whose value reliably grows with time.

Two kinds of questions

Now the craft, because not everything with a question mark is a tool.

The first kind exposes hidden assumptions. "What must be true for this design to work?" "Who pays when this fails at 2 a.m.?" "Which of these arrows is a wish and which is a contract?" These questions are cheap before the design is approved and brutal after go-live. Their entire value is in the timing. They tend to be short, slightly uncomfortable, and impossible to answer with a framework name.

The second kind performs seniority. The gotcha delivered for the audience. The technology flex ("have you considered Kafka?") asked not to learn but to be seen knowing Kafka exists. The fifteen-minute "question" that is actually a speech with rising intonation. You know the one. This kind produces no design changes, only defensive meetings.

My test is simple: would I still ask this question in a one-on-one, with no witnesses? If yes, it's a probe. If it only makes sense with spectators, it's theater. I've written before about how much of corporate life already is (Data-Driven Theater).

One more piece of craft: a question without an owner and a check-back date is not a tool, it's a sigh. "Someone should clarify this" has never once, in my experience, resulted in someone clarifying anything.

Open questions as an honesty mechanism

The deepest value of the question list is what it does to trust.

Every solution design of mine ends with an "Open Questions" section: the things I don't know, stated before someone else discovers them for me. It felt exposing the first few times. It turned out to be disarming. A review of a "complete" design is a hunt: reviewers win by finding holes. A review of a design with three declared holes is a search party: the reviewers join you, because you've already conceded the interesting part (that holes exist) and named where you think they are.

Declared uncertainty, I keep relearning, builds more credibility than performed certainty ever did.

Years ago, in Technical Leader — Identity Disorder, I leaned on Socrates while untangling my own role. I've since stopped treating "I know that I know nothing" as philosophical decoration. It's a working method, and the open-questions file is its production implementation. Confidence is not the absence of open questions. Confidence is knowing exactly which questions are open.

Which is why an empty Open Questions section in a big design is, for me, a red flag with a siren attached. If you can't name three things you don't know about your own architecture, that's not completeness. That's the first open question.

Try it

A small experiment for your next design document. Add an "Open Questions" section with at least three honest entries, each with an owner and a date to check back. Mine look like this:

[open]      Who owns this number after go-live?        → <name>, check back <date>
[answered]  What happens when the two sources disagree? → see the decision record
[overtaken] <the question a reorg answered for you>     → close it, keep the scar

Then watch what the review becomes.

"Who owns this number after it's published?" is still on my list. It has never come back with the same answer twice, which is the only test I have found for whether a question is worth keeping, and it is a better test than whether the question made anybody in the room look clever at the time. Collect the ones that sting. Sharpen yours.

What the layer actually protects

A quick refresher for the non-DDD crowd. An anti-corruption layer sits between your system and an upstream system whose model you do not control: a legacy platform, a vendor API, another team's service. Its job is translation: their concepts arrive, get mapped into your language at the border, and only then touch your domain.

The name is the important part. Evans didn't call it "adapter" or "facade". He called it anti-corruption, because that is what it prevents. And here is what most teams get wrong: the layer protects your model's integrity, not your API. The danger was never that a remote call fails; you have retries for that. The danger is that their status = 7, their nullable-everything contract, their subtly different definition of "customer" starts living inside your entities. You import one convenient enum today, and six months later your code speaks two languages, neither of them fluently. Every feature after that pays the tax.

Is the extra hop always worth it? Honestly, no. Translation costs: another mapping class, more tests, and a guaranteed "why this indirection?" comment in code review. If the upstream model is stable, close to yours, and read-only, map it directly and move on. The layer earns its keep in three cases, and they are worth naming separately because teams usually notice the third one long after it has already cost them a quarter of rework. The upstream model keeps changing. Its language contradicts yours. Or you catch yourself sprinkling if (theirType == LEGACY_B) across your domain logic. That if is the corruption, already inside. Not a warning of it. The thing.

Semantic corruption, human edition

Now watch the same mechanism run on people.

Teams import each other's vocabularies exactly the way codebases import foreign enums: silently and wholesale. The channel isn't an API; it's a shared spreadsheet, a copied ticket, a slide lifted from another department's deck. A word walks across the boundary ("account", "assessment", "active") carrying someone else's model inside it, and nobody inspects the luggage.

I've written before that most "data-driven" fights are really collisions between semantic contracts nobody wrote down (Data-Driven Theater). This is how those contracts get broken in the first place. A term optimized for sales, with sales' compromises baked in, becomes an engineering domain term. A status that conflates two different situations gets copied into three more teams' backlogs. The breakage replicates through the organization precisely like corrupted records through an unvalidated pipeline.

Nobody decides any of this. That is the point. Corruption rarely announces itself; it arrives one borrowed word at a time.

Translate or unify, but never "just align"

So what do you do at a boundary, human or technical? You have exactly two honest options.

Adopt a genuinely shared model when the concept is core to both sides and you are prepared to co-own its evolution. This is the ubiquitous-language dream, and it is expensive: shared definitions need governance, a change process, and someone empowered to say no. Reserve it for the handful of concepts that deserve it. This is model work (relations, constraints, evolution), the level I argued architects should stay at in Mathematicians vs. Lawyers.

Translate at the boundary when the other side's model is legitimately theirs: owned by them, stable, optimized for their world. Keep a glossary. Better yet, keep a translator, a person who consciously maintains the mapping and can say out loud that "their 'client' is our 'buyer', except during trials". A named, human anti-corruption layer. It feels like bureaucracy. It costs one page and saves quarters.

The trap is the third option, the one everyone reaches for first: "let's just align the teams." It sounds cheap. It is the most expensive item on the menu. Alignment means permanent joint ownership of a language, so every future change to the concept now requires both parties, forever, including the parties who will inherit it after the next reorg and were never asked. Most teams that "aligned" in a two-hour workshop actually just adopted whichever vocabulary was spoken loudest, imported its bugs along with it, and called the result consensus.

Choose deliberately: unify what is core, translate what is foreign, and never leave a boundary unmanaged just because the two teams happen to like each other. Friendship is not a data contract.

The audit

A small exercise for your next quiet Friday. Pick the three most central words on your team's diagrams. For each one, ask: where did this word come from? Does it mean the same thing one department over? And if it doesn't, who is doing the translation?

If the answer to the last question is "nobody", congratulations. You have just located the exact spot where your model is importing someone else's bugs, free of charge, on a daily schedule.

I stopped asking teams to align. Now I ask who translates. That is a smaller question and a much easier one to answer honestly, because the answer has a name in it and alignment never does. The person who says "that's our word, not theirs" is doing architecture, whatever their title says. Every domain word has an accent. The useful part is knowing whose.

I have contributed to such folders. I have created such folders. So take what follows as private observations, not science, but observations from both sides of the crime scene ;)

Here is the conclusion those folders eventually forced on me: organizations don't fail migrations. They fail to start them. The industry loves horror stories about big migrations that went wrong. Honestly, I've seen far more damage done by migrations that never left PowerPoint.

The options-collection ritual

The mechanism looks thoroughly respectable. A migration is clearly needed: the old platform hurts, everyone agrees, nobody objects. So we do the responsible thing: we analyze. We produce a comparison matrix. Options, strengths, weaknesses, costs, risks.

Then the quarter ends, priorities wobble, and the document goes to the folder. Next quarter someone reasonably notes that "the market has moved" (the market has always moved) and commissions a refresh. A new document is added. Nothing is ever subtracted.

This is analysis as a socially acceptable form of postponement. Nobody ever got fired for producing a comparison matrix. Producing one feels like progress, reads like diligence in a status report, and carries none of the personal risk of an actual decision. The ritual has all the ceremonial properties of work (effort, artifacts, meetings) with none of the consequences.

And every refresh resets the clock. You can postpone anything indefinitely if you re-analyze it at the right frequency.

Decision debt

We track technical debt in backlogs. We track risks in registers. The compounding cost of not deciding is tracked exactly nowhere, and it's often the largest item on the invisible balance sheet.

Because while the decision waits, the old platform doesn't wait with it. Every sprint adds new integrations to the thing you intend to leave. Every new feature is another consumer of the legacy contract, another strand in the net that will have to be cut later. The migration doesn't get cheaper while you analyze it. The price of "not yet" is invoiced monthly and itemized never.

There's a human line item too, and it compounds faster than the technical one. The third time a migration is announced and doesn't start, teams stop believing announcements. Engineers who prepared for the move file the experience under "management noise." So the zombie migration does not only burn analysis budget. It devalues every future promise leadership makes, including the real ones, including the ones with money behind them, and including the one somebody will need people to believe two years from now. Including the one that finally gets funded two years from now, and arrives to a room that has learned not to move until it sees a merged pull request. That currency does not come back at the next all-hands.

One-way doors, two-way doors

Amazon popularized a genuinely useful question: is this decision a one-way door or a two-way door? Irreversible decisions deserve slow, heavy scrutiny. Reversible decisions deserve speed; the cost of a wrong reversible decision is just the walk back through the door.

Now look honestly at a migration. Routing one endpoint through the new service: reversible. Dual-writing to both data stores: reversible by design. Moving one read path, one team, one low-risk workload: two-way doors, all of them. The overwhelming majority of migration steps can be undone with a config change and a mildly embarrassing standup update.

Yet the organization treats every step as a bet-the-company moment. Why? Because the migration was framed as one giant decision. "We are moving to X." That framing is a one-way door, socially if not technically. Nobody wants to personally own the giant door, so everybody keeps studying the hinges.

The trick is almost insultingly simple: stop deciding the migration. Decide the next step. Decompose until every step is a two-way door, then walk through the first one.

"A complex system that works is invariably found to have evolved from a simple system that worked." ― John Gall, Systemantics

What actually unblocks

Three things, in my experience, and none of them is another analysis:

1. A timebox on the analysis. Options expire like milk. Decide by a date, not by certainty, because certainty is not coming. It never was. An 80%-informed decision this quarter beats a 95%-informed decision that will never be made.
2. A named decider. Not a committee, not "alignment," one accountable person. Consensus is where migrations go to die; a name is where they wake up. I've written more about decision rights in Decisions Have an Architecture Too.
3. A first step too small to refuse. One endpoint, one consumer, two weeks, fully reversible. Impact is beside the point. Its job is to convert the migration from a document into a fact, because facts attract budget, volunteers, and momentum in a way folders never do.

A failed migration at least produces knowledge: you learn where it breaks, what it costs, who steps up. A migration that never starts produces only documents, plus a slow, expensive lesson in how little your organization's announcements are worth.

So, one honest question: which folder in your document storage is quietly approaching its fifth birthday?

Don't refresh it this quarter. Pick the smallest reversible step it describes and open door number one.

A few years later I stood at a whiteboard with a marker I had to shake to make work, drew four crooked boxes, and before I finished the fifth a senior developer interrupted: "That's not how it flows. The events go through the queue first." Twenty minutes of arguing later, we had discovered that two teams held two different mental models of the same integration, and had been building against both.

The crooked boxes did more for the architecture than the three-evening masterpiece ever did. It took me embarrassingly long to understand why, so let me save you the time: a diagram's value is consumed in the meeting where it is drawn. What survives the meeting is a receipt.

The half-life problem

Polished enterprise-architecture diagrams are dead on arrival. Not because they're wrong on day one, but because the system starts drifting away from them on day two, and no contract of maintenance was ever signed. Everyone wants diagrams to exist; nobody has "update the diagrams" in their sprint. Nobody ever will.

Run this audit in your own organization: ask a team to show you their "current state" diagram, then watch the eyes. The honest answer is always some flavor of "current as of the workshop we ran in spring." We don't version diagrams. We hold funerals for them, quietly, by never opening the file again.

Meanwhile the messy whiteboard photo from that one heated session keeps getting reposted in chat threads for months. Not because the sketch is good (it objectively isn't). Because everyone who was in the room remembers the argument it hosted. The picture is a bookmark for a shared understanding. People who weren't there see boxes; people who were see the conversation. That gap is the whole point.

One diagram, one question

The everything-diagram is the most common failure I see: one canvas trying to answer every question about the system, and therefore answering none. Fifty boxes, four zoom levels, a legend that needs its own legend.

My working rule is brutally simple: one diagram, one question. Scope every drawing to the single decision it must support. "Should checkout call inventory directly or go through events?" needs five boxes. It does not need your cluster topology, and it absolutely does not need the boxes that are only there because leaving them out felt impolite.

Anything that doesn't influence the decision is decoration, and decoration invites feedback about decoration. You wanted a call on the integration pattern; you got forty minutes on whether the auth service should also be pictured.

One small trick changes everything: title the diagram with the question, not the system. "Where should risk aggregation live?" starts a very different meeting than "Platform Overview v7."

Draw live, don't present

The pattern I trust most costs nothing: draw the diagram in the meeting, badly, in front of everyone.

A finished diagram triggers politeness; people approve documents. An unfinished diagram triggers honesty; people cannot stop themselves from correcting a sketch. And the moment someone says "that arrow is backwards" is the exact moment your architecture is being validated, for free, by the people who know the ground truth. There is no cheaper review process on the market.

I'll admit why I resisted this for years: presenting polished work is a way of performing competence. Drawing crooked boxes in public feels junior. It isn't. It takes considerably more seniority to be visibly unfinished in a room than to be privately perfect ;)

The practical version: come with the question written at the top, draw the first three boxes yourself, then hand over the marker, literally or rhetorically. "What am I missing?" outperforms "any questions?" every single time.

The AI twist

And now the part that changes the economics of all of the above. AI agents will happily generate a C4 diagram, a sequence diagram, or a dependency graph from a paragraph of text: on demand, in seconds, regenerated whenever the code changes. The mechanical act of drawing, the thing that used to cost me three evenings, now costs approximately nothing.

Which exposes what was true all along: the scarce skill was never the drawing. The scarce skill is choosing what to show: which question, at which altitude, for which audience. An agent can render fifty boxes flawlessly; it cannot know that this particular room, on this particular Tuesday, needs exactly five of them and one uncomfortable arrow.

Diagram-as-artifact is deflating fast. Diagram-as-conversation is appreciating. Plan your skills portfolio accordingly.

So, a small experiment for your next design review: don't bring the finished diagram. Bring the question, an empty canvas, and the willingness to be corrected in public.

A marker you have to shake to make work is optional. In my case it helped.

Silence. Then everyone answered at once, each about their own piece. One squad owned the data ingestion. Another owned one of the sub-scores feeding the aggregate. A third owned the screen where the final number is displayed to the customer. The number itself (the thing customers actually look at, the thing sales sells and support gets called about) was owned by nobody.

It took three meetings to establish that. Not because anyone was hiding. Everyone genuinely believed someone else had it.

What follows is a pattern I've seen too many times to ignore.

The org chart produces parts

We assign ownership by component, because components map neatly onto teams. A squad gets a service, a database, a screen. Clean boundaries, clear accountability, everyone can draw their box. So far, so good.

But the most valuable outcomes an organization produces are not components. They are sums: the aggregated score, the end-to-end response time, the coherence of the user experience, the total cloud bill. A sum, by definition, crosses boxes. And whatever crosses boxes on an org chart falls between them.

Conway's law is usually quoted about system design: your architecture will mirror your communication structure. There's an ownership corollary that gets much less airtime: an org chart can produce parts, but it cannot produce wholes. Wholes need an owner that the chart does not naturally generate. Someone has to create that role on purpose.

Nobody plans an orphan. An orphan is simply what's left over after everyone finishes claiming what's theirs.

How to spot one

Orphaned aggregates don't announce themselves. They surface as symptoms, and every symptom looks like something else:

• The ping-pong ticket. A cross-squad bug bounces between teams, each proving, correctly, that their part behaves as specified. Every part worked; the sum was wrong. The ticket ages until a frustrated customer escalates it past all of you.
• The decision that waits months. Changing a whole requires a yes from everyone who owns a part. A yes from everyone is, in practice, a yes from no one. So the improvement idea circles the organization like luggage nobody claims.
• The invisible roadmap item. Aggregate improvements appear on no backlog, because no backlog hosts them. Each squad's roadmap is full, full of parts.
• The human failsafe. The only owner is a veteran who remembers how the whole thing fits together. That's memory rather than ownership, and it resigns when they do.

Recognize two of these and you have an orphan.

The architect's move

Where I've landed on what a solution architect should do about it is less heroic than you might hope.

Name the orphan out loud. This sounds trivial and isn't. As long as the aggregate has no name, its non-ownership is invisible; there is literally nothing to point at. The moment you name it ("the overall score", "the end-to-end latency budget", "the network aggregate") the question who owns this? stops being unaskable and becomes merely awkward. Awkward is progress.

Then force an explicit decision. Not make it. Force it. The architect's job is to put the organization in a position where not deciding is the visible, embarrassing option. Getting from "we should discuss this" to a named owner is a craft of its own, and I wrote about that machinery separately in Decisions Have an Architecture Too.

Sometimes the honest answer to that decision is a role nobody has yet. Occasionally an existing squad's charter genuinely grows to cover the sum. More often you end up creating something that didn't exist before: a capability owner, a small platform team, a named service with a named human. Read that as the org finally matching what it sells.

And one warning from experience. The default answer in the room will be: "the architect can own it." Refuse politely. Architecture must not become the attic where the organization stores what it doesn't want to decide about.

Components get owners; sums get hopes. The whole game is converting one hope at a time into an owner.

Try it on your own system

Here's a 15-minute exercise that costs nothing. Walk your value stream end to end, from the first customer click to the last invoice, and count the things that everyone depends on and no one owns. The aggregate score. The overall latency. The consistency of terminology across screens. The total cost of the pipeline.

My prediction: you'll find at least three. Every organization I've looked at has them, because org charts are made of boxes and value is made of sums.

I do that walk now before I draw a single box on a new engagement, which is a habit I picked up the expensive way, by accepting a couple of these orphans myself and finding out that the flattery wears off in about a week while the babysitting does not. The orphans are always there. What changed is that I stopped being surprised by them, and started naming them in the first week instead of the third meeting ;)

The fourth workshop never happened. We assigned letters instead. More on the letters in a moment.

As architects we obsess over system design: boundaries, contracts, failure modes, who calls whom. Meanwhile the decisions about those systems, often worth more than the systems themselves, happen with no design at all. Whoever speaks loudest, or last, or closest to the deadline, wins.

The meeting that cannot decide

Here's the anatomy of a stalled architecture decision, and I bet you've lived it.

A question appears: who owns X, do we build Y, do we retire Z. A meeting is called. Smart people attend and say smart things. Somewhere near the end, someone summarizes "so we're aligned", and everyone nods, each person having heard a slightly different decision. Two weeks later the topic is back, re-litigated from scratch by whoever wasn't in the room.

The root cause is almost never missing information. It's that nobody knows who actually decides. A decision made by a meeting belongs to no one, so it evaporates the moment the meeting ends. Un-deciding it costs nothing, because deciding it cost nothing.

We would never build a system where any service can silently overwrite another's data. Yet we run decision processes where any sufficiently senior passer-by can overwrite last month's conclusion.

RAPID, in plain words

The letters that saved us from workshop number four come from Bain & Company: RAPID (their trademark, their consultants will be pleased I said so). Strip away the consulting varnish and it's simply an API contract for decision-making:

• R: Recommend. The person who does the analysis and brings a concrete proposal. Not a vibe, a proposal.
• A: Agree. The few whose formal sign-off is required (security, compliance). A veto with named grounds, not a mood.
• P: Perform. Whoever will do the work. They get a voice before the decision, not a surprise after it.
• I: Input. People consulted because they know things. Consulted, not obeyed.
• D: Decide. One name. Not a committee, not a forum, not "the leadership". One name.

Five letters, one rule: every letter is a person, and D appears exactly once.

Writing the letters down is what changed the behavior; the framework did nothing on its own. Our ownership dispute that survived three workshops was resolved in days once the letters existed. The R stopped selling to the whole room and wrote one decent document. The I's gave input without needing to "win". And the D, suddenly aware the decision was theirs with their name on it, asked sharper questions in one meeting than the previous three had produced in total.

Nothing about the problem changed. Only the architecture of the decision did.

The anti-patterns

Once you have the vocabulary, you start seeing the broken decision architectures everywhere.

Everyone has a veto. The A role inflates until half the org can block and nobody can approve, which is a system where every component can halt the pipeline and no component can ship it. The result is decision starvation with extra meetings.

Consensus theater is the harder one to name, because from the inside it looks like respect. The meeting is formally seeking a decision while what it wants is unanimous comfort, so it waits not for the best argument but for the last objection to get tired. I've written about the staged version of data-driven meetings in Data-Driven Theater. Consensus theater is its twin: same stage, different prop.

Then the alignment ritual. "Alignment meeting" is frequently the phrase an organization uses when nobody is willing to say "I decide." Alignment is a wonderful outcome and a terrible process goal: you align around a decision, not instead of one.

None of these people are acting in bad faith. That's the uncomfortable part. Each anti-pattern is locally rational: vetoes feel like diligence, consensus feels like respect, alignment feels like collaboration. The system produced by these good intentions cannot decide anything.

"No matter how it looks at first, it's always a people problem." ― Gerald Weinberg, The Secrets of Consulting

ADR records what, RAPID records who

Architects already have a beloved decision artifact: the ADR, the Architecture Decision Record. I write them, I love them, I make agents read them. But an ADR documents what was decided and why. It says nothing about who had the right to decide it, and whether they actually did.

The two are complements, not competitors. RAPID (or any explicit decision contract; the brand doesn't matter) defines who; the ADR preserves what. Pair them and decisions become durable: made once, by a named person, with named input, written down.

Skip the first half and you get my favorite one-liner from this whole experience: an ADR without a decider is a wish with a timestamp.

One question instead of one more meeting

So here's my practical suggestion. Next time an architecture decision stalls, bouncing between forums and gathering workshops like a hobby, don't schedule another meeting. Ask one question, in writing, where everyone can see it:

"Who is the D on this?"

If the answer comes quickly, you'll have a decision within days. If the answer is silence… congratulations, you've found the actual blocker, and it was never the technology.

Start with the oldest one. Every organization is carrying a question that has been circling for a year, gathering forums. It is circling because no one has ever been named to end it. That also makes it the cheapest thing on your list to unstick.

I have lost count of how many meetings I've attended that were officially data-driven. There was a deck. There were charts. At some point somebody said "the data clearly shows." And yet, walking out, I couldn't shake the feeling that I had just watched a performance, not a decision.

"There are three kinds of lies: lies, damned lies, and statistics."

Mark Twain popularized that line and attributed it to Benjamin Disraeli. Historians still can't confirm Disraeli ever said it. I love that detail: the most famous quote about misleading statistics ships with a broken attribution. Even the quote about data lying is a matter of interpretation.

Same words, different worlds

Here is my core observation: making decisions based on data makes sense only when the organization speaks the same language, built on the same concepts.

Take something as innocent as "active user." For the product team it's anyone who logged in this month. For sales it's a paying account. For support it's someone who opened a ticket and is still breathing. Now put all three in one room, each armed with a chart about "our active users," and enjoy the show. Everybody is right. Everybody is talking about a different universe.

As a solution architect, I spend a large part of my life on contracts between systems. We version APIs, we validate schemas, we break builds when a field changes its meaning. And then we walk into a meeting where two departments compare numbers built on definitions that were never aligned. These are semantic contracts between people that nobody ever wrote down. Being data-driven is empty if those contracts were never seriously considered. The dashboard is just the visible tip of an agreement that doesn't exist.

The preprocessing trap

"If you torture the data long enough, it will confess to anything."

That one is usually pinned on economist Ronald Coase, also in a paraphrased form, because apparently we can't even quote people about data accurately.

Here's the uncomfortable part: data is surprisingly easy to manipulate, and you rarely need to lie in the data itself. The comfortable place to cheat is earlier, in the preprocessing phase. Which rows were dropped as "invalid"? Which period was chosen as "representative"? Which outliers were "obviously" errors? Every one of those choices is invisible in the final chart. Nobody signs them.

That's why I believe explaining how a dataset was cleaned and prepared is often exactly as important as the conclusions drawn from it. The conclusions are the last five percent of the journey. Everything that shaped the answer happened before.

And there are two symmetric ways to fail here:

• Conclusions drawn from raw data give you a picture distorted by outliers. One huge client, one migration script, one QA account with ten thousand test orders, and your "average" is science fiction.
• Conclusions drawn from over-cleaned data give you optimization toward a thesis. Scrub away every inconvenient observation as an "anomaly," and the data will happily confirm whatever you believed before you opened the file.

Between those two extremes lives an honest analysis. You'll recognize it by one feature: it comes with a changelog.

It's rarely the conclusions

In organizations (I'm deliberately not saying corporations, because this has nothing to do with company size) the problem I keep seeing is almost never the inference step. People are genuinely good at drawing conclusions. Give a smart group a dataset and they will reason about it just fine.

The problem sits earlier and deeper. It is how the data was collected, and the missing shared language to describe it. We argue passionately about what the numbers mean. All the while we disagree, without knowing it, about what the numbers are. Calling that process data-driven doesn't fix it. It just gives the disagreement better slides.

Unless…

Of course, there is one scenario where none of this matters.

Maybe your goal is not a decision at all. Maybe it is walking into the meeting as the prepared one, radiating competence from behind a wall of charts. Then yes, data helps enormously. A confident slide with big numbers is a wonderful prop.

But it works under exactly one condition: your audience must not be competent enough to ask about definitions and preprocessing. And trust me, that happens more often than we would like to admit ;) If you are wondering how those audiences end up in those rooms, The Peter Principle has been explaining it since 1969.

A small experiment

So here's my suggestion for your next data-driven meeting. Don't challenge the conclusions. That's playing the game on the presenter's terms. Ask two questions instead:

1. "How exactly do we define this metric, and does everyone here use the same definition?"
2. "What was removed or transformed during cleaning, and why?"

Then watch the room.

If the answers come easily, congratulations: you're in one of those rare places where data-driven means something. If what you get is a pause, a nervous smile, and "let's take it offline", you have learned more in ten seconds than the whole deck was going to teach you, and you learned it in front of the same people who were a minute away from nodding along. You now know exactly which layer is broken. It happens to be the cheap one to fix.

Definitions are cheaper than dashboards. Write down what "active user" means here, get two departments to put their names on it, and half the charts in the building start meaning the same thing without anyone rebuilding a single query. That's an afternoon. I have never seen an organization finish it in one sitting, and I have never seen one regret starting.

But I have a thesis that might make a few software architects uncomfortable: in the era of AI, legacy code no longer exists. The entire concept of "legacy" is expiring. What we are left with is something far more valuable, and it's time we change how we look at it.

Why Did We Call It "Legacy" Anyway?

Let's be honest with ourselves for a second. What actually makes code legacy?

Historically, code became legacy the exact moment developers simply didn't want to maintain it anymore. It was an incentive problem. The promise of working with brand-new, shiny technology means being more efficient, learning new skills, and therefore remaining highly competitive on the job market. Not everyone wants to put "maintained a 10-year-old monolith" at the top of their CV.

To justify moving away from it, we tended to argue that legacy code is inherently more costly to evolve and that adding new features is too slow.

But here is the reality check: code is incredibly cheap now. With AI, generating code is no longer the bottleneck. Legacy code isn't the primary factor slowing down system development; unnecessary complexity is what actually kills productivity.

Oh, and let's not forget the most important part: many times, that ugly, outdated, legacy code is exactly what is paying our monthly salaries.

The Tech Stack Doesn't Matter Anymore

The fact that the technology used in an older codebase isn't state of the art means absolutely nothing to a Large Language Model.

As long as the code passes your functional and non-functional acceptance criteria (like performance and scalability), the age of the syntax is irrelevant. What matters right now isn't the framework. It's the data stored inside the code.

From Codebase to "Knowledge Container"

This brings us to the core of the shift. If it's not legacy code anymore, what is it? It is a Knowledge Container.

Think about it. That repository is the single most accurate, battle-tested database your company owns regarding:

• Deeply embedded business processes.
• Highly specific edge-case acceptance criteria.
• Real-world workflows that no one currently working in the office actually remembers.

In the past, code went out of date the moment a developer hit commit. Today, that commit just becomes highly structured training data, a rich knowledge base for AI agents to read, understand, and act upon.

The Rise of the "Dev Operators"

Because of this, we don't need massive, groundbreaking "greenfield" initiatives just to keep systems in sync with modern standards.

If the tech stack no longer matters, the role of the human changes. We are moving away from being traditional engineers who manually type out logic, to becoming "Operators." An Operator's job isn't to write the code; their job is to leverage the Knowledge Containers, express the business intent to an AI agent, and accurately judge the final result.

The concept of legacy code simply won't work anymore in the long term. It's a relic of an era where humans had to read every line.

Now, I just wonder: if we stop tracking Technical Debt, how long will it take for us to invent a metric to measure a system's "Knowledge Density"?

At the company I worked for, we lived exactly that. GitFlow-style branching, multiple active branches at once (master, develop, releases in flight), and changes that had to propagate across all of them. Manual coordination was error-prone and slow, and the errors were the expensive kind: a regression returning in production because one merge was forgotten.

So we automated it. We call it the Automerger.

What It Does

The Automerger is a script built with Cake, the C# build automation tool. Its job is deliberately boring:

1. Detect which branches need to be synchronized.
2. Create a temporary branch and perform the merge there.
3. Validate the result by building the code and running the tests.
4. If everything is green, push the merge.
5. If there is a conflict or a failed build, stop and notify the developers responsible.

The key design decision: the tool only involves humans when a human is actually needed. A clean merge that builds and passes tests does not deserve anyone's attention. A conflict does, and then the notification goes to the right team, not to everyone (alert fatigue is real).

Although the tool is written in C#, there is nothing .NET-specific about the workflow. It merges JavaScript and Java repositories just as happily; the validation step simply runs whatever build and test commands the repository defines. It plugs into our CI/CD platform (Azure DevOps in our case) and notifications go wherever the team lives, Slack included.

Convention over Configuration

The part I like most: the Automerger needs almost no configuration. It discovers branches and orders them by naming convention. If your branches follow a sensible pattern (and with GitFlow they already do), the tool can infer the merge direction on its own: fixes flow from the oldest release branch, through newer ones, into develop.

One honest requirement comes with that: the workflow relies on real merges, not cherry-picks. Cherry-picked commits look different to git, and the tool cannot reason about them. Convention over configuration works only if you keep the convention.

Two Years Later

After two years of running the Automerger every 3–4 hours during working days, the numbers settled around 90% of merges completing fully autonomously: no conflicts, builds green, nobody interrupted. Nine out of ten of those "remember to merge back" tasks simply stopped existing.

The remaining 10% is exactly where humans belong: genuine conflicts, where two branches disagree about the same lines and somebody has to decide.

The lesson generalizes beyond git. Find the task that is repetitive, mechanical, and only occasionally requires judgment. Automate the mechanical majority, and route the judgment cases to people with full context attached. Developer time is too expensive to spend on merges that a script can prove safe.

What is the "merge back to develop" of your team, the recurring chore everyone does by hand because nobody sat down for a week to kill it?

A technical leader can be just a simple position in the corporate hierarchy. It can be a safe position reserved for a person technically based with some leadership skills. Opposite to team leaders who generally should have strong leadership skills and a technical base, not necessarily be a guru in the programming stack. The question you should ask yourself is: what do you expect from your career?

One of the ingredients is your attitude. I have never wanted to make this title just a corporate position to me. The footer in corporate mail means nothing to me. After three years of being a technical leader, I've learnt a lot about what it's like to be one of them (in this particular environment). I have ups and downs. One day I would never change this position to a different one, the next day I was almost ready to quit and move on. I would like to break down this position into smaller pieces for you. Let's start with splitting just the name "technical leader". It has two words in it. The first part is strictly "technical", the second is "leader". I will try to address these two parts inside this article and explain what it means to me. What I do to be the best possible technical leader.

"Technical"

The technical part is all about widely known engineering craftsmanship. The whole category is extremely wide, so let's split it even more.

Self-development. The first one is self-development in the context of engineering knowledge. So simple and yet so complex at the same moment. The technical leader needs to join the technical mastery journey no matter what he or she knows already. A technical leader is responsible for analyzing new approaches, new shiny bits and bobs that come to our engineering market. Follow trends, join conferences, and so on. As the market is going fast in various directions, it is a tough nut to crack.

Usually, inexperienced developers are highly motivated. Discovering the engineering world just makes them even happier to go further and further. Somewhere on the road, the developer finds out that it is almost impossible to be a specialist in every branch of engineering.

After some time you find it spiritually releasing to decide not to try to be a specialist in everything, because it is almost impossible. Just find your thing or two that drives you, makes you sleepless through the night, makes you search for the next piece of information about a particular topic. On other topics be up-to-date, more or less. Do you like data science? It's fine not to know the specification differences between OpenAPI 3.0 and 2.0. Just simply know it's there; you will deep dive into details when needed.

"Let him who would move the world first move himself." ― Socrates

Using knowledge. The second chapter is using engineering knowledge in the day-to-day workspace. Making the right decisions and leading the team to the chosen common goal, which should describe where the IT department wants to be in the long run. It's the technical leader's responsibility to make sure the goal itself correlates to the high-level shape of the software architecture. Architecture as simple as possible while meeting all the needs of the business. Easy to develop and easy to maintain in the long run.

Finding this architecture is a never-ending story. The company evolves and software should follow the development as well.

"Clean code is not written by following a set of rules. You don't become a software craftsman by learning a list of heuristics. Professionalism and craftsmanship come from values that drive disciplines." ― Robert C. Martin

Being a medium. The third category is being the technical medium and connector between the architect, other teams, and the team itself. At the moment we have eight teams with seven developers each. This is not a space where lack of proper communication can be accepted. Discussing with other technical leaders and the architect takes place twice per week.

Being a connector between the technical leaders' community and the team is an important task which needs to be done every day. Making sure the team knows where we are heading. It's crucial to the whole IT environment to know what decision has been made and why the technical leaders' community took this approach. In the long run, communication lets the team understand the goal where we are heading and, therefore, be more independent in making decisions and in the end more effective.

"The single biggest problem in communication is the illusion that it has taken place." ― George Bernard Shaw

"Leader"

Each technical leader has a "leader" inside the position title. Leader means leadership for the team. How to be the best one for the team? Here I will present tangible ideas and practices that are introduced inside my team. I am sure that thanks to those, my team has improved a lot during these three years. Are those rules a golden bullet suited for every team in every corporation? For sure not… Simply looking from a statistical point of view, they will not fit every environment. I hope I can inspire you a bit and encourage discussion.

Dev knowledge sharing. The first idea is about sharing knowledge in a safe space. I have booked one hour per week, usually at the end of the week when everyone is thinking about the weekend already. The idea is to create a safe space to share any topic you want.

Only one rule applies: you have to talk about engineering. There is no constraint that the topic has to be work-related or has to suit the project the team is working on. Simply, you have something to share? Come and talk about it. What's more, there are no rules about the presentation itself. If a developer wants to have a high-end presentation, it is appreciated; if a developer presents an idea from a scratch of paper, that's fine as well.

The idea found interest quickly and became a permanent part of the team's life. We had meetings where all of us were reviewing pull requests with some new approach, as well as meetings about machine learning algorithms. From TDD to ideas on how to optimize our team efficiency. From coding conventions to project managing strategies. Anything developers are interested in is suited for the local dev knowledge sharing.

After three years of hosting these meetings, I found out that the secret here is feeling safe inside the team. Each presenter received feedback during the meeting knowing that feedback is only for his good and self-improvement. There are no mean jokes, nobody criticizes that the topic isn't important in any context. It is simply time for a developer to shine and be proud of his knowledge.

These meetings evolved from local dev knowledge sharing to company-wide meetings. We keep both. Local team meetings stay the same, the safe place they were designed to be. There is also a place to share knowledge with the bigger crowd: the whole IT department. Sure, it requires a little more preparation than just a piece of paper and an idea. A nice presentation is one of the unwritten requirements. The audience is multinational, so it also requires globalization of your presentation. Globally hosted knowledge sharing meetings are a much bigger deal than the local ones. Both meetings are held hand in hand. In the end, the outcome is improved team knowledge with no additional cost.

"If you have knowledge, let others light their candles in it." ― Margaret Fuller

Meetups. Starting from the local dev knowledge sharing idea, we moved one step further. We hosted a meetup. The first one was about the approach to one of the projects we were involved in. We had space and time to learn (learn the hard way) TDD inside DDD.

We decided to share our journey with the local community. The event took place at our office, in a workshop formula, and it was specially designed to guide participants into the same mistakes we made. We showed how we handle challenges and what we had learned.

Technical excellence meetings. On the other side, inside the team, we have team members, NOT resources. Each team member is a human being with a different background, different needs and different goals.

As a technical leader, there is enough space to show myself useful. The idea is to independently develop each team member's skills based on his or her needs. The concept name is "technical excellence". There are two kinds of meetings during the month. The first meeting is quick, up to half an hour: a planning and negotiation session whose goal is to find the area that will be developed later. Ideas usually come from the developer; he or she knows best what they're interested in (well, sometimes it is not the case, as some people need a small hint). My role is to ensure the idea is valid at the basic level and to find common ground between developer needs and company goals.

With a plan in place, there is a proper longer meeting, usually around two hours once or twice per month. This relatively small time belongs completely to the developer. We can do whatever he or she wants as long as it brings educational value. During these three years we had meetings about blockchain, testing, many topics related to DDD, or specific Azure features. During the meeting we can research the topic itself, work on problems related to it, or even prepare a presentation that will be shown later at the IT department knowledge sharing meeting.

The ones that touched me the most are about self-improvement. The majority of my team members found themselves in a place where they want to take a "step forward", the step that will distinguish them from every other backend developer. Those meetings are the most heart-touching, the hardest ones, but also the most inspiring and rewarding ones. I would recommend it to each technical leader: try to talk not only about facts and technology. Find a way to inspire team members, even a little bit.

The success of those meetings is based on properly planned time for the developer, way ahead. Each of us has some topic that he or she wants to handle when time allows. The truth is that there will be no free time. What's more, you will have less and less "free time" as your career evolves. Those meetings address the problem: the time frame cannot be moved, every participant needs to be prepared. The meeting must take place.

Every year there is a time of appraisals, the time when your performance gets reviewed. What is important to me, there are feedback forms that let others put opinions about me as a technical leader. In the past, I found a lot of mentions of technical excellence in the feedback forms, and most of them were very positive. For me, it is simply a win and the way to go.

Along with those meetings, I found two things that make me wonder a bit. Since each meeting was between me and another team member, I had to be prepared for every topic, which put pressure on my calendar. The idea I want to test is to follow the same meeting pattern, but with team members running the meetings for each other. I would just watch at the very beginning and help until the point where I'm no longer needed. (At this moment I am part of a team of very experienced developers; the idea might not work with a less experienced team.)

The second matter that bothers me a bit is purely egoistic. Each team member gets a few hours per month to develop himself, but what about me? :) The answer is simple: I do technical excellence with myself (sounds like a split personality). I simply book some time during the month and learn what I'm interested in the most. At the moment the hype is on deep learning.

"Be a yardstick of quality. Some people aren't used to an environment where excellence is expected." ― Steve Jobs

Pair programming. Again, simple as that and powerful as that. Pair programming in any form that suits the developer and the situation. Starting from just sitting together and being a rubber duck for the partner, to hardcore pure pair programming with the whole team inside a dedicated room. Having not just one additional pair of eyes but three members watching. A live coding session with a large screen presentation and discussion about specific problems.

Which method should we choose? The rule of thumb is to pick "small" pair programming (sitting together, switching keyboards from time to time) for smaller problems like bugs or planned tasks, and the "whole team is watching" meeting for solutions that will affect everyone's future work. Usually meetings about core decisions made at the beginning of a project, or changes in the direction the team was heading.

A lesson learned here for technical leaders: be prepared to monitor the involvement of others during "everyone is watching" meetings. The tool is so simple and so powerful; in terms of team building and knowledge sharing it is one of the best in my opinion. Be careful not to fall into the trap of being "The Devil's Advocate", which causes frustration. Usually stepping back and taking a huge breath is the cure. After all, being pragmatic and empathic is crucial here.

Open source initiative. Teams at our company are backend based. Usually we have a 5:2 ratio of backend to frontend developers inside a team. Team members produce source code daily. Most of the code is usually not visible to the end user and, therefore, it is harder to appreciate the craftsmanship of individuals.

Here, the idea was to share our concepts with the external world. Share it with the IT community in the form of YouTube videos, source code on GitHub, and articles on medium.com, exactly like this one. Each IT member can express himself or herself to the community about the topic he or she has mastered during nine-to-five work. Every piece of content is signed with the developer's name, no anonymous content. The sharing idea brings clear benefits to both sides. Developers build a brand for their names, and they build the company's brand as one with a strong engineering culture.

"Open source is a development methodology; free software is a social movement." ― Richard Stallman

Power of Small Changes

All the tools and methods described here are working for my team. What I've found during a few years of being a technical leader is that team evolution is faster than you think. Each member works hard to become a better version of himself or herself, not only during work hours but also after the nine-to-five period. To keep everyone interested there is a constant need for small improvements, small changes that keep the technical leader's toolset fresh and joyful for everyone.

If you find yourself in the same corporate position as mine, please share your experiences with the set of tools that you have developed over time.

"Great things are not done by impulse, but by a series of small things brought together." ― George Eliot