Oh no, sick kids!

Imagine that there two parents: Karen and John.

They have two kids: Alice and Dylan.

The life was good, until one day when both got back from the school and had strange symptoms: vomitting, fatigue, diarrhea, and fever.

Well, not a pleasent situation for the kids.

And even more unpleasant for the parents, who had to deal with the sudden illness of their children (and in general with the situation at home).

What did the parents do in this situation?

Called the doctor, immediately.

Also what they did, before the doctor arrived, was to make sure the kids drank plenty of fluids.

But there was another problem which was not known from the beginning - whenever any of the children drank any fluid in a glass-volume amount that was too large, they would immediately vomit it back up.

This complicated the situation.

The doctor, Mrs. Ivonne, examined the kids, listened to what parents ellaborated about the situation.

She then diagnosed them with a strange viral infection.

The doctor was pretty knowledgable and she know it's good to visualize the knowledge, even for a simple case like this.

She wrote the rules on the piece of paper and handed it to the parents, ensuring they are all aligned - to achieve so, she asked both parents to explain her how they would administer the dosages.

Instructions from the doctor (generated with LLM)

Even though the situation was really challenging, both parents were happy - they got pretty detailed instructions from the doctor on how to care for their sick children.

Now it was a matter of living through this sickness, with some disciplined administration.

Parents + Engineering = ...?

Karen and John wanted to approach this a little bit more structured and organized, applying some engineering principles to ensure they followed the doctor's instructions accurately.

Fortunately, they had a whiteboard where they could keep all the information in the single, central place.

Such that they won't administer something incorrectly, just by referring to the whiteboard for guidance.

They divided the whiteboard into two halves: one for Alice and the other for Dylan.

Whiteboard as a central place for keeping all the information about kids. (generated with LLM)

Now, they needed to think a bit about how to organize the information, so that they can quickly find the relevant details when needed and avoid any mistakes in administering the medications.

Parents decided to devide everything into categories based on the discussion with the doctor: temperature, vomitting, hydration, meds.

Additionally, they thought maybe "notes" as a separate category might be useful to have - having more information sounds better, isn't it?

Whiteboard structured into categories for each child. (generated with LLM)

When they stood in front of the whiteboard, they felt proud of approaching the whole experience in this way.

Whiteboard-driven sickness management

The life was moving on and both parents were diligently following the structured approach they had set up on the whiteboard, ensuring that their children received the care they needed.

Everything was meticulously recorded and updated on the whiteboard, providing a clear and organized view of the children's health status at any given moment.

Whiteboard updated with the latest information about the children's health. (generated with LLM)

It looked both impressive, but also a bit...Messy?

It was definitely possible to read the state of each child's health and how does a recovery process is progressing, even if the whiteboard appeared a bit chaotic at first glance.

Problems started araising when Mrs. Ivonne asked about a specific detail regarding one of the children's medications, and it took a moment to locate the information on the whiteboard.

Additionally, she queries for a summary of last days which required juggling TEMP, VOMIT, HYDRATION, and MEDS sections on the whiteboard, making it a bit challenging to quickly compile the information.

The nail to the coffin came when the doctor came back with a conclusion that the fever temperature threshold over which a medicine needed to be administered was different from what she initially said.

Mrs. Ivonne spoke with the lab and they clarified that this virus requires more careful treatment so the rule for dosing the medication for fever was not using 40°C as the threshold, but rather 38°C.

This meant that all the previous entries on the whiteboard regarding fever and medication needed to be re-evaluated and updated according to the new threshold of 38°C, adding to the complexity and potential for confusion.

Karen and John organized the whiteboard around the information, not about "real" facts they observed while taking care of their children.

Even though is seemed structured and organized, as the time passed, it was a bit rigid and less adaptable.

Constraints liberate, liberations constrain?

They became aware that what they are dealing with is not just a set of information with relationships, but rather a process - something that flows, expands and contracts.

They still wanted to use the whiteboard as a tool for keeping the information, but this time the information they will gather and interpret is going to be different.

Karen suggested to focus on what is happening, rather what is changing.

This meant paying attention to facts, rather than mere information.

Also, what they learned from the whiteboard experience so far is that it's very tempting to erase information or update information, because it seemed easy.

Some of the entries from earlier got buried under other information, which basically made parents lose important insights about the progression of their children's health and recovery.

The decision was made - entries cannot be erased or overwritten; instead new entries would be added to reflect the ongoing changes and observations, creating a chronological record of the children's health and recovery process.

This single constraint fundamentally changed how they interacted with the whiteboard.

To achieve such constraint, John suggested using orange sticky notes so that they can treat each entry as unchangeable once it is added.

Stickies representing the record of what happened when during the recovery process (generated with LLM)

After they established another way of organizing the information on the whiteboard, they started thinking what kind of facts they need to capture and keep track of.

They realized that capturing facts required a clear distinction between observations and interpretations. Observations are direct, verifiable occurrences, while interpretations are the meanings or conclusions drawn from those observations.

This distinction helped them understand that while observations could be recorded as immutable entries on the whiteboard, interpretations could be added as separate entries that provide use case and insight without altering the original facts.

So they came up with the following list of facts that were important in their situation:

• "Temperature measured" with details:
  • which child
  • when measurement was captured
  • the measured temperature value
  • who measured the temperature
  • what device was used (they figured out that they used either a digital thermometer or an infrared thermometer)
• "Vomited with fluid" with details:
  • which child
  • when it happened
  • the volume of vomit (small, medium, large)
  • who observed it
• "Vomited with food" with details:
  • which child
  • when it happened
  • what food was vomited (if known)
  • the volume of vomit (small, medium, large)
  • who observed it
• "Fluids offered" with details:
  • which child
  • when it was offered
  • what type of fluid was offered (e.g., water, juice, electrolyte solution)
  • the volume of fluid offered (spoon, glass, bottle)
  • who offered it
• "Fluids consumed" with details:
  • which child
  • when it was consumed
  • what type of fluid was consumed (e.g., water, juice, electrolyte solution)
  • the volume of fluid consumed (spoon, glass, bottle)
  • who observed it
• "Fluids refused" with details:
  • which child
  • when it was refused
  • what type of fluid was refused (e.g., water, juice, electrolyte solution)
  • the volume of fluid refused (spoon, glass, bottle)
• "Dose administered" with details:
  • which child
  • when it was administered
  • what medication was given
  • the dosage
  • who administered it
• "Urinated" with details:
  • which child
  • when it happened
  • the volume of urine (small, medium, large)
  • who observed it

Karen reviewed the important facts they considered as essential and additionally suggested the following:

• "Symptom observed" with details:
  • which child
  • when it was observed
  • what symptom was observed (e.g. "fatigue")
  • who observed it
• "Slept" with details:
  • which child
  • when it happened
  • the duration of sleep
  • any wake periods during sleep
  • who observed it

John was very happy that they focused on what they must observe during the care of the children.

Somehow it felt "right" from the start of using this way, because they didn't need to focus on the structure of potential, future interpretations, like this inquiry from the doctor about the summary, or anticipating what they need to count.

By doing that, they were able to separate observations from interpretations.

He also highlighted that there is another important fact to consider: issuing instructions.

They received instructions and initially Mrs. Ivonne told them to use 40°C temperature as the threshold for administering medication.

Then, the rule changed and 38°C was the new threshold.

So additionally to previous meaningful observations-to-record, they decided to add one more:

• "Care instructions received" with details:
  • which child
  • when it was received
  • what the instruction was
  • who issued it
  • when it was effective from

In case of changes to care instructions, they will be able to adjust how to make the decision regarding administering medication or other care actions accordingly.

After some time, that is how the whiteboard looked, filled with all the essential observations they captured:

Children's health observations (generated with LLM)

They were able to use those facts to make decisions about next steps, when it came to assisting in the recovery process - whenever vomit occurred, the additional medicine should be administered (according to the care instructions received).

According to the rules, three vomits in a 5 minute window, under a fever threshold, triggers giving the medicine.

Parents could easily retrieve such information, just by going through all facts recorded on the whiteboard, for the kid who vomited.

The doctor calls to check the child's condition based on some summary information?

Sure thing - just start from the left side of the kid's whiteboard-half and follow the sequence of observations recorded there, creating the summary.

Finally, Karen and John felt empowered by all the optionality offered by those facts, represented by stickies.

Previous approach was not bad and not evil, on its own.

It was not yielding the same level of options and flexibility, when it comes to adjusting based on the evolving situation.

And the most important constraint - no erasing and no overwriting of existing observations on the whiteboard - truly guided their behavior.

The process of healing?

One day Mrs. Ivonne called them to check what is the situation right now.

She told them how to take care of the children, but she was not clear on specifying when a child could be considered fully recovered.

The doctor expressed the following: "whenever any of the following happen: fluid was consumed, temperature was measured, a child urinated, perform a check - full glass consumed, temperature below threshold, child has urinated - all in 2 hours, then recovery can be considered as completed."

Soon, John used this guidance to verify the state of the recovery process of both kids.

Finally, both Alice and Dylan were considered fully recovered according to the doctor's criteria.

The model of everything?

Both parents fall in love with this approach for organizing "things" - even though it might have seem as overly complex and difficult to follow at first, they quickly realized the benefits it brought in terms of clarity, accountability, and flexibility in managing the children's care.

It turned out it's not only for managing the children's care - but it fits other problems too.

One day, John noticed that Karen appended a new sticky note to the whiteboard, in Alice's half.

It caught John's attention because it contained the following information:

• "School project scheduled" with details:
  • what is the school subject
  • what is the topic of the project
  • due date
  • required materials
  • when it was scheduled

It was definitely worthy having such fact recorded, but at the same time it did not feel "right".

"So far, we were keeping observations about recovery process, and this new one is more about school-related activities?", thought John.

He decided to leave it for now and see how it would evolve.

Sick kids? Vomitting? Diarrhea?

"Ok Damian, what the hell did just happen?", one could definitely ask angrily.

People are serious software professionals and I dare to tell a tale about sick kids, vomitting and parenting?

How disappointing it might seem to be!

But wait, let's stop here and ask one important question.

Do you know what this tale was about, dear Reader?

Probably you have already guessed.

We saw event sourcing in action, but more on the conceptual level.

Our whiteboard played a role of persistent storage, initially acting as "a general storage".

All the observations were events, capturing what happened over time.

Both parents played the role of "consistency boundaries", ensuring that proper decisions are made based on the rules driving this "tiny, toy domain".

They both were "deciders", using models for deciding - very specifically built ones, out of all facts that happened, but applying one by one until the correct set of information was obtained.

Throughout this tiny tale, we saw how parents were trying two approaches to managing the complexity of the situation.

Initially, they used structured approach for capturing snapshots of the state.

So it's not that they did not put any effort in analyzing and planning the way of organizing.

They represented information about each children, using categories they understood and found relevant for tracking the recovery process.

It was easy to start, but the more into the future, the harder it was to maintain consistency, especially when the requirements changed - new rules arrived, new inqueries appeared.

What could have mislead them was the assumption that they are facing a state of sickness of each kid, rather than a dynamic, flowing process that evolves over time.

One could say that they focused on nouns, without checking how these nouns interact with each other, transform over time and form a flow of "work" (=a workflow).

They might have fallen into "a nominalization trap".

So telling a story how they arrived at certain state was challenging, but not impossible.

When they realized they are dealing not with "a state of sickness", but rather with a recovery process that unfolds over time, they adjusted their approach accordingly.

They switched into looking at important and meaningful facts that they could and needed to observe over time.

And there was no magic - parents needed to spend time to carefully analyze, structure and organize those facts-to-capture.

The quality of that process helped them gain a clearer understanding of the recovery journey and make informed decisions along the way.

Even though "the requirements" changed, like those instructions from the doctor, the approach was accomodating them quite easily, because parents were observant and skilled enough in defining the process.

They were able to adjust the way they interpreted the captured facts, depending on the evolving context and the specific needs of each moment.

And this "one simple trick" changes almost everything - separating facts from ways of interpreting them is so enormously powerful.

What does it teach us, dear Reader?

Facts? Interpretations? Perspectives?

Look around, dear Reader.

Our mind constantly interprets the facts happening in the external world (external to "us"), tricking us into believing that each "thing" in the surrounding environment is fixed, static.

A spoon that was placed in the pot of boiling water, and started heating up, might seem like "the thing", but in reality, it is part of a continuous process of heating and cooling.

Continously flowing.

Panta rhei - everything flows, nothing stands still.

But it is just one process - thermodynamical one.

And there are other processes to - manufacturing process, selling process, delivery process, claiming process, and so on.

So a single "thing" can be a subject of many, different flows.

That's why we, as software professionals, need to pay attention to dimensions while we are analyzing, reasoning and designing systems.

An avid Reader might realize that "there is no spoon", at least not the spoon.

There are many spoons-in-different-contexts, each undergoing various processes, and it's our decision what is relevant, important and worth modelling.

One could say a spoon might be viewed from different perspectives.

And we already know that mixing different perspectives into "the single thing" might create problems in the near future.

This absolutism-attracting force, "the knowledge gravity" as I like to call it, will lead to another trap related to state - mistaking the current snapshot, needed in a given use case, as the state of a given "thing".

The same nature was possible to be observed in the context of children recovery process, that Karen and John experienced.

Initially, they focused on dealing with sickness and recovery facts, but as soon as Karen noticed another important fact - "school project scheduled" - she needed to assign it somewhere.

Unfortunately, they named the whiteboard-halves after their children names, immediately anchoring themselves into thinking in "absolutisms".

Naming is framing, so this "single, tiny event", related to the school, might have started the process of entropical information attraction.

Started with recovery concepts, this stream of facts might slowly, but steadily, acquire more concepts related to school, social life, and other aspects of the children's daily activities.

And sooner or later, various perspectives will make the entire event stream:

• hard to maintain due to its length and coupling
• hard to ensure consistency due to overbloated consistency boundary
• hard to perform well due to its length
• and more

That's why event sourcing might not help us if we incorrectly organize event streams, decomposing them along incorrect boundaries.

This means that just capturing events is not enough - one must use use calories to explore, discover and establish boundaries, watching out for the Diaper effect.

The state of designing systems?

It's easy to fall into a common trap of looking at absolute concepts, as well as focusing on the current snapshot of the system's state.

Easy, because it requires little effort to grab what is immediately visible, without paying attention to depth, perspectives and time.

System 1 kicks in so blazingly fast that the judgment is done before noticing it's all over.

That's why we need to slow down and use quality time to collaborate with others to align and avoid hasty conclusions.

"Haste makes waste" which might not be initially visible.

So next time dear Reader, look for what happens when it comes to what you are analyzing and observing - whether this is a manufacturing process of a spoon, a child's recovery journey, or the evolution of a software system - all in specific contexts (here: perspectives).

This framing is so powerful that influences the system architecture in a great extent, because of the used language.

And this language frames our thinking, either limiting or opening possibilities.

If we start naming things in the context of "continously flowing", this would be the world we see.

If on the other hand we decide to name things as absolute, static entities, this would be the world we operate in.

So next time dear Reader, when you are presented with a business problem or an engineering challenge, ask yourself:

And remember pay attention to the language and start naming various perspectives you and users might look at this workflow:

Going out to find some nouns

You might recall Derek and Diego from The ambiguity of naming - two developers working for a company selling local, guided tours.

Multi-city tours shipped. Customers were happy. Paul, their product owner, was happy too, for a while.

Then the Tour class started growing. And growing. Pricing rules bumped into scheduling rules, which bumped into navigation state, which bumped into guide availability.

Sounds familiar? (if it doesn't, dear Reader, go check what happened to poor Tom's tourism platform)

Now senior enough to know better, Diego had enough.

So they did. Out into the wild.

Everyone hands a noun

Guides talked about "the tour".

Back-office people talked about "tour seats" and "the schedule of a tour".

Marketing talked about "tours catalogue".

Participants talked about "my tour's itinerary" and "my tour booking".

Derek was taking notes furiously, circling anything that sounded like a concept.

Why does this keep happening, even to senior people who (hopefully) know it's a trap?

A noun the brain grabs first

Daniel Kahneman described two ways our brain operates (it's a reductionistic perspective, but as with all models - still it's useful).

When you're standing in a guide's office and someone says "the tour", System 1 does what it's best at - it matches the sound "tour" to a ready-made mental box and hands it to you, instantly, no assembly required.

It basically boils down to "what I see/there, there it is".

Asking questions requires effort, answering them requires even more of it too.

And effort is exactly what System 1 is built to avoid.

That's the urge to "find things" out in the wild - we go looking, we collect words, and the loudest, earliest, most concrete-sounding word wins the naming contest, well before we've asked what it actually represents.

Whatever we find "out there" still needs the software dimensions applied to it - time, angle (perspective) and depth aren't optional decoration, they're what turns a word into a model.

Slow down, on purpose

Diego wasn't satisfied.

That's the switch from System 1 to System 2 - and it's exactly what analysis is for: taking something whole and decomposing it into its elements, so it can actually be understood, before it gets put back together.

They went through all of the material, one by one:

• Someone browsing options, before ever paying anything - marketing wants this searchable, filterable, fast.
• Someone picking a date and a headcount, holding a spot, paying for it.
• Back-office people checking how many spots are left, right now.
• A participant, mid-tour, checking what happens next and where.

Different moments in time.

Different perspectives.

Different needs.

It all requires an aware, trained mind to notice all of that.

And it's effort requiring.

It consumes time.

Eventually, four concepts emerged in the field of operator awareness: Catalogue, Reservation, Seats, Itinerary.

Derek looked relieved.

Are all nouns equal?

Here's the ambiguity, dear Reader - grammatically, all four words are nouns. Same part of speech, same shape, same "box with fields" instinct that System 1 wants to apply to every single one of them.

But are they the same kind of thing?

In Modeling Maturity Levels, we already established a small, useful correspondence:

So, naively, a noun should mean "Being" - what something has, what it is.

A verb should mean "Behaving" or more deeply "Becoming" - what something does, what it turns into.

Except language cheats.

Verbs in a noun's clothing

It might be that not every noun is equal.

Even if we use our analytical skills and correctly segregate an absolute noun into a set of contextual ones, still we might fail with designing a model around those concepts.

In linguistics and cognitive sciences, there's an interesting concept behind a phenomenon called nominalisation.

A verb gets frozen, packaged and handed to you as "a thing".

to reserve becomes a reservation.

to decide becomes a decision.

to arrive becomes an arrival.

So instead of "looking at the motion", our focus gets placed on "the thing that results from the motion".

Reservation is exactly that - underneath its noun-shaped costume hides a verb, a whole sequence of them: request a spot, hold the seats, wait for payment, confirm, or expire, or get cancelled.

type Reservation =
    | { status: "Requested"; participants: ParticipantCount }
    | { status: "SeatsHeld"; holdExpiresAt: Date }
    | { status: "AwaitingPayment"; amountDue: Money }
    | { status: "Confirmed"; confirmedAt: Date }
    | { status: "Expired" }
    | { status: "Cancelled"; reason: CancellationReason }

On the surface it might be seen (and then understood) as a noun, yet again as an absolute "thing".

So even though we successfully identified a particular aspect that "a Tour" might be looked at, we might fall into the trap again.

This is a "Becoming" level, wearing "Being" clothes - a state machine, disguised as a data bag.

It might be that we are dealing with a business workflow - going through various states, integrates a bunch of other concepts in order to deliver value, based on the needs of the consumer.

So something that "flows" rather than "is".

Model it as a flat class with a status: string field, and you've thrown away exactly the information that matters - which transitions are even legal, and when.

Seats, on the other hand, isn't hiding anything - it might be regarded as a countable resource with an invariant (you can't hold more than what's available) that must be protected, consistently (if you are looking into the challenge for designing a solution for such a problem dear Reader, please feel free to explore this blogpost).

class Seats {
    constructor(private readonly total: number, private held: number) {}

    canHold(count: number): boolean {
        return this.held + count <= this.total;
    }

    hold(count: number): void {
        if (!this.canHold(count)) {
            throw new Error("Not enough seats available");
        }
        this.held += count;
    }
}

And yet again, we might undersee important and subtle details, if we treat it as an absolute "thing".

It truly requires a disciplined, mindful and skilled approach so that we continously challenge designer's (which mean, ours) assumptions so that we verify we are designing a model, not the model.

Catalogue is yet another substance entirely - a perspective, composed for a completely different moment in time (browsing, before any commitment exists), for a completely different audience and needs (a curious visitor, not yet a paying participant).

Denormalized, read-heavy, low on rules.

Naive conceptual check?

Analysis had done its job - it segregated Tour.

It would be good to have some heuristics so that we can "shake" the model candidate, to see if any hidden workflows reveal themselves through our perception.

Diego had a shortcut for exactly that.

The mental tool is fairly simple - try adding "-ing" to a noun and see if it reads as an ongoing activity.

If not, you might want to go to deeper levels and try to check "what is hidden" behind this "absolute" thing.

There might be something hidden, which is more workflow-based, around.

Another approach of the same kind is to prefix an absolute noun with "ongoing" - "ongoing User", "ongoing Product", "ongoing Tour".

The main idea is to "see it in motion", not "laying down on the shelf".

We, designers, want to interact with the concept to see how does it behaves.

Imagine that heroes of our tiny tale ran it against Catalogue next - "Cataloguing" fits too.

This is the whole point of these "tricks", dear Reader - they are not a golden hammer.

Say a word to a noun, watch it wobble (or not), and decide what to do with what you just "saw" - what information it reveals.

Hammer blindly - "if '-ing' fits, it's a workflow, full stop" - and it might hurt you, dear Reader.

What about Itinerary?

Derek wasn't ready to let this go.

That's the twist, dear Reader - checking whether a noun is a nominalisation isn't a spelling exercise, it's not about etymology at all.

The question is never "does this word grammatically descend from a verb?" - it's:

Itinerary-the-plan is a "Being" noun.

"Itinerary planning" is a "Becoming" process.

Language just doesn't give us a single clean word for the second one, so we default to naming the output / the result, and quietly forget the workflow that produced it ever existed.

Analysis, then synthesis

Decomposing Tour into those four was the analysis - taking the whole apart into elements we could actually reason about, one perspective and one moment in time, at a time.

But analysis alone isn't design. Diego and Derek still needed to put it back together, with the understanding they just gained - synthesis.

Reservation, once confirmed, is what makes Seats.hold(...) lasting forever, and eventually what causes an Itinerary to be produced for that specific booking. Catalogue doesn't participate in any of this - it just gets refreshed, later, from whatever changed.

None of the four nouns disappeared.

There's no single Tour class anywhere holding them together - there's a TourId, threading through all four, at runtime (you might recognize this from where is "Tour" entity?).

The ambiguity of nouns

We can't design, or even talk, without nouns - they're how we carve "the wild", the undifferentiated reality out there, into things we can point at and reason about.

Not every noun refers to the same kind of thing, though - some are resources, some are views, some are plans, and some are verbs that learned to dress up as nouns to sneak past our attention.

System 1 can't tell them apart - they're grammatically identical, so it treats them identically, reaching for whichever one was loudest, earliest, or easiest - the one requiring the least effort to accept.

System 2 is what asks the second question - not "what is this called?" but "what does it hide?".

We've seen how a single concept ("a Tour") go transformed into a set of interacting concepts - seats availability, reservations, itineraries, and catalogues.

Each of newly organized terms could be further transformed - either "going up" (generalizing) or going down (specializing), when it comes to a business area.

But it all takes the effort, especially when a designer (an LLM operator) is not trained enough.

If we don't put enough attention and skills, we are going to base on "the reflexes" - which naturally tend to seeing whatever we already know.

Nouns are not inherently evil - it is always an operator's "fault" (ekhm, or responsibility).

Watch for absolute-sounding ones, dear Reader.

Slice them using time, perspectives, and then look for the depth.

So next time, dear Reader, when the world presents you a bunch of "things", slow down and ask yourself:

Imagine Nadia, a few months into her first job, and Marek, who reviews her pull requests.

The codebase is C#. A pragmatic, mid-sized system that calculates discounts for orders.

Nadia was asked to add a new rule - a seasonal discount that stacks with loyalty points, but only under certain conditions.

She wrote it. Tested it. It worked.

public static decimal ApplySeasonalDiscount(decimal total, int loyaltyPoints, bool isSeasonActive)
{
    if (!isSeasonActive) return total;

    var discount = loyaltyPoints > 100 ? 0.15m : 0.10m;

    return total - (total * discount);
}

Nadia shipped it.

The code was clean, the tests were meaningful, the rounding was correct to the cent.

By any craft standard, this was good work.

She even noticed the duplication with the other discount methods - a genuinely good catch.

But she asked, got waved off, and moved on to the next ticket.

"Why does it work this way?"

Two years later.

Nadia is no longer new. She has shipped dozens of features, fixed her share of production incidents, and by now she has opinions.

A new request lands - a fifth discount type, this time combinable with two others under specific business rules that nobody wrote down anywhere.

Notice what changed.

Nadia was no longer asking "does this compile, do the tests pass" - she was asking "is this the right shape for the problem, and what will it cost us later if it isn't".

She doubted the given approach.

She proposed an alternative, defended it, and accepted that it needed a conversation before any code got written.

She was reasoning about structure, not just output.

Notice what she did not ask.

She did not ask whether a fifth discount type made business sense, or whether pricing should be this configurable in the first place.

She trusted that someone above her had already answered that, and stayed entirely inside the solution space - given that this needs to be built, what is the right way to build it.

That boundary matters. She was designing. She was not yet questioning why there was anything to design at all.

"Would you bet your money on this?"

Another few years pass.

Same title. Same desk, more or less. Nadia is still an engineer on the same team, and Marek is still the lead who reviews her work.

Nobody promoted her into caring about what happens next. A new initiative arrives from above - a loyalty tier system with five levels, gamified badges, and a leaderboard.

Nadia had no more authority in this room than she had in the first scene. (well, she probably earned something through that time - do you know what it is, dear Reader?)

Nobody made her responsible for the roadmap. Nobody had to.

She questioned whether the request was the right one anyway, brought evidence anyway, and committed to building whatever got decided anyway - properly, without sulking about being overruled.

She cared whether the company's money and the customer's time were spent well - not just whether her part of the system was elegant, and not because a title told her to.

She cared about understanding Marek's point of view and his words - his mental model.

Hand(s), Head(s), Heart(s)

Three scenes.

Same person.

Different capability each time.

The first scene - a clean, well-tested discount rule, a good catch on duplication that got waved off - was Hand(s).

The second - doubting the given approach, proposing a real model instead of a sixth near-identical method - was Head(s).

The third - questioning whether the leaderboard deserved the quarter at all, and putting her name on that answer - was Heart(s).

You probably suspected as much while reading them.

That's the point - the labels were never the interesting part. What Nadia actually communicated was.

How could we explain each lens, in slightly reductionist terms?

Notice something about those three definitions, dear Reader.

You can point at Hand(s) - it's the diff. You can point at Head(s) - it's the sketch on the board, the alternative that got argued for in the meeting nobody wanted to sit through.

Heart(s) leaves no artifact of its own. It never shows up in the pull request, and no reviewer can approve it into existence.

It's the one ingredient in this whole potion that never makes it onto the label - and the only one that decides whether what you built was worth drinking.

Together, they're the lenses you compose, one on top of another: Hand(s), Head(s), Heart(s).

Unlike TEA, this is not a spectrum you move across depending on the situation.

It's a set of lenses, composed together - not swapped one for another.

Marek could not have asked Nadia for a design opinion in her first week, because she had nothing yet to doubt with.

She had to first know what "correct" looked like, with her hands, before she could sense that something was structurally wrong.

And she had to be trusted with structure, with Head(s), before her opinion on "should we build this at all" carried any weight in the room - no title required either time, just enough demonstrated judgment for people to want to hear it.

Hand(s) are necessary, not sufficient

Let's be fair to Hand(s), dear Reader.

Nobody gets to skip it.

A designer who cannot write the C# that expresses their own idea is not designing - they're speculating, and someone else pays for the gap between the speculation and reality.

A person with a strong opinion about ownership who cannot ship a working feature is not exercising Heart(s) - they're just having opinions, which is a much cheaper thing to do.

Nadia's clean rounding logic, her fifteen test scenarios, her instinct to notice duplication - none of that stopped mattering once she reached Head(s) and Heart(s).

It became the foundation everything else stands on.

The hidden cost of staying at Hand(s)

Here is what should worry you, dear Reader, if you have ever taken pride in shipping fast, and stopped there.

For a while, it works. It works remarkably well, even.

Tickets close. Velocity charts go up and to the right. Someone calls you "reliable".

Nobody tells us that reliability, at the Hand(s) level, is measured by how faithfully you execute someone else's understanding of the problem - not by whether that understanding was any good.

You are not asked "should we build this" because you have not yet earned the standing to be asked, and you have not yet practiced having an opinion worth defending.

Nadia noticed the duplication in her first scene and got told "not today".

That's not a failure of hers - that's simply what Hand(s) sounds like from the outside.

Competent, correct, and not yet invited into the room where the shape of the problem gets decided.

The codebase does not punish you for staying at Hand(s) immediately.

It punishes whoever is still there in three years, still confident that well-written code and passing tests were the whole job.

That's the dark side of staying at Hand(s) too long, dear Reader - not incompetence, but a comfortable kind of invisibility. You get very good at not being asked, and eventually you stop noticing that you've stopped being asked.

Head(s) without Heart(s)

The second failure mode is a bit more subtle, and in some ways more comfortable, which makes it more dangerous.

You've grown into Head(s). You doubt, you architect, you see the abstraction three moves ahead. People bring you problems because you're good at reshaping them.

And somewhere along the way, it stops mattering to you whether the thing gets built at all, or whether it was worth building.

You optimize the design of features you don't believe in.

You elegantly implement a leaderboard nobody asked for, because the elegance itself became the reward, detached from whether the customer's actual problem

This is the architect who can defend any decision technically and cannot tell you why the business or consumers should care.

Nadia in her second scene was already close to this - a genuinely better design, argued well, for a ticket she had not yet questioned the existence of.

It took another round or rounds, and a willingness to say "I don't think this deserves our quarter", to close that gap.

That's the dark side of staying at Head(s) too long - skill without meaning.

The trade-offs get sharper. The diagrams get cleaner.

Nobody asks anymore whether any of it was worth doing - least of all the person best equipped to ask.

Heart(s) - investment or cost?

The third scene cost Nadia something the first two did not.

The comfort of just doing what was asked. The safety of being able to say later "I only built what I was told to, it's not my call".

She traded that comfort for visible disagreement - for going on record against a decision that had already been made above her, with no title obligating her to try and no guarantee anyone would listen.

This is why so few people arrive at Heart(s) (and why organizations often prefer they don't?).

A room full of Hand(s) and Head(s) executes predictably.

Probably with the decent quality (whatever it means to you, dear Reader).

A room with Heart(s) in it argues, questions the premise, sometimes says no - and is, over any long enough horizon, the only kind of room that reliably builds things worth having built.

They argue, because they care.

Care about what?

About other people - whether they are customers or their colleagues.

Because nothing great (and valuable) was built when all agreed.

Extreme Programming was never a set of technical rituals adopted for their own sake - pairing, collective ownership, sustainable pace, whole-team responsibility for the outcome are what Heart(s), practiced daily, actually looks like from the outside.

You cannot mandate caring with a policy document.

Heart(s) requires mutual trust, and mutual is the part organizations skip in favor of procedures, control and governance.

What came first, dear Reader - the governance, or the lack of trust it was quietly built to compensate for?

Nadia had to trust that "I'd rather we spend the quarter on checkout" wouldn't cost her the next uncomfortable conversation she needed to have. Marek had to trust that her pushback was an honest read of the data, not insubordination wearing a lanyard. Remove either half of that trust and the exact same words curdle into either silence or noise.

You can only build the conditions where people who've already grown through Hand(s) and Head(s) are trusted enough to start caring out loud - and where that trust is returned, not just extended.

Quite too idealistic, isn't it?

Maybe.

Heart(s) has a dark side too, and it shows up when someone stays there without ever going back down to do the work.

Caring out loud is cheap once it stops costing you anything.

Opinions about every decision. Delivered from the sidelines. By someone who hasn't shipped a feature or sketched a design in years.

That still sounds like Heart(s).

It's trust, spent on volume, long after it stopped being earned.

Everyone in the room can tell the difference. Nobody says it out loud.

Where does the LLM fit in this?

I bet, you knew this question was coming, dear Reader.

Here is the uncomfortable part: an LLM is remarkably good at Hand(s).

Give it a clear specification (by the way, dear Reader, what is a "clear specification"? How do you know it's "clear" - clear to whom, and clear until which surprise arrives?), a language, a test - and it will produce something that compiles, sometimes something well-designed, occasionally something you'd have written yourself given enough coffee.

As explored in LLMs, 3D printers and amplifiers - it works as an amplifier of whoever is directing it, not as a replacement for the judgment doing the directing.

An amplifier has no opinion about whether the song is worth playing.

It plays whatever signal it is fed, louder.

There's a reason the fit is this good, and it isn't flattering to how the profession has treated Hand(s).

Stripped of Head(s) and Heart(s), Hand(s) was always a mercenary way of working.

Grunt labor, however well-crafted.

Take the specification. Produce the artifact. Move to the next ticket.

No opinion required. Frequently none welcome.

It was already transactional - and transactional work is exactly what a model trained on transactions reproduces well.

Head(s) asks for something it cannot manufacture on demand.

Reasoning about optionality. About the structure - elements, interactions and purpose - an architecture should have. About which trade-off costs less in eighteen months.

It can list you three options when asked.

It cannot sit with the discomfort of not yet knowing which one is right.

It has no stake in being wrong about it.

Heart(s) sits further out still.

It isn't really a technical faculty to begin with - it's a humane, social one.

Whether a leaderboard deserves a quarter of a real team's time is not a question about code.

It's a question about people - what a company owes the customer in front of it, versus what it owes its own comfort.

And people doesn't stop at the customer. It includes the teammate who inherits whatever gets decided here.

"What do you have in mind?"

"What does it mean to you?"

"What is it important to you?"

Ask them of a customer. Ask them of a colleague. The question doesn't change - only who's answering it does.

It's by, with, and for people, all the way down.

A model has no colleagues to let down. No customer to fail. No finite quarter of its own working life to spend on the wrong bet.

It cannot care, in any sense worth the word.

Caring requires something to lose.

Which means the era in which "I write well-crafted code quickly" was, on its own, a durable professional identity is quietly closing - not because writing it well stopped mattering, but because the scarce part of that sentence was never the typing.

But Heart(s) does not get to skip looking at what Hand(s) produced.

Someone still has to read the diff.

It makes no difference whether the Hand(s) that typed it were biological or virtual - a person's, or a model's, prompted by that same person.

If Hand(s), purely as execution speed, is now something you can rent by the token, then the only thing left that was ever actually yours is the Head(s) that decided what to build, and the Heart(s) that decided whether it deserved to exist (and how you are communicating with other human beings).

That should not read as a threat, dear Reader, though I understand if it does.

"Typing was never the bottleneck", some might boldly say so.

Even if it was not the bottleneck, building understanding through fast feedback loops was.

Learning is a real bottleneck.

Knowledge acquisition is a real bottleneck too.

Insights and conceptual framing are bottlenecks as well.

Typing might and often helps with that.

Why?

Typing is thinking.

It was simply the most visible part of the job, and the easiest one to reward.

We tricked ourselves, stakeholders included, into thinking that coding, Hand(s), was the entirety of the work.

There's more to it than that, we just need to escape the matrix.

Composing, not switching

In TEA, where you consciously move between Telling, Explaining and Aligning depending on what a given conversation needs, Hand(s), Head(s) and Heart(s) don't offer you that choice in the same way.

You do not wake up and decide to "do some Heart(s) today" the way you might decide to explain something more carefully.

You add a lens, and mostly, you don't remove the ones beneath it - you keep looking through every lens you've already installed, every day, for the rest of your career.

Nadia at the Heart(s) level still writes C# on a Tuesday when the team needs her to - through the Hand(s) lens, same as always.

She still doubts a design on a Wednesday - through Head(s).

The difference is that she no longer sees through either lens alone. Heart(s) sits on top now, and everything below it gets seen through it too.

"What are you doing?"

You've heard some version of this one already, dear Reader.

Three stonemasons, same building site, same question put to each of them: "What are you doing?"

The first says: "I'm laying bricks."

The second says: "I'm building a wall."

The third says: "I'm building a cathedral."

Same bricks. Same mortar. Same hands.

Really same?

"The level is in the eyes of the beholder."

The first looks through Hand(s) - one brick set correctly after another, according to the pattern he was handed. (sometimes without care and understanding, unfortunately)

The second looks through Head(s) - the brick matters because of the wall, the load it carries, the plan it has to satisfy. (sometimes without seeing the bigger picture, unfortunately)

The third looks through Heart(s) - the wall matters because of the cathedral, and the cathedral matters because of who will stand inside it, long after his own name is forgotten.

None of the three is lying.

None of them is wrong, exactly.

Same as with this well-known motivational tale about stonemasons,Hand(s), Head(s) and Heart(s) are here to communicate something more profound over a simple metaphor.

Metaphors are imperfect, but they can help us see the world in new ways.

Looking for logical holes and inconsistencies in metaphors can be a useful exercise, but it's not the primary goal.

Be free with your interpretations.

Be free with your tempo.

Be free.

Play with that.

Let yourself flow with the uncharted sensations that are true vessels of understanding.

Understanding of thyself.

Understanding of the world around you.

Starting small

You don't need a promotion to start installing the next lens.

It starts with a single question the next time you're handed a ticket.

Or more general, questioning.

The gap between Hand(s) and the lenses stacked above it is not talent, dear Reader.

It is curiosity.

It is hard work.

It is slowing down.

It is saying "I don't know".

It is mostly the accumulated habit of not being asked, and therefore never practicing the answer.

Meet Tom (you might recall him from Many Faces of DDD Aggregates in F#) and from The ambiguity, the curse and the fallacy of domain model).

As a successful businessman, after he earned tons of money with disco clubs and creating video games, with his business nose, he felt there's a niche in the market.

Tom says:

Hi there! Long time, no see.

I got an amazing idea - "thanks" to LLMs and AI technologies people forget things easily.

Sooner or later, they will forget how to calculate a simple division!

Can you help me with building a service around it?

It will have a bunch of features, but nothing too complicated.

Just talkListening carefully

A division?

It seems we need to explore this area a bit more.

Good that we have Tom to guide us and we are pretty skilled with collaborative exploration.

Let's have a quick event storming session! (because that's what cool kids do, right?)

"Ok, tell us more about the division - what is it all about?", we asked.

After this little question, we spent 1 hour exploring Tom's idea (during which Tom mostly rambled about how great it is) and it turned out we didn't capture that many business facts.

the output from our exploration

It was quite hard to cut in Tom's enthusiastic monologue, so we ended up with not-so-clear idea of his idea (pun intended).

Specification by example to the rescue!

Maybe it's time to involve Tom in more concrete examples and scenarios to clarify his idea?

Definitely we should go and ask him to walk us through a few specific cases.

It will help us with implementing this feature.

Tom says:

Special cases?

I don't know what might be special in the division, but let me try to explain it!

Just talkListening carefully

And we went into executable specifications mode, trying to nail down the details of his idea.

Outside-In development perspective is deeply rooted in our heart, so we started from writing down a need-driven, executable, acceptance criteria.

    [Theory]
    [InlineData(10, 2, 5)]
    [InlineData(9, 3, 3)]
    [InlineData(7, 2, 3.5)]
    public async Task given_dividend_and_divisor_when_dividing_then_returns_expected_result(int x, int y, double expected)
    {
        var response = await _client.GetAsync($"/divide/{x}/by/{y}");

        response.EnsureSuccessStatusCode();
        var result = await response.Content.ReadFromJsonAsync<double>();
        Assert.Equal(expected, result);
    }

Next step in our 3S workflow is to satisfy the specification, we write down the implementation to make the tests pass.

app.MapGet("/divide/{x}/by/{y}", (int x, int y) => (double)x / y);

And puff, tests got green.

Tom gave us happy-path examples and of course we asked him about "the special case".

"You don't know what is the 'special' case of division? I told you people will forget that!", he yelled.

"Dividing by zero, of course!", he continued, a bit calmer this time.

So we captured that as an executable specification too.

    [Fact]
    public async Task given_a_dividend_and_zero_as_divisor_when_dividing_then_returns_unprocessable_entity_with_problem_details()
    {
        var response = await _client.GetAsync("/divide/10/by/0");

        Assert.Equal(HttpStatusCode.UnprocessableEntity, response.StatusCode);

        var problemDetails = await response.Content.ReadFromJsonAsync<ProblemDetails>();
        Assert.Equal("Cannot divide by zero.", problemDetails?.Detail);
    }

Back to satisfying the specification, we extend the handler to cover the zero-divisor case.

app.MapGet("/divide/{x}/by/{y}", (int x, int y) =>
    y == 0
        ? Results.Problem(detail: "Cannot divide by zero.", statusCode: StatusCodes.Status422UnprocessableEntity)
        : Results.Ok((double)x / y));

It's a bit of a shame that we didn't figure it out earlier, but at least we have a clear specification now, right?

Close collaboration definitely helped distilling the domain part of the problem. We could follow the 3S workflow and follow up the simplification phase and refactor toward a real domain model.

So the arithmetic and its failure mode moved out of the handler and into a Calculation that knows how to Divide.

public static class Calculation
{
    public static Result<double> Divide(int x, int y) =>
        y == 0
            ? Result.Failure<double>("Cannot divide by zero.")
            : Result.Success((double)x / y);
}

And the handler shrunk down to translating that result into an HTTP response.

app.MapGet("/divide/{x}/by/{y}", (int x, int y) =>
{
    var result = Calculation.Divide(x, y);

    return result.IsSuccess
        ? Results.Ok(result.Value)
        : Results.Problem(detail: result.Error, statusCode: StatusCodes.Status422UnprocessableEntity);
});

Tests stayed green, but now the rule "you cannot divide by zero" lives in one obvious place instead of being tangled with routing and HTTP status codes.

That's the software engineering way: yeehaa!

Because we were modelling together, Tom saw the code and wasn't even impressed by the usage of Result.

Poor Tom is not aware of monads.

We could also improve the code and map, don't ask.

app.MapGet("/divide/{x}/by/{y}", (int x, int y) =>
    Calculation.Divide(x, y).Match(
        onSuccess: value => Results.Ok(value),
        onFailure: error => Results.Problem(detail: error, statusCode: StatusCodes.Status422UnprocessableEntity)));

Functional-first thinking baby!

This time we don't even show it to Tom, he wouldn't admire the greatness of it.

Ah, we also forgot about publishing events - as we explored the domain earlier, wouldn't it be a waste if we didn't do it?

Let's add missing specs.

    [Fact]
    public async Task given_a_dividend_and_a_non_zero_divisor_when_dividing_then_publishes_division_calculation_completed()
    {
        var eventTracker = new FakeEventTracker();
        var client = _factory
            .WithWebHostBuilder(builder => builder.ConfigureServices(services =>
                services.AddSingleton<IPublishEvent>(eventTracker)))
            .CreateClient();

        await client.GetAsync("/divide/10/by/2");

        var completed = Assert.IsType<DivisionCalculationCompleted>(Assert.Single(eventTracker.Events));
        Assert.Equal(10, completed.Dividend);
        Assert.Equal(2, completed.Divisor);
        Assert.Equal(5, completed.Result);
    }

    [Fact]
    public async Task given_a_dividend_and_zero_as_divisor_when_dividing_then_publishes_calculating_division_failed()
    {
        var eventTracker = new FakeEventTracker();
        var client = _factory
            .WithWebHostBuilder(builder => builder.ConfigureServices(services =>
                services.AddSingleton<IPublishEvent>(eventTracker)))
            .CreateClient();

        await client.GetAsync("/divide/10/by/0");

        var failed = Assert.IsType<CalculatingDivisionFailed>(Assert.Single(eventTracker.Events));
        Assert.Equal(10, failed.Dividend);
        Assert.Equal(0, failed.Divisor);
        Assert.Equal("Cannot divide by zero.", failed.Reason);
    }

    private class FakeEventTracker : IPublishEvent
    {
        public List<object> Events { get; set; } = new();

        public Task Publish<TEvent>(TEvent @event) where TEvent : notnull
        {
            Events.Add(@event);
            return Task.CompletedTask;
        }
    }

Specs complete!

Are we done?

The M-word?

What is the M-word that Tom is mostly interested in?

No, it's not Monads, sorry.

It's M-oney.

Tom says:

Finally, we talk about money.

I saw this division in action, but it's nothing amazing, to be fair.

As soon as people start forgetting how to divide because of LLMs, we are going to be rich.

You might wonder - how?

That is simple.

Whenever a calculation is performed, we charge the user a small amount of money, that's it.

They will not notice it, because it'll be so small.

Millions of users, times a small amount, adds up quickly.

Just talkListening carefully

Division feature was super easy, the domain was trivial - we know how to divide.

Ok, charging users might be more interesting.

Thankfully, we know that communication at the right level is vastly important and that collaboration is the key to success - that's why we invited Tom back to the event storming board.

the output from our exploration

If you listened carefully, dear Reader, you might have noticed that there "whenever" keyword appeard in Tom's message.

If we take an interpretation of Alberto's picture that explains (almost) everything, you might recall we might be talking about a policy.

It sounded as if we are going to transform DivisionCalculationCompleted into a command ChargeUser that will eventually lead to a fact UserCharged happening.

That's definitely our a brilliant observation - domain modelling in its fullness!

Tom was not that impressed - we put some more stickies, but for him it was pretty obvious - that's what he exactly said, isn't it?

We tried to tell him what we have discovered, why events are important, what is a command, and what a policy means - but he wasn't that interested.

It's not his area of expertise, maybe that's why he is not seeing the depth of our work.

To complete the session, let's add missing commands.

Seems like we understood what is required by Tom, let's finally go to the code.

We are charging a user, so definitely we need to create the domain model that will represent this concept of a User.

What information do we need User to have in order to satisfy Tom's requirements?

Definitely some identification - who they are.

Then some details needed to charge them - for transferring money.

We quickly sketched what "charging a user" probably needs. Surely, a User with some billing details bolted on will do?

public class User
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }

    public string CreditCardNumber { get; set; }
    public DateTime CreditCardExpiry { get; set; }
}

Looks reasonable, doesn't it? A name, an email, and just enough fields to charge someone.

Of course we know that our models should be focused on behaviors rather than just data.

But we will express it as an executable spec!

"Whenever"

Thankfully, we listened carefully and we know that a policy means a reaction - so we need to create an event listener that will do the proper transformation of incoming event into a command.

    [Fact]
    public async Task given_a_dividend_and_a_non_zero_divisor_when_division_calculation_completed_then_user_is_charged_with_tiny_fee()
    {
        var user = new User
        {
            CreditCardNumber = "4111111111111111",
            CreditCardExpiry = new DateTime(2030, 1, 1),
            BaseCalculationFee = 0.01m
        };

        var gateway = new FakePaymentGateway();
        var client = _webApplicationFactory
            .WithWebHostBuilder(builder => builder.ConfigureServices(services =>
            {
                services.AddSingleton<IUsersRepository>(new FakeUsersRepository(user));
                services.AddSingleton<IPaymentGateway>(gateway);
            }))
            .CreateClient();

        await client.GetAsync("/divide/10/by/2");

        var transfer = Assert.Single(gateway.Transfers);
        Assert.Equal(user.CreditCardNumber, transfer.CardNumber);
        Assert.Equal(user.CreditCardExpiry, transfer.CardExpiry);
        Assert.Equal(user.BaseCalculationFee, transfer.Amount);
    }

    private class FakeUsersRepository : IUsersRepository
    {
        private readonly User _user;

        public FakeUsersRepository(User user) => _user = user;

        public Task<User> GetAsync(Guid id) => Task.FromResult(_user);
    }

    private class FakePaymentGateway : IPaymentGateway
    {
        public List<PaymentDetails> Transfers { get; set; } = new();

        public Task Transfer(PaymentDetails details)
        {
            Transfers.Add(details);
            return Task.CompletedTask;
        }
    }
}

Of course, the spec fails as there is no logic built-in that will ensure the required behavior - let's add it!

First, IPublishEvent needs a partner in crime - something that lets a reaction subscribe to the events flowing through it.

public interface IHandleEvent<TEvent>
{
    Task Handle(TEvent @event);
}

Object providing this capability will get the easiest (requiring the lowest effort) implementation - so we'll omit it for brevity.

User is going to be much more interesting element, because we want it to be fully object-oriented.

What does it actually mean?

A User knows how to charge itself, given a gateway and its own tiny fee - behavioral modelling for the win!

public class User
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }

    public string CreditCardNumber { get; set; }
    public DateTime CreditCardExpiry { get; set; }
    public decimal BaseCalculationFee { get; set; }

    public async Task Charge(IPaymentGateway @using)
    {
        var gateway = @using;
        await gateway.Transfer(new PaymentDetails(CreditCardNumber, CreditCardExpiry, BaseCalculationFee));
    }
}

The policy, the event handler, works with its collaborators to actually deliver specified behavior.

public record DivisionCalculationCompletedEventHandler(
    IUsersRepository Users,
    IPaymentGateway Gateway
) : IHandleEvent<DivisionCalculationCompleted>
{
    public async Task Handle(DivisionCalculationCompleted @event)
    {
        var user = await Users.GetAsync(@event.CustomerId);
        await user.Charge(@using: Gateway);
        await Users.SaveAsync(user);
    }
}

And finally, the policy subscribes to a particular event - DivisionCalculationCompleted.

builder.Services.AddScoped<DivisionCalculationCompletedEventHandler>();
builder.Services.AddSingleton<IPublishEvent>(services => new InMemoryMessageBus(services));

var bus = (InMemoryMessageBus)app.Services.GetRequiredService<IPublishEvent>();
bus.Subscribe<DivisionCalculationCompleted, DivisionCalculationCompletedEventHandler>();

We execute the specification we wrote earlier and...It's ✅.

Software works exactly as we understood it to, from the expectations we were told to represent.

How cool is that?!

We presented the specifications to Tom so that he could approve our understanding - because we used business language in the spec names, it should be straightforward for Tom to verify.

We got ✅ from him too.

Nice!

A side-effect of our design with events is that in case of scaling - we can distribute the event handling across multiple instances or services, allowing for better performance and reliability.

Our architecture is very simple - it contains two elements:

It does not look like those overengineered architectures you often see in presentations.

Simple requirements, simple architecture, right?!

Change, change never changes

Tom went out to check our newly developed services.

Some time passed and he came back with interesting observations.

Tom says:

Our users love the new service!

As I predicted, people started forgetting how division is working and they got hooked!

Some users are not happy with charging by the usage.

Those userswould rather put some money in advance and controlhow much money they spend.

This might be very interesting, because we could offer some seasonal bargains- instead of charging 1 dollar from your prepaid money, we take half of it.

Nice idea, isn't it?

Just talkListening carefully

Preloaded money seems like a good idea - our architecture could definitely support it out of the box.

We designed the domain model taking into the account the behavioral level everything will be encapsulated in the Charge behavior of User.

It looks as an easy feature, so we don't bother Tom with event storming session - we asked him directly about how to determine charging method.

Tom says:

To me, it looks like some kind of configuration that users can set up

We should not overcomplicate things - a user chooses either prepaid or not.

Just talkListening carefully

Configuration - of course!

Can you figure it our dear Reader where how this change is going to look?

I bet you can.

public class User
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }

    public string CreditCardNumber { get; set; }
    public DateTime CreditCardExpiry { get; set; }
    public decimal BaseCalculationFee { get; set; }
    public bool IsPrepaid { get; set; } // 👈 new information!
    public decimal PrepaidAmount { get; set; } // 👈 new information!

    public async Task Charge(IPaymentGateway @using)
    {
        if(IsPrepaid) // 👈 new section!
        {
            if(PrepaidAmount >= BaseCalculationFee)
            {
                PrepaidAmount -= BaseCalculationFee;
                return;
            }
            else
            {
                throw new InvalidOperationException("Insufficient prepaid amount.");
            }
        }

        var gateway = @using;
        await gateway.Transfer(new PaymentDetails(CreditCardNumber, CreditCardExpiry, BaseCalculationFee));
    }
}

It turned out quickly that with the current organization of elements, when a user has prepaid charging configured, they go below the limit after the division calculation was completed - so they already have used the service.

The worst thing was that we didn't want to couple calculating division with information about users - in order to control it on the calculation side, we would need to read the user's prepaid status and amount.

We tried to explain it to Tom in terms of best practices, but Tom wasn't particularly happy about not earning money.

Also, after the initial testing with the real users, it might be that we would need to introduce some kind of a limits for each user? At least that's what Tom said briefly.

Tom says:

I have another brilliant idea for a feature.

Next to limits, we will apply a delayso that if a user wants to get his division results sooner, they need to pay extra!

Just talkListening carefully

This is very interesting feature.

How will a User look like after introducing that change?

High chances are that there will be some kind of a BaseDelay.

public class User
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }

    public string CreditCardNumber { get; set; }
    public DateTime CreditCardExpiry { get; set; }
    public decimal BaseCalculationFee { get; set; }
    public TimeSpan BaseDelay { get; set; } // 👈 new information!    
}

Ok, after this change we would definitely couple users and calculations.

We swallow a hard pill and let it be - if a fellow architect asks, we would tell them that Tom wanted that, according to his specs, right?

Tom says:

Ah, and by the way, I also want to apply a precision trimming when returning a calculation result for the userthat requested it.

So if they want to get more precision, they need to pay us.

The sooner we ship it, the better.

Just talkListening carefully

Even though it might sound complicated, it is fairly easy and straightforward.

It sounds like yet another configurable parameter that user can select and pay for.

public class User
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }

    public string CreditCardNumber { get; set; }
    public DateTime CreditCardExpiry { get; set; }
    public decimal BaseCalculationFee { get; set; }
    public TimeSpan BaseDelay { get; set; }
    public int Precision { get; set; } // 👈 new information!
}

Ok, seems like we need to go and implement features in the core logic.

Since delay and precision now live directly on the User, the handler needs to know who is asking - a customer identifier joins the route, and the handler reaches straight into their record for the numbers it needs.

app.MapGet("/divide/{customerId}/{x}/by/{y}", async (
    Guid customerId, int x, int y,
    IUsersRepository users,
    IPublishEvent events) =>
{
    var result = Calculation.Divide(x, y);

    if (!result.IsSuccess)
    {
        await events.Publish(new CalculatingDivisionFailed(x, y, result.Error));
        return Results.Problem(detail: result.Error, statusCode: StatusCodes.Status422UnprocessableEntity);
    }

    var user = await users.GetAsync(customerId);

    await Task.Delay(user.BaseDelay);
    var trimmed = Math.Round(result.Value, user.Precision);

    await events.Publish(new DivisionCalculationCompleted(customerId, x, y, trimmed));

    return Results.Ok(trimmed);
});

"What's next boss?"

Let's slow down for a while and think.

We rolled out so many features, we used collaborative methods, applied functional programming, object-oriented design and many more.

We tried to control coupling between services.

Everything seems fine.

But what are the predictions about our little system?

User entity is getting bigger, attracts more and more information.

At the beginning, we focused so much of our quality time into exploring the details of dividing, but it somehow feels odd.

The more features we got on our plate, the more it seems it is just an element of the entire puzzle.

Hm, we tried to apply all those industry best practices, at least when it comes to working together, as a team.

Literally, whatever Tom brought to us, we listened carefully and tried to build up understanding and apply it, representing important concepts like Calculation, User.

"It is a toy example Damian, in real systems no one is so naive as you tried to be", some might actually say.

Well, I didn't say we are going to build a big system during this tale.

If we take John Gall's law:

It might be that our toy example will eventually grow into something bigger, even if it looks deceivly simple at the moment.

We started with a simple, but central division feature, and ended up as it being pushed to the side, in favor of other aspects of the system.

Aspects of the system or aspects of the business?

What a calculator has to do with a business?

Imagine that our initial conversation with Tom looked slightly different.

Tom had his ideas, brilliant ones, not to diminish them.

But they needed to be worked on, at least slightly.

We used our way of thinking to understand and refine them.

Analyze how to decompose concepts firstly, sometimes suggesting, a bit speculatively, how to organize them.

After a short discussion which started from a simple division and users, we ended up with ideas about:

• users
• customers
• calculation tokens
• calculation orders
• billing

"This is so Big Design Up-Front Damian!", some might resist.

Well, what if those concepts were there, but uncovered?

Many of the businesses and human activities have common ideas, especially when it comes to universal concepts like selling/ordering/billing, and so on.

Who's fault, I mean responsibility, is to make those concepts explicit?

Often times, our domain experts or business owners are the ones who have the most knowledge about their area of expertise, but they are not trained in abstract thinking.

A particular way of experiencing the world around.

So what a calculator has to do with a business?

In a way, nothing and everything at the same time.

It is a basic capability that we are selling an access to.

Initially, Tom did not reveal us "the depth" of this area - but when we consciously explored it, trying to understand the main ideas driving the whole endeavor, it seems we saw this "depth".

Of course it required being proactive and also suggest organizing the concepts in the certain way.

Not only receiving what Tom told us, but also process, reflect and pushback.

"The depth" that got mentioned, might be directly related to different levels at which our concepts live.

Those "levels" appear in the literature in various forms, but the universal pattern is similar - our systems are not "flat", and there are various dimensions that we should use while we're analyzing, understanding, decomposing systems.

Same with our tiny tale:

Domain responsibility layers

Doing all of that work will eventually lead to User concept disappearing, at least in the form we experienced it in this tale.

It also enriches the language we might use while talking to each other.

An avid Reader might have already noticed a subtle feedback given by earlier specs, when it comes to a concept of User:

var user = new User
{
    CreditCardNumber = "4111111111111111",
    CreditCardExpiry = new DateTime(2030, 1, 1),
    BaseCalculationFee = 0.01m
};

Even though we create a new instance of User object, the information used in the test are focusing on a very specific perspective of it.

Coincidentally mixing up aspects and creating the domain model might sound easy, but definitely it is not simple.

Even tests were whispering to us, giving diagnostic signals, but it strongly depends on our ability to listen to them.

Requirements? Features? Concepts?

Often times, we get "the requirements" which turn out to be unprocessed thoughts - they might have their value, but still they need a little bit more effort when it comes to ensuring they fit the conceptual integrity of our system.

Those "requirements" or "features", branded as "simple", hide interesting and important abstract ideas behind.

And this is our job to check how they interact with the rest of the system.

But when I say "interact", it does not only mean "technically interact" - method calls, sending HTTP requests and so on.

It also means "conceptually interact" - as you experienced that earlier dear Reader, when we had a lengthy discussion with Tom.

Before jumping to any coding or solutioning, we should think about composing a PIE.

Two questions I find particularly interesting, powerful and useful, are:

or

They require me to enter analysis mode where I try to purposefully explore the problem area.

Each requirement, feature or expectation, has deeper structure buried underneath.

Unfortunately, they don't communicate this conceptual structure explicitly and immediately.

It requires an investment, human effort, to lean over it and start seeing underlying ideas.

Recall dear Reader what Tom initially told us - "it is a simple division" - we got hooked in by this framing and the rest is just history.

That's why naming is framing - as soon as the label/name appears, it shapes the world we experience and we see.

It requires stepping outside of the invisible box, the invisible frame, and start asking questions:

• "Why is it important?"
• "What are the main questions are we looking answers to?"
• "What is the goal?"
• "What do we try to accomplish when doing X?"
• And so on...

Those questions are there not to critique, but to understand.

To synthesize the knowledge, and frame the right conceptual structure that will hold the rest of the system.

We must do it, because the information we often initially get is unstructured, ambiguious and contradicting.

Ambiguity has no problems with getting compiled.

Also, ambiguity does not throw NonsenseException.

Software design is about untangling ambiguity and organizing various structures - but please don't conflate them with "data structures".

It's far more than that.

More like building theories, however, I would rather brand it as "conceptual structuring" or "organizing conceptual structures".

It is necessary effort, but insufficient, on its own.

Our software systems live in numerous dimensions - and conceptual is only one of them.

We have runtime as well.

So those technical matters are still greatly important, because slowly responding, but perfectly modeled systems is not particularly useful for users or customers.

Software design might be regarded as a continuous process of searching deeper conceptual structures.

It strongly depends on the problem area we are operating in - tools solving a particular problem might be bounded enough so that the search might end pretty quickly, whereas business environments can cause neverending forces that will require concepts to die, emerge and transform.

Everything starts with a question

The quality of questions is the quality of answers.

As someone once said, "A question contains the half of the answer".

As naming is framing, framing questions is framing the way we think.

We can use various tool like event storming, example mapping, specification by example and more, but if we don't look for deeper conceptual structures, "the theories", we might just slight on the surface.

If we remember that tools make fools, we might resist the temptation to rely solely on them.

Clearly thinking operator, the designer who know how to build, is the secret sauce here.

Clear thinking gets amplified, noisy thinking gets amplified too.

Often times the clarity comes from collaboration, but as we saw, at least one side of the conversation needs to be able to exercise the deep conceptual thinking.

A simple division might hide the complexities of business systems, only if the operator is capable of reasoning using the variety of dimensions.

Domain-Driven Design might be frequently conflated with "tactical patterns", but essentially it is a simple (but not easy, which means effort-requiring) call to collaborate in order to establish conceptual organization, where the ambiguity is primarly observed.

It might be that we are facing a basic business capability, like division, that is surrounded by other contexts, which in the first glance are invisible.

There are certain business operations that utilize those capabilities, and the specificity of the logical order of interactions, is what might be truly volatile, hence requires encapsulation - a true criteria for decomposing a system.

So next time dear Reader, when you hear "a simple requirement", ask yourself:

Imagine two senior software engineers, Sarah and Sam, sitting in a call.

Both have been in the industry for years.

Both know their craft.

Sarah has been at the company for years - she knows every corner of the system, every decision, every failed experiment that led to where things are today.

Sam has just joined. Experienced engineer, but new to this particular system.

Sarah is doing the onboarding.

The topic is complex - an event-driven, distributed architecture with multiple bounded contexts and asynchronous message flows.

How do you think, dear Reader, did Sam get it?

He didn't even know what question to ask.

A few days later, Sam sat down alone to implement his first change.

No one around.

Just him, the codebase, and a mental model assembled from thirty minutes of acronyms.

He touched the wrong layer entirely.

When Sarah found out, she said: "But I told you - BDG doesn't own that, it goes through the MTR Saga."

She was right.

She did tell him.

Alone, isolated from the heads that held the real context, Sam had only the words - not the understanding behind them.

Sarah had no idea.

She was too fluent in the language of the system to notice that each sentence she spoke was an acronym stacked on an assumption, with no shared ground beneath.

Because she was only at the Telling level.

"Does it make sense so far?"

A week later, Sarah noticed something after hearing back from a colleague that Sam had been asking very basic questions in team chat for days.

Questions that the onboarding was supposed to answer.

So she tried something slightly different.

This time, Sam walked away with something real.

Not everything, but enough to ask the right questions.

Sarah was now at the Explaining level - checking if the signal was getting through, adjusting based on what came back.

Still, there was something missing.

She was the one drawing the picture.

Sam was receiving it.

"Can you tell me what you understood?"

Another session.

This time Sarah decided to approach it differently.

She opened a shared canvas - a blank excalidraw board - and put it in front of both of them.

Sam drew it.

Sam discovered it.

Sarah guided him there, but the understanding belonged to Sam now.

Because they were collaborating on the Aligning level.

What is TEA?

Three conversations.

Same topic.

Very different outcomes.

What distinguished them was not the information - it was the direction of the communication and who was responsible for creating the conditions for growing the understanding.

Let's bring some definitions, because they might be useful.

Together, they form TEA - Telling, Explaining, Aligning.

Three levels of communication intensity when it comes to conveying abstract ideas and collaborating with others.

Not a ladder to climb once and stay at the top.

A range to move through, consciously, depending on what the situation demands.

Why does it matter?

"Communication always fails, except by accident" - as Wiio's laws remind us.

And as we explored in Keep it visible, smartass - words are volatile, invisible by nature.

Spoken words are impermanent.

They dissipate.

The mental model built in the sender's head and the one assembled in the receiver's head might share a few words, but diverge significantly in meaning.

And neither side knows it.

Because it is invisible.

The first conversation between Sarah and Sam - pure Telling - is the most common mode of illusionary knowledge transfer in software teams.

Architecture reviews, onboarding sessions, design discussions, incident post-mortems.

Someone talks.

Others nod.

And everyone leaves with a slightly different map of the same territory.

Then the codebase pays for it.

Telling is not wrong

Let's be fair to Telling.

It has its place.

When context is genuinely shared, when the audience is already aligned, when speed is the constraint - Telling is appropriate and efficient.

But how do you know, dear Reader, that we can stay at the Telling level?

A standup update is Telling.

A well-written ADR is Telling.

Briefing a team that already lived through the same decisions is Telling.

The problem is not Telling itself.

The problem is defaulting to the Telling level when the Explaining or Aligning level is needed - because it feels easier - which might seem faster - or because we assume shared context that isn't there.

The hidden cost of assumed understanding

Notice what Sam said in the first conversation.

"Yeah, yeah."

Not because he understood.

Because he didn't know what he didn't know.

This is Dunning-Kruger applied to receiving information - you cannot ask about the gaps you cannot see.

And Sarah filled the silence with confidence.

Silence is not agreement.

Silence is not understanding.

Silence is what happens when someone doesn't have the vocabulary to ask.

Provide the context.

Provide the vocabulary.

Provide abstract ideas supported by examples.

Visualize the language - put it on the board, write down the words as they appear, draw the boxes as the concepts emerge.

When Sam sees "BDG" and "MTR Saga" written down next to each other with an arrow between them, he has something to point at.

He can say "what is this arrow and what does it mean?" instead of not knowing what he doesn't know.

The board doesn't just capture ideas - it creates the vocabulary that makes questions possible.

The first conversation produced an illusion of alignment.

Both parties left feeling good about it.

The team chat told the truth a week later.

Explaining is not enough either

The second conversation was better.

Sarah asked "does it make sense?" and waited.

Sam even pushed back on the compensating transaction part.

Real signal came through.

But notice who held the pen.

Sarah owned the mental model and was handing pieces of it to Sam.

Sam was receiving, validating, acknowledging.

His understanding was still a pale copy of hers - not a structure he built.

When he would sit down to implement something a week later, he would be working from a received model.

Received models are fragile.

They don't survive contact with new information well.

And they are easy to misremember.

Aligning is the investment

The third conversation was slower.

It required a shared canvas.

It required Sarah to give up control and let Sam drive the drawing.

It required Sam to be wrong in front of her and not feel bad about it.

But something happened at the end of that conversation that didn't happen in the previous two.

Sam made an inference on his own.

"The Saga is the only thing that sees the whole picture. The other services don't know about each other."

Sarah didn't say that.

Sam derived it.

That's the difference.

When someone can derive the conclusion from the structure they built themselves, the understanding is theirs.

It can be extended.

It can survive contact with new information.

It can be taught to the next person.

From invisible to visible

All three levels of TEA benefit from making things visible - but the Aligning level depends on it.

You cannot align on an invisible mental model.

The canvas in the third conversation was not a nice-to-have.

It was the mechanism through which alignment became possible.

Sam's drawing was wrong in places.

That was the point.

The assumptions became visible.

It could be corrected.

As Alberto Brandolini wisely noted - don't talk about invisible things.

And as we know from Keep it visible, smartass - making things visible is what surfaces assumptions, gaps and misunderstandings that would otherwise remain hidden forever.

In Telling, nothing is visible.

In Explaining, the sender's model is visible.

In Aligning, the receiver's model becomes visible - and that's where the real work happens.

Which mode to use?

This is not about always doing full Aligning level sessions.

That would be exhausting and inefficient.

TEA is a spectrum, not a prescription.

The question to ask is: "what is the cost of misalignment here?"

If Sam misunderstands a team social event - low cost, Telling level is fine.

If Sam misunderstands why boundaries are organized in a certain way, or what event-driven thinking really means for how things are structured - the cost is high, and it grows with time. Every decision made on top of a misunderstood foundation adds another layer of drift. Weeks later, no single change is cheap anymore.

The less shared context there is, the more abstract the topic, the higher the stakes - the further along the TEA spectrum the investment should go.

"We only have 30 minutes" is often said precisely in the situations where the Aligning level matters most.

And 30 days of work can save 30 minutes of Aligning.

Starting small

You don't need to organize a full collaborative modeling session to practice Aligning.

It starts with a single sentence.

Instead of "did you get it?" - try "can you tell me what you understood?".

Instead of "does this make sense?" - try "can you draw what you heard?".

Instead of assuming the nod means understanding - treat it as a signal to probe further.

We are two boxes and an arrow away from surfacing the first gap.

And the gaps are always there.

In every technical discussion.

In every design session.

In every architecture review.

Invisible, until someone makes them visible.

So next time, dear Reader, when you are about to present something important to a colleague, pause before the closing "any questions?", and try this instead:

Then listen.

Not for agreement.

For their model.

Imagine that two developers - Daniel and Alice - are working on a new feature for their application.

It is related to sending e-mails, whenever an order was placed.

Sounds quite typical, right?

It does not need to be explained, as it's a common feature in many applications.

Of course, they are following 3S workflow (also known as TDD), so they use consumer-expected needs to drive the implementation.

Fortunately for them, an executable specification was there already:

[Fact]
public async Task given_an_order_when_placing_order_then_order_is_saved()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing = 
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    await _client.PlaceOrder("/orders", orderToPlace);

    await orders.Received(1).Save(Arg.Is<Order>(o => o.Id == "order-123"));
}

They needed to grow the system by introducing the new, required behavior.

But they didn't want to express all consumer requirements in a single test, so that from designer's perspective they could more easily locate the problems using very precise specifications:

[Fact]
public async Task given_an_order_when_placing_order_then_confirmation_email_is_sent()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing = 
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .WithCustomerEmail("a@b.com")
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    await _client.PlaceOrder("/orders", orderToPlace);

    var emailSender = _factory.Services.GetRequiredService<IEmailSender>();

    await emailSender.Received(1).Send("a@b.com", "Your order has been placed."); 
}

Daniel wasn't happy that compiler was buzzing, as red color is associated with something "bad".

However, Alice calmed him down by saying that they just expressed (or specified) needs, which now requires satisfying.

Orders interface was already there, so they could focus on implementing the missing, new behavior.

To make everything compiling, Daniel firstly created missing interface:

public interface IEmailSender
{
    Task Send(string recipient, string message);
}

Right after that, they went to the easiest implementation, that satisfies the requirements.

app.MapPost("/orders", async (
    PlaceOrderRequest request,
    Orders orders,
    IEmailSender emailSender
) =>
{
    var order = orders.Get(request.OrderId);
    order.Place();
    await orders.Save(order);
    await emailSender.Send(order.CustomerEmail, "Your order has been placed.");
    return Results.Ok();
});

record PlaceOrderRequest(string OrderId);

public interface Orders // ✅ it was already here, so no need to create it again
{
    Order Get(string id);
    Task Save(Order order);
}

They ran both tests and got green lights.

But Daniel wasn't happy - he heard that using mocks to verify if methods on objects were invoked is a bad practice.

He suggested going with WireMock and testcontainers in order to not worry about "internals", also known as "implementation details".

Alice asked him a bunch of questions in order to understand his mental model, when it comes to designing.

It quickly turned out that he associated "mocking" with "implementation details", because that is what major of the software engineering community is saying so.

She tried to unfold another way of thinking that was more oriented toward business capabilities - if there is a need for saving information about placed order, that is a hard requirement that cannot be omitted, rather than thinking in technical terms.

So ensuring that the e-mail was correctly sent and that the placed order was saved became a matter of fulfilling business needs, not just verifying technical interactions.

"Sometimes e-mail, sometimes SMS"

Change, change never changes.

It quickly turned out that this was a banger feature - finally customers were able to be informed right after their order was placed.

But not everyone wanted to use e-mails for achieving so.

Some customers wanted to receive notifications via SMS instead.

"Notifications", Alice said aloud, starting to realize their designing mistake.

Daniel didn't get it - "what mistake was she talking about?" - he wondered.

She went to the specs and understood that they did not discover true abstractions, but rather technical mechanisms for deliverying notifications.

"We need to refactor", she said to her fellow pair-designer.

"What? Oh come on, this feature is almost there, gimme the keyboard", Daniel protested.

Thankfully, he worked with Alice so he had the habit so start with a specification (or rather adjusting it):

[Fact]
public async Task given_preference_set_to_email_and_an_order_when_placing_order_then_confirmation_email_is_sent()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing =
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .WithCustomerEmail("a@b.com")
        .WithNotificationPreference(NotificationPreference.Email)
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    await _client.PlaceOrder("/orders", orderToPlace);

    var emailSender = _factory.Services.GetRequiredService<IEmailSender>();
    await emailSender.Received(1).Send("a@b.com", "Your order has been placed.");
}

This test failed when executed, so Daniel provided the implementation:

app.MapPost("/orders", async (
    PlaceOrderRequest request,
    Orders orders,
    IEmailSender emailSender
) =>
{
    var order = orders.Get(request.OrderId);
    order.Place();
    await orders.Save(order);

    if (order.NotificationPreference == NotificationPreference.Email)
        await emailSender.Send(order.CustomerEmail, "Your order has been placed.");

    return Results.Ok();
});

And poof, specs were green again.

"Now, time for another channel!", shouted Daniel.

[Fact]
public async Task given_preference_set_to_sms_and_an_order_when_placing_order_then_confirmation_sms_is_sent()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing =
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .WithCustomerPhone("+48123456789")
        .WithNotificationPreference(NotificationPreference.Sms)
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    await _client.PlaceOrder("/orders", orderToPlace);

    var smsSender = _factory.Services.GetRequiredService<ISmsSender>();
    await smsSender.Received(1).Send("+48123456789", "Your order has been placed.");
}

Satisfying new requirements happened just after that spec:

app.MapPost("/orders", async (
    PlaceOrderRequest request,
    Orders orders,
    IEmailSender emailSender,
    ISmsSender smsSender
) =>
{
    var order = orders.Get(request.OrderId);
    order.Place();
    await orders.Save(order);

    if (order.NotificationPreference == NotificationPreference.Email)
        await emailSender.Send(order.CustomerEmail, "Your order has been placed.");

    if (order.NotificationPreference == NotificationPreference.Sms)
        await smsSender.Send(order.CustomerPhone, "Your order has been placed.");

    return Results.Ok();
});

And tests were green again.

How good feeling is this, ain't it dear Reader?

But Alice remained silent throughout this entire 3S cycle.

"We need to simplify it, it was very easy to add this implementation, but any time we do something with notifications, we would need to touch application logic.", she concluded.

She also pointed out that number of dependencies increased, which is a strong signal that they are probably missing an abstraction.

Her pair-designing partner didn't get all of these - tests were green, implementation was easy - why worry about abstractions?

Alice asked for a permission to add an alternative implementation, just to see the options they had.

She asked herself aloud what are the current needs and it turned out they were discussing notification preferences.

That was their WHAT, and somehow they already framed themselves in using Order as the primary source of preferences.

But order placement capability never specified HOW it needs to be provided.

So she started refactoring by introducing missing concepts and structures:

[Fact]
public async Task given_preference_set_to_email_and_an_order_when_placing_order_then_confirmation_email_is_sent()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing =
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .WithCustomerEmail("a@b.com")
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    var notificationPreferenceProvider = 
        _factory
        .Services
        .GetRequiredService<IProvideNotificationPreference>(); // ❌ bzzzzzt, no such interface!
    
    notificationPreferenceProvider
        .For(orderAwaitingPlacing)
        .Returns(NotificationPreference.Email);
    var emailSender = _factory.Services.GetRequiredService<IEmailSender>();

    await _client.PlaceOrder("/orders", orderToPlace);

    await emailSender.Received(1).Send("a@b.com", "Your order has been placed.");
}

Then she created missing interface:

public interface IProvideNotificationPreference
{
    NotificationPreference For(Order order);
}

Followed by adjusting the implementation:

app.MapPost("/orders", async (
    PlaceOrderRequest request,
    Orders orders,
    IProvideNotificationPreference notificationPreferenceProvider,
    IEmailSender emailSender,
    ISmsSender smsSender
) =>
{
    var order = orders.Get(request.OrderId);
    order.Place();
    await orders.Save(order);

    var preference = notificationPreferenceProvider.For(order);

    if (preference == NotificationPreference.Email)
        await emailSender.Send(order.CustomerEmail, "Your order has been placed.");

    if (preference == NotificationPreference.Sms)
        await smsSender.Send(order.CustomerPhone, "Your order has been placed.");

    return Results.Ok();
});

She also refactored other specs, accommodating the change of introducing a new interface.

By specifying the interface and interaction in advance, by using NSubstitute (a tool for designing using mocking techniques), she designed the usage of that capability and the contract.

Daniel was upset - jira ticket did not say anything about providing notification preferences.

It was so natural to associate preferences with orders - and it required so little changes.

Alice challenged that perspective by asking what if preferences coming from order is true for today, but tomorrow there will be a dedicated web service providing those - what then?

"We will change implementation, simple.", Daniel replied.

But Alice was not finished, she started pulling more capabilities out of the existing implementation:

[Fact]
public async Task given_preference_set_to_email_and_an_order_when_placing_order_then_customer_is_notified()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing =
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    var notificationPreferenceProvider = 
        _factory
        .Services
        .GetRequiredService<IProvideNotificationPreference>();

    notificationPreferenceProvider
        .For(orderAwaitingPlacing)
        .Returns(NotificationPreference.Email);

    await _client.PlaceOrder("/orders", orderToPlace);

    var notification = _factory.Services.GetRequiredService<ISendNotification>(); // ❌ bzzzzzt, no such concept expressed using code!
    await notification.Received(1).Send(NotificationPreference.Email, orderAwaitingPlacing, "Your order has been placed.");
}

Daniel silently observed what the heck she is doing - "new interfaces?!" - he thought.

Alice added missing interface:

public interface ISendNotification
{
    Task Send(NotificationPreference preference, Order order, string message);
}

And adjusted other tests, so that they become green again.

But Daniel couldn't understand - why so many new interfaces?

Now they are not 100% sure if the entire system is working, because they are testing against fake implementations!

In his opinion, it will be easier to use the real implementations and test the system end-to-end, rather then testing implementation details.

Alice to finalize her approach, she showed how real implementations might look like:

public class OrderBasedNotificationPreference : IProvideNotificationPreference
{
    public NotificationPreference For(Order order) => order.NotificationPreference;
}

public class InProcessNotificationGateway : ISendNotification
{
    private readonly IEmailSender _emailSender;
    private readonly ISmsSender _smsSender;

    public InProcessNotificationGateway(IEmailSender emailSender, ISmsSender smsSender)
    {
        _emailSender = emailSender;
        _smsSender = smsSender;
    }

    public async Task Send(NotificationPreference preference, Order order, string message)
    {
        if (preference == NotificationPreference.Email)
            await _emailSender.Send(order.CustomerEmail, message);

        if (preference == NotificationPreference.Sms)
            await _smsSender.Send(order.CustomerPhone, message);
    }
}

"Maybe you were correct, after all? Placing an order does not care about the implementation details of notification sending", she concluded again.

Daniel nodded in agreement.

He knew that he was right all the time.

He awaited Alice's next refactoring, removing that artificially created interface.

So he observed in silence.

[Fact]
public async Task given_an_order_when_placing_order_then_customer_is_notified()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing =
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    await _client.PlaceOrder("/orders", orderToPlace);

    var notification = _factory.Services.GetRequiredService<ISendNotification>();
    await notification.Received(1).Send(orderAwaitingPlacing, "Your order has been placed.");
}

Alice smiled, because of the next specification:

[Fact]
public async Task given_email_preference_when_sending_notification_then_email_is_sent()
{
    var order = 
        Order
        .AnyAwaitingPlacing()
        .WithCustomerEmail("a@b.com")
        .Build();

    var preferenceProvider = Substitute.For<IProvideNotificationPreference>();
    var emailSender = Substitute.For<IEmailSender>();
    var gateway = new InProcessNotificationGateway(preferenceProvider, emailSender, Substitute.For<ISmsSender>());

    preferenceProvider
        .For(order)
        .Returns(NotificationPreference.Email);

    await gateway.Send(order, "Your order has been placed.");

    await emailSender.Received(1).Send("a@b.com", "Your order has been placed.");
}

She ensured that all scenarios were covered, making all tests green too.

But there was one thing that was really off - "why notification gateway does need to know anything about orders?", Alice wondered.

She thought of introducing another concept - a NotificationContent - but decided to leave it, for now.

They had a very vivid discussion about the whole development process - Alice tried to understand the standpoint of her pair-designer, highlighting the bright sides of using WireMock/testcontainers for the whole test suite.

Although, she disagreed with making specs much bigger, including many assertions.

Having the possibility to localize problems through well-defined expectations about interactions, using well-defined contracts, was a must-have in her world.

And then new requirements arrived.

"Notify about fact"

This time it was Jerry, the architect, who came with a requirement: there are other parties interested in a fact of placing an order.

The idea was simple: emit an event, stating that order was placed, and let others deal with that information.

"Of course, one of the consequences will be notifying customers about that fact using e-mail or SMS." Daniel assumed.

"Finally, we won't deal with e-mails", he assumed again.

"Actually, it's a bit opposite. I want to have two ways at the same time - I don't know what is the customer experience if we notify them eventually", said the architect.

Daniel couldn't believe - how the hell it makes any difference? For the end user it's a freaking notification, being delivered, but eventually, because there will be another service doing so.

"But it will happen, for sure", he said aloud.

Alice was more curious and asked about what is the decision point, when it comes to sending e-mail immediately rather than eventually.

"Together with product owner, we believe that some customers treat notifications very seriously and they want to get that information as soon as possible", replied Jerry.

"So we need to send e-mails either immediately or eventually, and always emit events, right?" Alice asked.

"Yes, but please remember that Notification service is serving multiple consumers and it can't accept specific information, like Daniel suggested, by using events", Jerry observed.

"And please remember we're experimenting to see what will be the customer response, when it comes those deferred notifications", he continued.

They know everything that was required to fullfil those requirements.

Daniel was so eager earlier to go fully with Event-Driven Architecture, but now he needs to await.

So Alice started thinking how to satisfy those requirements.

She wanted to express new concept - selecting Notification gateway - following that abstract idea in tests.

[Fact]
public async Task given_an_order_when_placing_order_then_customer_is_notified()
{
    var orderToPlace = new { OrderId = "order-123" };

    var orders = _factory.Services.GetRequiredService<Orders>();
    var orderAwaitingPlacing =
        Order
        .AnyAwaitingPlacing(withId: orderToPlace.OrderId)
        .WithCustomerId(customerId: "customer-ABC")
        .Build();

    orders
        .Get(orderToPlace.OrderId)
        .Returns(orderAwaitingPlacing);

    var notification = Substitute.For<ISendNotification>();
    var gatewaySelector = 
        _factory
        .Services
        .GetRequiredService<ISelectNotificationGateway>(); // ❌ bzzzzt, no abstract idea expressed in the code yet!

    gatewaySelector
        .SelectFor("customer-ABC")
        .Returns(Task.FromResult(notification));

    await _client.PlaceOrder("/orders", orderToPlace);

    await notification.Received(1).Send(orderAwaitingPlacing, "Your order has been placed.");
}

To calm down the compiler, new interface was immediately added:

public interface ISelectNotificationGateway
{
    Task<ISendNotification> SelectFor(string customerId);
}

Daniel was shocked - mock returning mock?

"This is such an anti-pattern", he commented aloud.

Alice just mentioned that she used it to design interactions and contracts.

"Internal ones, right?", he continued.

"Well, yes, capabilities required by order placement, according to our new understanding", she replied.

Alice satisfied specification with the following implementation:

app.MapPost("/orders", async (
    PlaceOrderRequest request,
    Orders orders,
    ISelectNotificationGateway gatewaySelection,
    IPublishEvent publisher
) =>
{
    var order = orders.Get(request.OrderId);
    order.Place();
    await orders.Save(order);

    await publisher.Publish(new OrderPlaced(order.Id));

    var gateway = await gatewaySelection.SelectFor(order.CustomerId);
    await gateway.Send(order, "Your order has been placed.");

    return Results.Ok();
});

This sparked a new conversation, related to ratio of customers that should use deferred notifications. It turned out that it should be no more than 5% of customers.

According to the established understanding, the follwing implementation happened:

public class ExperimentalRandomizedNotificationGatewaySelection(
    InProcessNotificationGateway immediateNotificationGateway,
    NotificationWebGatewayHttpClient eventualNotificationGateway
) : ISelectNotificationGateway
{
    public Task<ISendNotification> SelectFor(string customerId)
    {
        ISendNotification gateway = Random.Shared.NextDouble() < 0.05
            ? eventualNotificationGateway
            : immediateNotificationGateway;

        return Task.FromResult(gateway);
    }
}

They shipped it, awaited some time period and observed the results.

It turned out that some customers were happy to pay a little more in order to get notification in a guaranteed time.

Daniel was surprised by the unexpected outcome.

He couldn't believe that customers were willing to pay more for notifications.

Alice explained that it was not about notifications, but about purchasing priority.

It might have sounded as it was a mere detail, but that framing was crucial for understanding customer behavior.

And stop "just coding" and start thinking in terms of producing value, as customers would have never think of that themselves.

As this feature was proven to be valuable, they decided to provide it only for subscribed customers, which drove the implementation toward the following capability:

public class SubscriptionBasedNotificationGatewaySelection(
    ICheckCustomerSubscription subscriptions,
    InProcessNotificationGateway immediateNotificationGateway,
    NotificationWebGatewayHttpClient eventualNotificationGateway) : ISelectNotificationGateway
{
    public async Task<ISendNotification> SelectFor(string customerId) =>
        await subscriptions.HasSubscribedToNotificationPriority(customerId)
            ? immediateNotificationGateway
            : eventualNotificationGateway;
}

Fortunately, there was company-wide subscriptions web service that provided such capabilities, so it was very easy to integrate.

And thankfully, the structure, that emerged through gaining understanding, was ready for accommodating incoming changes.

Implementation details?

"Come on, mocking in 2026 with AI?!", some might think right now.

Well, yes.

It is not mocking that is "bad" on its own, it's the operator that truly makes the difference.

As we discussed some time ago - everything boils down to composing a PIE.

Based on Purpose (driven by needs) we design Interactions between Elements.

We saw two developers building understanding of what needs to be delivered and then they designed proper communication structure between elements.

Alice mindfully organized this communication letting certain abstractions to emerge.

Not NotificationService or NotificationManager, but symbols and ideas that were appearing in human language, as they spoke and listened to each other.

NotificationContent, NotificationPreference, NotificationGateway and so on.

These abstractions allowed them to reason about the system at a higher level, focusing on the value delivered to the customer rather than the mechanics of implementation.

Considering they properly abstracted away details.

But really, what are implementation details?

Often time one might heard that mocks are "bad" because they make the tests brittle and tightly coupled to the implementation.

Same as the claim that mocks are breaking encapsulation - what is really encapsulation? (you might be interested in a great article by Grzegorz Gałęzowski about alleged encapsulation breaking and why we might incorrectly think about it)

As yet again we get trapped in thinking in static labels, names - "mocks".

What if mocking is actually a design tool?

So it is a process of designing. Designing what?

Interactions.

How certain concepts interact with each other.

What are relationships between abstractions, but not in a static, "data" sense, but when those abstractions are in motion, when they "act".

To understand how they collaborate behaviorally.

Or rather, how do we want them to collaborate with each other.

It might be that those "implementation details" are actually interaction requirements we specify (as designers) so that certain abstractions can provide them.

Abstractions we introduce so that we can raise the level of being specific.

Abstractions that aim at creating a specific boundary that expresses certain language.

Often times those "implementation details" might create an effect that some call "brittle tests from over-mocking" - but if actually those "brittle tests" are diagnostic signal trying to highlight poor abstraction discipline?

Expressing roles and their interactions that might be actually quite stable, if we model them at certain level.

It might quickly turned out that interfaces do not represent the correct behavioral boundaries, but are rather a reflection of our current understanding.

Or rather - misunderstanding.

And shallow analysis of the problem area.

Poor abstraction discipline is frequently a symptom of implementation-first thinking, leaking details that should have been hidden inside a particular boundary.

And it is our job to understand the problem, language that lives inside of that area, decompose the purpose into a set of collaborating roles, named after what they do, not what they are or how they do it.

Translating that purpose into interactions of elements, provided that we build proper structure around our understanding, will bring stable abstractions, without the dreaded details.

Maybe those details are poorly designed abstractions, dear Reader?

"Consumer observable behavior" you fool!

What about notifying customers using some kind of preferred delivery mechanism?

Does it really matter how those notifications are delivered?

Isn't it "the implementation detail"?

Well, some might say yes, some might say no.

Then, why "no"?

Behavior is exactly the same, isn't it?

Well, what if an external Notification web service has a priority queue and some customers might be notified later than others?

Behavior might be exactly the same, but experience will significantly vary.

That is why quality attributes are truly important - they add more dimensions to the provided solution.

Those quality attributes emerge from the interactions between abstractions, that form boundaries, hiding certain details, from consumers' sight.

Features is the easy part.

Expressing important abstractions and how they interact - "the structure" - this is often the hard part.

It might turn out quickly that the notification delivery mechanism might actually matter - as it changes the reception of our provided capabilities.

One might conclude that there is a crucial nuance that the consumer is relative to the boundary you're looking at - that's why Outside-In Designing is so powerful, because one is traversing various boundaries and then designing accordingly.

"Implementation detail" is not an absolute property of a piece of code. It is a relational concept — defined by who is observing and from which boundary (or from what level).

And if mocking (a workflow/a process) is a designing technique that might teach us about interactions and boundaries - how does it contribute to thinking on other levels, outside of a single boundary?

EDA - Eventing Dopamine Addiction

Let's try to visualize the simple workflow using Event Storming notation.

Orange stickies are events, blue stickies are commands and yellow stickies are rules.

Exploring the problem

To better understand the needs, we could follow up with a question - "what is a consequence of placing an order?"

And some might of course come up with a notification - e-mail one.

Important information revealed

And as Daniel immediately saw - event here, event there, so placing order abstraction interacts with notifications in a very particular way - notifications consume events to trigger their behavior.

But is it the only way boundaries can interact?

It might be that designed interaction is not the correct one and might be quite costly if we continue down this path.

Another way of organizing interactions between boundaries - green stickies are information, pink stickies are external systems

That is what Jerry tried to communicate - some abstractions are much more stable than others and interactions should be designed accordingly.

If one organizes interactions incorrectly then details from one boundary might leak into another, causing unintended consequences and increasing complexity, operational costs and simply frustration.

Notifications are pretty stable concept (abstraction), whereas Orders might change more frequently - sometimes because of the business side, other times because of regulation.

Also, notice the language change - notifications are not using language of orders.

Inside their boundary there is nothing like "order" - there are recipients, notification contents, notification preferences, maybe notification priority?

As with "brittle tests from over-mocking" (which is a misnomer), coupling to details might be a wrong way of organizing interactions between elements - that are simply abstractions, but sometimes expressed on various levels.

Subsystems (Notifications) or small objects (Notifications).

Essentially, poorly designed abstractions (which means - behavioral models) is what we typically might be dealing with, but "coupling to implementation details" is a consequence of that.

Focus on finding proper abstractions rather than fixating on implementation details.

They are truly a detail (pun intended) when it comes to a process of organizing interactions between boundaries.

Mocking? DDD? Abstractions?

In Domain-Driven Design we say and think a lot about models expressing contextual behaviors - which can be translated into abstractions interacting with each other.

Relating to each other, in certain moments of time, in specific way.

If one uses brittle tests and challenging integrations between bounded contexts as diagnostic signals, we might eventually learn and improve ways how elements interact with each other.

Elements having different meaning, depending on the level we are currently reasoning at.

Which might lead to finding proper models or abstractions, or boundaries, or whatever.

It was always about the same thing, although the names might be changed.

Every brittle test is a friend in disguise - use it to guide you towards better abstractions and interactions.

Every challenging integration is an opportunity to refine boundaries, improve the language and communication structure.

Next time dear Reader when your tests are failing or you need to participate in yet another meeting about integration between services, ask yourself

Imagine that three people - Alice, the Architect, Peter, the Providing Developer, and Chris, the Consuming Developer - are discussing a new feature for their software application.

Chris, the Consuming Developer wants a new capability to be provided so that his team can complete their work.

Both the architect and the providing developer represent the another side of the relationship, trying to understand the needs.

As they were doing circles without any outcomes, someone got an idea to start visualizing various options.

They went with Event Storming notation and conjured a quick process level diagram.

Process level Event Storming for a tiny worker assignment process

Neither of them liked the solution of another, because it either put too much responsibilities on one side or made the system harder to maintain.

They tried to find consensus, but it was tough to be achieved, knowing the constraints they had.

Being caught in "analysis paralysis" isn't the best state, Alice, the Architect noticed that and decided to write an ADR in which they specify all options.

Then the architect decided to go with the option putting the responsibility for identifiers exchange on the Chris, the Consuming Developer side.

Of course, it didn't make him happy, but at least they moved on, remembering that "Bad decision isn't bad, if you know it's bad".

"At least it's easy"

As it was decided, Chris, the Consuming Developer is going to handle the exchange of identifiers.

In fact, he is providing yet another capability - assigning workers to jobs - which is consumed by the web application.

So Chris, the Consuming Developer also plays the role of a provider.

Chris, the Consuming Developer wanted to have easy interface provided by Peter's service, but it turned out that it wasn't that easy (pun intended) to convince people.

So then he started specifying the capability that his service is going to provide, knowing that along with consuming equipment ordering capability, it also needs consume identifiers exchanging.

[Fact]
public async Task given_existing_job_when_successfully_assigning_worker_by_id_then_confirms_successful_assignment()
{
    var jobId = "job-123";
    var workerId = "b692976a-b25c-450c-a5e1-c190cd5c09c4";

    var response = await _client.PutAsync($"/jobs/{jobId}/assign/{workerId}", null);

    response.StatusCode.Should().Be(HttpStatusCode.OK);
}

The test failed ❌ because there was no implementation.

This is what a consumer of his service would do to assign a worker to a job, and what expects to get back as confirmation.

Implementation is also straightforward:

app.MapPut("/jobs/{jobId}/assign/{workerIdOrWorkerReference}", // 👈 new!
    (string jobId, string workerIdOrWorkerReference) =>
    {
        return Results.Ok();
    }
);

And this made the test passed ✅.

Chris, the Consuming Developer then specifies the next consequence of successful assignment - saving the assignment.

[Fact]
public async Task given_existing_job_when_successfully_assigning_worker_by_id_then_assignment_is_saved()
{
    var jobId = "job-123";
    var workerId = "b692976a-b25c-450c-a5e1-c190cd5c09c4";

    await _client.PutAsync($"/jobs/{jobId}/assign/{workerId}", null);

    var assignments = 
        _factory.Services.GetRequiredService<IGetAssignmentById>(); // 👈 in runtime this resolves to `PostgresAssignmentRepository`
    var assignment = await assignments.GetById(jobId);

    assignment.Should().NotBeNull();
    assignment!.WorkerId.Should().Be(workerId);
}

The test failed ❌ because there was no saving yet.

Thankfully, the solution already uses testcontainers so it is super easy to run these tests in an isolated environment.

No mocking required, so less amount of code is needed to actually verify the real saving to database.

The downside is that this simple test requires additional time to start the Postgres container.

Then, Chris, the Consuming Developer implements the remaining logic:

app.MapPut("/jobs/{jobId}/assign/{workerIdOrWorkerReference}", 
async (
    string jobId,
    string workerIdOrWorkerReference,
    ISaveAssignment assignments // 👈 new!
) =>
{
    await assignments.Save(new Assignment(jobId, workerIdOrWorkerReference)); // 👈 new!

    return Results.Ok();
});

And now, both tests passed ✅.

Chris isn't an advocate for such narrow interfaces, they seem too fine-grained, too unit-esque.

It isn't something that he decided on - if we could, he would name it as IAssignmentsRepository, at least the pattern is well-known in the industry.

But he asked himself - "are there any benefits of using such narrow interfaces?", but a message on Teams broke this insightful moment.

The consumer of the capability provided by Chris's service can now confidently assign workers to jobs and have those assignments saved correctly, along with expected confirmation response.

But even those tests are small, working on real database interactions provides a delayed feedback, as tests startup takes longer.

"At least it's easy to write those tests, as I don't need unnecessary mocking.", thought Chris, the Consuming Developer.

"Let's not complicate it"

Chris, the Consuming Developer to progress with provided capability, it's time to order equipment using Peter, the Providing Developer.

"The easiest would be to verify ordering on the HTTP level", told Chris, the Consuming Developer himself.

So he did it:

[Fact]
public async Task given_existing_job_when_successfully_assigning_worker_by_id_then_equipment_is_ordered()
{
    var jobId = "job-123";
    var workerId = "b692976a-b25c-450c-a5e1-c190cd5c09c4";

    _wiremock
        .Given(Request.Create()
            .WithPath("/equipment-orders")
            .UsingPost())
        .RespondWith(Response.Create()
            .WithStatusCode(HttpStatusCode.OK));

    await _client.PutAsync($"/jobs/{jobId}/assign/{workerId}", null);

    _wiremock.Should().HaveReceived(1).Calls()
        .WithPath("/equipment-orders")
        .UsingPost()
        .WithBodyAsJson(b => b.WorkerId == workerId);
}

The test failed ❌ because there was no implementation of equipment ordering.

Observing unsatisfied behavior, the developer stated implementing it:

app.MapPut("/jobs/{jobId}/assign/{workerIdOrWorkerReference}", async (
    string jobId,
    string workerIdOrWorkerReference,
    ISaveAssignment assignments,
    HttpClient equipmentOrderingClient // 👈 new!
) =>
{
    await assignments.Save(new Assignment(jobId, workerIdOrWorkerReference));

    await equipmentOrderingClient.PostAsJsonAsync("/equipment-orders", new // 👈 new!
    {
        WorkerId = workerIdOrWorkerReference
    });

    return Results.Ok();
});

And this made all tests pass ✅.

He observed even longer time needed to get feedback.

Here came the final boss - exchanging worker identifiers. Thankfully, Alice, the Architect provided the necessary contract for doing the exchange.

It was a simple HTTP GET interaction to https://api.workers.bigcorp.io/workers/{workerIdOrWorkerReference}, which gave entire worker object back.

Specifying this behavior for scenario with worker reference was easy, as WireMock.NET was already used:

[Fact]
public async Task given_existing_job_when_assigning_worker_by_reference_then_worker_should_be_assigned_to_job()
{
    var jobId = "job-123";
    var workerReference = "EMP-ABC";
    var resolvedWorkerId = "b692976a-b25c-450c-a5e1-c190cd5c09c4";

    _wiremock
        .Given(Request.Create()
            .WithPath($"/workers/{workerReference}")
            .UsingGet())
        .RespondWith(Response.Create()
            .WithStatusCode(HttpStatusCode.OK)
            .WithBodyAsJson(new { Id = resolvedWorkerId, Reference = workerReference }));

    _wiremock
        .Given(Request.Create()
            .WithPath("/equipment-orders")
            .UsingPost())
        .RespondWith(Response.Create()
            .WithStatusCode(HttpStatusCode.OK));

    var response = await _client.PutAsync($"/jobs/{jobId}/assign/{workerReference}", null);

    response.StatusCode.Should().Be(HttpStatusCode.OK);
    _wiremock.Should().HaveReceived(1).Calls()
        .WithPath("/equipment-orders")
        .UsingPost()
        .WithBodyAsJson(b => b.WorkerId == resolvedWorkerId);
}

The test failed ❌ because there was no exchange logic provided.

So Chris, the Consuming Developer started satisfying it.

app.MapPut("/jobs/{jobId}/assign/{workerIdOrWorkerReference}", async (
    string jobId,
    string workerIdOrWorkerReference,
    ISaveAssignment assignments,
    HttpClient equipmentOrderingClient,
    HttpClient workersClient // 👈 new!
) =>
{
    var workerId = workerIdOrWorkerReference;

    // worker ids are GUIDs
    if (!Guid.TryParse(workerIdOrWorkerReference, out _))
    {
        var worker = await workersClient
            .GetFromJsonAsync<WorkerResponse>($"/workers/{workerIdOrWorkerReference}");

        workerId = worker!.Id;
    }

    await assignments.Save(new Assignment(jobId, workerId));

    await equipmentOrderingClient.PostAsJsonAsync("/equipment-orders", new // 👈 new!
    {
        WorkerId = workerId
    });

    return Results.Ok();
});

And this made all tests pass ✅ again.

Chris, the Consuming Developer was pretty proud, as it didn't take much time and was pretty easy to implement.

He didn't even need to add too many new classes, and what is pretty important - he avoided mocking, and he heard that mocking leads to testing implementIt meant to be easyation details, which then leads to brittle tests.

For a while he thought of introducing mocks, at least for a small boundary between HTTP handler and HTTP clients, but then said to himself - "let's not complicate it".

Then, he started working on error scenarios.

What does it mean "easy"?

"Isn't a joke? TDD in the LLM world?", one might ask.

Bear with me, dear Reader.

We saw three roles collaborating to satisfy the needs.

The needs - of whom?

In the first part of the tale, we observed vivid discussion of three parties - each having their own understanding of "easy".

The consumer wanted to have easy way of using the capability exposed through HTTP interface, by not needing to care about identifiers.

The architect wanted to have easy way of maintaining and evolving the system, by clear boundaries and responsibilities.

The provider wanted to have easy way of providing the capability, by delegating identifiers exchange to another service and just doing the HTTP interaction.

It is not difficult to see that in their eyes, the quality attribute "easiness" meant three different things, because the roles were physically separated.

But what about the second part of the tale?

Wasn't it really different from the discussion between three people?

It might actually turn out to be a good example of the invisible role-switching problem.

A single person, Chris, unconsciously and dynamically swapped the perspective, multiple times.

One time he played the role of a consumer for "his" provided capability, next time he thought from the providers perspective.

When he started doubting whether more time needed to get feedback is worth it, provided that the system will grow in complexity - then we could say that Chris looked at "things" from a system's designer perspective, taking into account quality attributes, like maintainability or testability.

As those role switching was done mostly in his head, it remained invisible to others.

Even to himself, especially when "being in the process".

Each role having its own perspective

Roles (consumer, provider, designer) does not disappear, they are assigned or relocated differently.

A consumer looks from outside perspective.

A provider looks from inside perspective.

A designer looks from a system-level perspective - observing both outside and inside parts.

Sometimes to different people, sometimes to the same person at different moments.

Also, the tension between various needs remains similar, especially when one tries to take each and every perspective into account.

And we might arrive at the conclusion - "there is no single easy".

What does it mean "easy"?

Shocking mocking?

When dealing with implementation work, Chris used consumer-driven approach for driving the implementation of capability that was expected to be provided by the service he owned.

He was able to specify the contracts (interfaces, along with required and provided information), from the HTTP interface consumer perspective.

Additionally to that, he went with "the easiest implementation" possible (at least in his mind) - designing against HTTP boundary and against real database.

I know, I know - it is a bit exaggerated to distinguish between a provider and a designer perspectives, mainly because while implementing, one is also designing, on some level.

But the designer might have more system-level approach for solving problems - was WireMock a right choice, from maintainability perspective?

What about test containers, and testing a typical state-changing process?

If you recall, Chris for a while switched to "a designer" perspective, asking about mocking.

How would mocking change the system's behavior and maintainability?

Anti-mocking movement would tell you it's straightforward - mocks break encapsulation.

Let's stop for a while - what does "mocking" mean? Are we sure we have the same "thing" in our heads?

Ok, back to the main topic.

It might be arguable to even introduce "designer's perspective", but imagine a "jira ticket jockey" who just want to close the ticket, without caring about the system - even if they are implementing, are they really designing consciously?

And what about "easy" - what does it really mean in this context?

Effortless now, effortful later?

I hope you know dear Reader that I like definitions, because they contribute to building understanding and clarity, so here we go:

In Simple ain't easy, we tried to deepen our understanding when it comes those two terms.

Building something without adding more code might seem simple, but will it be after, let's say, one year?

Or maybe it is just "easy", meaning - requiring little effort? If it is, who's stating that - a consumer? A provider? A designer?

The situational awareness might be really helpful when it comes to understanding the context and perspective from which "easy" is being evaluated.

As we saw in 3S, specifications through tests might be useful mental tool for "putting on" consumer's glasses.

Which does not mean we magically will not get our hands (or heads?) dirty by looking inside, when it comes to designing internal quality.

Boundaries are not only valuable, but necessary to control complexity - technical, cognitive and organizational.

Establishing them doesn't only happen at one level - boundaries are fractal in their nature, so pick a level and you will find them there too.