Lesson 0001 · Core Designer · Module 1

Seeing Coupling & Cohesion

Before you can fix structure, you have to see it. This lesson trains your eye to measure the two forces every structure is made of.

Reading ≈ 11 minPractice ≈ 20 min

Mission tie-in: code that "works" but isn't maintainable is usually failing on exactly these two forces. Every later lesson — patterns, ports, domain protection — is a tool for steering them.

Knowledge: the two forces

Coupling measures how much one module depends on another. Low coupling means a module can change, be tested, or be replaced without its neighbors noticing. Cohesion measures how strongly the elements inside a module belong together — whether it has one purpose.

Look at this function. It works. It also does three different jobs:

def process_order(order_id: str, db: Database) -> None:
    order = db.fetch_order(order_id)
    total = 0.0
    for line in order["lines"]:
        total += line["price"] * line["qty"]
    order["total"] = round(total, 2)
    db.save_order(order)
    EmailClient().send_receipt(order_id, order["total"])
    logger.info("Order %s processed", order_id)

Ask two questions. Cohesion: how many jobs is this one function doing? It computes a business total, persists it, sends email, and logs — four. Coupling: what does the order flow depend on? It is now fused to the email client and the logging framework; change either and order processing breaks.

Notice what you didn't need: a diagram, a framework, or a tool. You saw the problem by asking how many reasons does this have to change, and who is it joined to. That is the skill of this module: not applying rules, but seeing.

How a senior designer reads that function

Watch the order of operations, because it is not "read the code and dislike it".

They look at the history before the code. git log --oneline -- orders.py over six months returns eighteen commits: "add VAT for IE", "new receipt template", "switch to structured logging", "retry failed sends", "fix rounding on discounts". Five different parts of the world edit one file. That list is the cohesion measurement; the function body only confirms what the history already said.

Then they ask one question: if the mail vendor changes next month, what has to be re-tested? The honest answer is order pricing — because the send is inline, the pricing path and the send path share a failure surface. That sentence is what the coupling costs, stated in a form a product manager can act on.

Then they reject the obvious refactor. The tempting move is to lift the last two lines into a notification class that takes the order dictionary:

class NotificationService:
    def send_receipt(self, order: dict) -> None:
        EmailClient().send_receipt(order["id"], order["total"])
        logger.info("Order %s processed", order["id"])

This looks like progress and is not. process_order still builds the dependency at call time, still fails when SMTP fails, and the new class now depends on the order dictionary's key names as well — a second module that breaks when total is renamed. The edit moved code across a file boundary without turning a single arrow. The tell for this mistake: after the refactor, is the list of things you must re-test any shorter? Here it is not, so nothing was decoupled; something was relocated.

The move that works changes who depends on whom. Order processing computes and saves, then returns a result; something outside it decides whether a receipt is sent. The receipt becomes a consequence of a completed order rather than a step inside one, and the order flow stops importing anything about mail at all.

The consequence over a year. In the coupled version, a marketing tweak to a receipt template ships through the order-processing test suite and the order-processing deploy. That is the version where, on the busiest trading day of the year, a template that raises on a missing field takes checkout down with it — the classic incident shape, in which the blast radius is set by structure rather than by the size of the change. In the decoupled version the same edit touches one module, and a failing receipt leaves an order that is still saved and still correct.

Cohesion and coupling trade against each other across a boundary: to lower coupling between two modules you often raise the cohesion of each — you pull each job into its own module and leave each module with one job.

When this is the wrong move

Do not split a function merely because it does more than one thing. Leave it alone when the code is a spike or a migration script whose lifetime is shorter than the next change to it; when the two jobs have always changed together and there is no plausible world in which one changes alone; or when the split would replace one readable function with three modules plus an orchestration layer you now have to hold in your head at once. Structure is bought with reading cost, and a boundary nothing ever crosses is a boundary you paid for and never used. The question to answer honestly is not "does this have one job?" but "will anything ever want to change one of these jobs without the other?"

Skill: point at the problem

Read each snippet below and name the force that is failing. Answer before checking — the act of deciding is the practice.

Practice on your own code

Take the messiest function in a file you own. Write down (in your head or a note): its jobs, and every neighbor it touches. If the list has more than one job or more than two neighbors, you have found this lesson's win. Then run the history check — git log --oneline -- <that file> — and see whether the commit subjects name more than one part of the world.

In the lab: the companion returns-resolution service carries this lesson's problem at working scale. Its phase-1 checkpoint asks you to find the coupling hot-spots in the resolution flow — the places where one edit forces several — and cut exactly one, then show that the list of modules a notification change touches actually got shorter.

class Order:
    def __init__(self, order_id: str, lines: list[Line]) -> None:
        self.order_id = order_id
        self.lines = lines

    def total(self, pricing: Pricing) -> Money:
        return pricing.total(self.lines)   # domain knows money, not email


# one job: order flow
def process_order(order_id: str, orders: OrderRepository, pricing: Pricing) -> Money:
    order = orders.get(order_id)
    return order.total(pricing)            # persistence, email, logging live elsewhere

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 4 "Modules Should Be Deep": why module shape, not size, determines whether code survives.
• Code Complete, McConnell — ch. 5 "Design in Construction": the deepest treatment of cohesion levels and coupling types.
• David Parnas, "On the Criteria To Be Used in Decomposing Systems into Modules" (Communications of the ACM, 1972) — the primary source. Its argument is not "split by processing step" but "split by the decision each module hides", which is where the change-propagation reasoning above comes from.
• Watch: search "coupling" and "cohesion" on ArjanCodes YouTube — the channel's videos on these are the primary source for this lesson.
• Reference: Design Principles — and the glossary on coupling, cohesion, and change amplification.

Anything unclear? Ask your agent-teacher — re-explain any part of this lesson, or bring your own code and have it pointed at together.

Source page: lessons/0001-seeing-coupling-and-cohesion.html

Lesson 0002 · Core Designer · Module 1

SRP, DRY, KISS, YAGNI in Context

These four are quoted as rules and violated as rules. The skill is reading them as forces: each names a failure mode, and each can be wrong.

Reading ≈ 10 minPractice ≈ 20 min

Mission tie-in: AI will happily generate code that "follows the rules" while violating the point. Understanding the forces is what lets you keep control of AI output instead of accepting its letter.

Knowledge: forces, not rules

SRP — one reason to change

The unit is the reason to change, not the method. "We must edit this class because tax rules changed" and "…because we switched databases" — two reasons in one class is the failure. A class with twenty methods but one change source is fine; a class with two methods and two change sources is not.

DRY — once and only once, per unit of knowledge

DRY targets knowledge, not text. These two functions are identical today — and encode different knowledge:

def fee_for_bank_transfer(amount: Money) -> Money:
    return amount * Decimal("0.01")   # bank fee, set by our bank

def fee_for_wire_transfer(amount: Money) -> Money:
    return amount * Decimal("0.01")   # wire fee, set by the clearing house

Both compute 1% today. Merge them into one fee(amount) and the next time one fee changes, you will silently charge the other's customers the wrong amount. That is false DRY — deduplication that creates coupling between things that will diverge. The two fees changing together twice is what earns the merge (the rule of three).

KISS and YAGNI — the cost of complexity

KISS: prefer the least complex solution that meets the requirement. YAGNI: do not build capability with no evidence of need. Both are about unpaid tax: every generality, hook, and abstraction layer is paid for on every future read of the code, whether it's used or not.

The context is the whole story: a hook is YAGNI in a two-month project and common sense in a platform other teams will build on. The same line of code can be a violation and a virtue in two codebases.

How a senior designer decides the fee question

Return to the two 1% fees. Here is the reasoning, not the verdict.

First they look for the owner, not the code. Who decides each number? One is set in the bank's commercial agreement; the other is published by the clearing house. Two documents, two counterparties, two renewal dates. That answer arrives before anyone opens the function bodies, and it is already most of the decision.

Then the question: when one of these changes, does the other change in the same commit? Not "could they" — has it happened? Check the history of the constants. If the two numbers have moved independently even once, they are two facts and the merge is a bug waiting for a date.

Then they reject the compromise. The tempting middle path is to keep one function and pass a discriminator:

def fee(amount: Money, kind: str) -> Money:
    rate = Decimal("0.01") if kind == "bank" else Decimal("0.01")
    return amount * rate

This is worse than either honest option. It is control coupling: the caller now passes a flag whose only job is to select which of two policies runs, so every caller must know the taxonomy, and the function's signature promises one behaviour while delivering two. It also creates the illusion of having deduplicated — the rate literal is written twice anyway. A senior designer's tell: if the parameter exists only to choose between branches, you have not shared knowledge, you have shared a switchboard.

The consequence over eighteen months. On a four-team payments platform, the wire fee went tiered — 1% up to €10,000, then 0.6%. In the merged version, that change edits the function both teams depend on; the bank team's regression suite starts failing for reasons that have nothing to do with their product, and the review needs someone from each team, so a two-line change waits three days for a quorum. In the kept-apart version it is one file, one reviewer, one afternoon. The duplication that looked like sloppiness was the thing that let two teams move at different speeds.

When this is the wrong move

• Do not wait for the rule of three when the duplicated thing is a security or correctness check. Three copies of an authorisation test means two of them will drift, and the failure mode is not a wrong number, it is an open door. Centralise on the first copy.
• Do not apply YAGNI to stored data or published contracts. A version field on an event, a nullable column reserved for a known-coming attribute, an extra map on a public payload — these are cheap now and cost a migration later. The principle is about capability, and its strength scales with reversibility.
• Do not split for SRP in an unfamiliar domain. You cannot name change sources you have never seen. Keep it in one module, watch the edits for a quarter, and split when the history tells you where the line is.
• Do not read KISS as "fewer abstractions". The simplest thing for the reader is sometimes one more named concept, not one fewer. A clear twenty-line function with two well-named helpers beats a clever five-liner that needs a paragraph of explanation.

Skill: judge the application, not the principle

Practice on your own code

Find one place where a principle was applied as a rule — a shared helper that two things were forced into, a class split "to follow SRP", a generality built "just in case". Name the force it ignored, and then name the reversibility: if this call was wrong, what would undoing it cost in hours and in coordination?

In the lab: the returns-resolution service contains at least one shared helper that two policies were pressed into. The phase-1 checkpoint asks you to decide whether it is true DRY or false DRY using the ownership test — who sets each number, and have they ever moved independently — and to write the one-line justification for whichever way you call it.

Read and watch deeper

• Clean Architecture, Martin — ch. 7 "SRP: The Single Responsibility Principle": the reason-to-change definition.
• The Pragmatic Programmer, Hunt & Thomas — "DRY: The Evils of Duplication", where DRY is defined over knowledge rather than text.
• Refactoring, Fowler — ch. 2, where the Rule of Three is stated ("three strikes and you refactor"). It belongs to Fowler, not to DRY, and the distinction matters: DRY says what to unify, the rule of three says when.
• "Yagni", Martin Fowler — the clearest primary statement of the cost model: presumptive features cost build, carry, repair, and delay.
• A Philosophy of Software Design, Ousterhout — ch. 11 "Design It Twice" and the discussion of complexity in ch. 2: KISS made concrete.
• Watch: ArjanCodes YouTube — search "7 principles of software design" for the source framing of these four.
• Reference: Design Principles — all nineteen, each with the way it fails when followed as a rule; and the glossary on false DRY and the rule of three.

Stuck on a judgment call? Ask your agent-teacher: paste the code and the claimed principle, and it will help you name the force actually at stake.

Source page: lessons/0002-principles-in-context.html

Lesson 0003 · Core Designer · Module 1

The Law of Demeter

A method should only talk to its immediate neighbors. When code walks through strangers, it learns their geography — and every geography change breaks it.

Reading ≈ 10 minPractice ≈ 20 min

Mission tie-in: chain-walking is one of the most common structural defects in AI-generated code. Master the tell, and you can spot it in any output in seconds.

Knowledge: no talking to strangers

The Law of Demeter limits a method's acquaintances to: itself, its own fields, its arguments, objects it creates, and the direct members of its own collections. Everything else is a stranger.

This is the failure it prevents — a "train wreck":

def is_free_shipping(order: Order) -> bool:
    city = order.customer.address.city
    return city in FREE_SHIPPING_CITIES

is_free_shipping reaches through order into customer, then address, then city. The caller now knows the internal geography of three objects it doesn't own. Change customer.address to customer.delivery_address and this breaks even though nothing about shipping changed.

The fix is tell, don't ask: move the behavior to the object that owns the data.

def is_free_shipping(order: Order) -> bool:
    return order.has_free_shipping_to(FREE_SHIPPING_CITIES)

# inside Order:
def has_free_shipping_to(self, cities: set[str]) -> bool:
    return self.customer.delivery_city() in cities

The caller talks to one neighbor (order). The chain still exists — but it lives inside the object that owns the data, where geography changes are contained. The Law of Demeter is not "no chains ever"; it is "nobody walks through strangers."

How a senior designer judges a chain

The first question is not "how many dots" but "how many owners". Open the three types in the chain. If Order, Customer, and Address all live in domain/orders/, maintained by the same four people, the chain is a mild readability issue and probably not worth a refactor. If Address comes from a shared identity package on its own release cadence, every hop into it is a dependency on another team's calendar, and the same three dots are a real liability.

The second question is what kind of thing you are extracting. There is a real difference between pulling out a value and moving a decision. Both look like refactors; only one helps.

The rejected alternative. The reflex fix is to add a forwarding accessor:

# inside Order — looks like the law, isn't
def customer_city(self) -> str:
    return self.customer.address.city

The caller now says order.customer_city() and the reviewer nods. But nothing was decided anywhere new: Order has acquired an opinion about address geography, the chain still exists one frame down, and if Address gains a second delivery address, Order is the thing that breaks. This is Fowler's middle man: a class whose methods mostly delegate. The test that catches it: does the new method express something the object is responsible for, or is it a tunnel dug for one caller's convenience? "What city does this customer receive deliveries in?" is Customer's business. "Does this order ship free?" is Order's business. "What is the string inside my customer's address?" is nobody's business.

The consequence at scale. An identity team changes Customer.address to Customer.addresses, a list, to support a separate billing address. In a 200,000-line codebase, grep -rn "\.address\." returns something in the hundreds across a dozen modules, and each hit has to be judged individually: which address did this caller mean? Nobody can answer that from the call site, because the call site never said. Where the question had been moved into Customer, the same migration is one file and one decision made once, by the team that actually knows the answer. That asymmetry — one deliberate decision versus hundreds of undocumented ones — is the whole cost of the law, and it only shows up on the day someone restructures.

When this is the wrong move

Leave the chain alone when it walks a data structure rather than an object: parsed JSON, a frozen configuration tree, an AST node. There is no owner to ask, and inventing one produces a wrapper class per node type for no benefit. Leave it alone when the chain is the published interface — query builders, assertion libraries, and pipeline APIs are designed to be chained, and "fixing" them destroys the thing you paid for. Leave it alone inside an aggregate root reaching into its own parts, where the root is the owner (lesson 0012). And resist the fix when it would push a foreign concern into a domain object: adding Order.to_html_row() to spare a template three dots trades a small coupling for a large one, because now presentation lives in the domain.

Skill: spot the stranger

Practice on your own code

Search a file you own (or an AI-generated one) for chains: patterns like a.b.c.d or repeated get_x().get_y(). Pick one and, before touching it, answer the two senior questions: how many owners does this chain cross, and what decision is the caller really trying to make? Then move the decision to the object that owns the data — and check you did not just build a middle man.

In the lab: the returns-resolution service reaches through several objects to decide whether a return is eligible. The phase-1 checkpoint asks you to find the deepest chain in that decision path, name the owner that should be answering it, and move the question there — then confirm the test for that rule no longer needs to build three nested objects to run.

# before
if booking.flight.airline.contact_email:
    notify(booking.flight.airline.contact_email)

# after — the airline answers; Booking has no opinion on airline internals
if booking.flight.has_contact_email():
    notify(booking.flight.contact_email())

Read and watch deeper

• Lieberherr & Holland, "Assuring Good Style for Object-Oriented Programs" (IEEE Software, 1989) — the primary source, where the law is stated as a constraint on which objects a method may send messages to.
• The Pragmatic Programmer, Hunt & Thomas — the "Decoupling and the Law of Demeter" topic: the treatment that popularised it, including its cost in coupled deployments.
• Refactoring, Fowler — the "Middle Man" smell in the smells catalogue: the failure mode of over-applying the law by delegating everything.
• "Tell, Don't Ask", Martin Fowler — the companion principle that makes the law workable.
• Code Complete, McConnell — ch. 5: where coupling levels (including "content coupling" — reaching into internals) are ranked.
• Watch: ArjanCodes YouTube — search "Law of Demeter".
• Reference: Glossary — Law of Demeter, Tell, don't ask, train wreck.

Unsure whether a chain is a violation? Ask your agent-teacher to judge a snippet with you — the boundary cases are where the law becomes judgment.

Source page: lessons/0003-law-of-demeter.html

Lesson 0004 · Core Designer · Module 1

Recognizing When Strategy Is Emerging

Patterns are not applied — they are noticed. The Strategy pattern is already in your code the moment one behavior branches on a type. This lesson trains the noticing.

Reading ≈ 11 minPractice ≈ 20 min

Mission tie-in: "recognize when patterns emerge naturally" is a core Designer skill; it's also the difference between AI that copies patterns and code that grows them from evidence.

Knowledge: the shape that already exists

The Strategy pattern's shape: a varying behavior extracted behind an interface, with implementations swapped at runtime without touching the caller. Before it is a pattern, it is a smell — an if/elif chain selecting behavior by a type field:

def discount(customer: Customer, total: Money) -> Money:
    if customer.tier == "gold":
        return total * Decimal("0.90")
    elif customer.tier == "silver":
        return total * Decimal("0.95")
    else:
        return total

Ask: what will change here? The set of tiers — new tiers appear, discounts change, and every edit lands in this one function. That is a variation point with a growing list of branches. The Strategy is emerging: the chain already plays the role of a strategy selector.

Making it explicit:

class DiscountStrategy(Protocol):
    def apply(self, total: Money) -> Money: ...

class GoldDiscount:
    def apply(self, total: Money) -> Money:
        return total * Decimal("0.90")

class SilverDiscount:
    def apply(self, total: Money) -> Money:
        return total * Decimal("0.95")

class NoDiscount:
    def apply(self, total: Money) -> Money:
        return total

def discount(strategy: DiscountStrategy, total: Money) -> Money:
    return strategy.apply(total)

Nothing about behavior changed — the chain was already a strategy; now it is a strategy with names and seams. New tiers become new classes instead of new branches.

How a senior designer decides whether to extract

First they read the chain's history, not the chain. How many arms did it have six months ago? Three, and now five. That is a rate: roughly one new arm a quarter, and the trend is what the decision hinges on — a chain that has had two arms since 2021 is not a variation point, it is a boolean.

Then they look at who adds arms. If every new tier arrives as a ticket from a different stakeholder — growth wants a referral tier, finance wants a wholesale tier — the arms are not one team's implementation detail, they are a queue. Queues want a place to append. If instead one engineer has quietly added all five, the chain is fine and the cost of the pattern would be paid by readers who do not benefit.

Then they reject the lighter option, out loud. The cheapest possible fix is a lookup table:

RATES = {"gold": Decimal("0.90"), "silver": Decimal("0.95")}

def discount(customer: Customer, total: Money) -> Money:
    return total * RATES.get(customer.tier, Decimal("1.00"))

If the variants differ only in a number, stop here — this is smaller, faster to read, and adding a tier is a data change. The reason to go further is that the variants have stopped being numbers. Gold has acquired a cap ("never more than €50 off"), silver applies only between November and January, and wholesale needs the customer's contract. Those are three different behaviours, and a dictionary of rates cannot hold them without growing a second dictionary of exceptions beside it. That is the moment the strategy earns its indirection: not when the list got long, but when the arms stopped being the same shape.

The consequence over a year. Left as a chain, the tier logic on a mid-sized commerce team reaches nine arms and about 140 lines, and becomes the file with the most merge conflicts in the repository; because every arm lives in one function, every discount change requires re-running and re-reading the whole test class, and the team develops a habit of adding an arm at the top with an early return "to be safe". Extracted, the same nine variants are nine small files, each with its own test, and the selection is a dictionary someone can read in five seconds. The second version is not more elegant — it is cheaper to change concurrently, which is what actually mattered.

When this is the wrong move

• Two stable arms. A boolean wearing a string. Extracting gives you two classes, an interface, and a factory to express if.
• Data-only variation. If the arms differ by a rate, a threshold, or a message, put them in a table. A strategy per row is a class hierarchy pretending to be a configuration file.
• Variants that compose. Strategy assumes exactly one implementation is chosen. When several adjustments can apply at once, you want a list you fold over, not a selection — reaching for Strategy here produces a class per combination.
• Selection driven by untrusted input. A registry keyed by a string from a request is a dispatch table an attacker can aim. Validate the key against a closed set before it reaches the lookup, and never build the class name from input.

Skill: see the strategy inside the code

Practice on your own code

Find an if/elif chain (or match) in your codebase that selects behavior by a field or string. Gather the two pieces of evidence before deciding: how many arms it had six months ago, and whether the arms differ by a value or by a behaviour. Then commit to a call — extract now, drop to a lookup table, or write the variation point down in a note and keep watching.

In the lab: the returns-resolution service branches on the reason a customer gives for a return, and the list has been growing. The phase-1 checkpoint asks you to decide whether that chain has earned a strategy or only a lookup table, and to justify the call with the arm-arrival rate rather than with taste.

Read and watch deeper

• Head First Design Patterns, Freeman et al. — ch. 1: Strategy taught by noticing a problem, not by memorizing a diagram.
• Design Patterns, Gamma et al. — ch. 5, Strategy: the canonical reference.
• Refactoring Guru — Strategy: the "problem/solution" framing that matches this lesson's noticing-first approach.
• Refactoring, Fowler — "Replace Conditional with Polymorphism" in the refactoring catalogue: the mechanical steps for the transformation above, and the preconditions that tell you it is safe.
• Watch: ArjanCodes YouTube — search "strategy pattern python".
• Reference: Patterns Quick Reference — Strategy, with the shape and the “don't”.

Show your agent-teacher a branching snippet and compare judgments on whether a strategy is truly emerging.

Source page: lessons/0004-spotting-emerging-strategies.html

Lesson 0005 · Core Designer · Module 1

Structural Issues in AI-Generated Code

AI output is legacy code from an author who won't answer questions. This lesson turns your structural eye on the five defects AI code most reliably carries.

Reading ≈ 13 minPractice ≈ 25 min

Mission tie-in: you'll generate more code with AI, not less. The skill that keeps you in control is the ability to review structure the way you'd review a stranger's pull request — this lesson is that review checklist.

Knowledge: the five recurring defects

AI produces fluent, plausible code — and fluently repeats the same structural defaults:

1. God functions and helper sprawl. One function that does everything, or the opposite: twenty micro-helpers with no shape, built to keep each output chunk short.
2. Hidden global state. Module-level mutable containers, caches, and singletons that make behavior depend on call order.
3. No invariants. Data accepted and mutated freely; invalid states possible by construction.
4. Bare exception handling. except Exception with pass, or errors converted to None — failure becomes invisible and travels.
5. Missing seams. Hardcoded I/O, sleep, and environment access inside logic that should be pure and testable.

Treat AI output as legacy code from an unknown author. The discipline that applies is the one Michael Feathers wrote for legacy code: find the seam, lock the behavior with a characterization test, then restructure with confidence.

def process_all(users: list[dict]) -> None:
    processed = []
    cache = {}                     # rebuilt every call: dedup never spans batches
    for u in users:
        if u["email"] in cache:
            continue
        try:
            resp = requests.post("https://api.example.com/notify", json=u)
            if resp.status_code != 200:
                return  # silently stops mid-batch
            cache[u["email"]] = True
            processed.append(u)
        except Exception:
            pass  # swallows everything
    return processed  # annotated -> None, yet returns a list on the happy path

Name what's wrong — and this snippet carries nearly every defect on the list: network I/O welded to logic (no seam, so no test runs without a network), a bare except Exception that swallows a typo as readily as a timeout, a mid-loop return that abandons the remaining users and hands back None, a return type that contradicts the annotation, and a cache rebuilt on every call — so the de-duplication it appears to buy never survives a second batch.

How a senior designer reviews that snippet

They read the signature before the body. def process_all(users: list[dict]) -> None — and the function returns a list. That contradiction takes four seconds to find and tells you the annotation was decoration, not a claim anyone checked. Contracts are where lies are cheapest to detect, which is why they are read first.

Then one question about testability: what would I have to stand up to run this? A network. That single answer settles the seams question without reading the loop: any test of this function is an integration test, so in practice there will be no test.

Then they hunt for silent exits — every path on which the function ends without saying anything. There are two: the return inside the loop and the except Exception: pass. The question that turns those into a business statement is what does the caller see when thirty of five hundred users fail? The answer is None, which is indistinguishable from the result of an empty input. A partial failure has been laundered into a success.

The rejected fix. The reflex is to wrap the call site:

try:
    process_all(users)
except Exception:
    logger.exception("notification batch failed")

This is treating the symptom. The function still cannot be tested without a network, still abandons the batch mid-loop, and still returns nothing the caller can act on — and now there is a log line that fires only in the cases the function did not swallow, which is the opposite of the ones you need to hear about. A reviewer's tell: if the fix is entirely outside the function, you have decided not to fix it.

The consequence over time. Five hundred users, item twelve raises, four hundred and eighty-eight notifications are never sent, and the batch reports success. Nobody learns anything until a customer asks why they were not told about something three weeks ago — and by then there is no log line, no failure record, and no way to reconstruct which users were skipped, because the only artefact that ever knew was the traceback that pass deleted. The cost of the defect is not the outage; it is that the system destroyed the evidence needed to understand it.

When this is the wrong move

Skip the checklist when the code is genuinely disposable — a scratch analysis, a one-shot migration, a spike you will read once and delete — because structure is an investment in future change and there will be none. Skip it when the generated unit is a leaf: a pure function with no I/O, fully pinned by example tests. There, read the examples against the business rule instead; structure is not the risk. And be honest about the arithmetic on small pieces: if applying the five points costs more than writing the twenty lines yourself, write them yourself. The checklist earns its place on code that will be changed by someone else, later, under time pressure.

Skill: run the AI review checklist

Practice on your own code

Take a function AI generated for you recently. Run the five-point checklist (god function, hidden global state, missing invariants, bare exceptions, missing seams). Before fixing anything, answer the two senior questions: what would I have to stand up to run this, and what does the caller see when part of the work fails? Then fix exactly one defect, with a test that would have failed before.

In the lab: parts of the returns-resolution service were generated rather than designed, and carry these defects verbatim. The phase-1 checkpoint asks you to run the five-point review over one generated module, write a characterization test that pins its current behaviour — including the behaviour you disagree with — and only then change the structure.

class Notifier(Protocol):
    def notify(self, user: dict) -> None: ...

def process_all(users: list[dict], notifier: Notifier) -> BatchResult:
    result = BatchResult()
    seen: set[str] = set()
    for user in users:
        if user["email"] in seen:
            result.skipped(user)
            continue
        seen.add(user["email"])
        try:
            notifier.notify(user)
        except NotifyFailed as exc:
            result.failed(user, exc)
        else:
            result.done(user)
    return result

Read and watch deeper

• Working Effectively with Legacy Code, Feathers — ch. 4 "The Seam Model" (where a seam is defined as a place you can change behaviour without editing in that place) and ch. 13, "I Need to Make a Change but I Don't Know What Tests to Write", which is where characterization tests are introduced.
• Google's code review guide — what to look for: a primary source on reviewing design before lines, written for exactly the case where you did not write the code.
• A Philosophy of Software Design, Ousterhout — ch. 16 "Modifying Existing Code": how to improve unfamiliar code without breaking it.
• Clean Code, Martin — ch. 7 "Error Handling": why bare excepts and silent returns are structural defects.
• Watch: ArjanCodes YouTube — search "AI code review" or "AI coding best practices".
• Next: lesson 0010 covers steering AI toward better structure from the start.
• Reference: Patterns — seam / characterization test; glossary — seam, characterization test.

Paste an AI-generated function to your agent-teacher and ask for the five-point review — then argue with its findings.

Source page: lessons/0005-structural-issues-in-ai-code.html

Lesson 0006 · Core Designer · Module 2

Design Around Reasons to Change

Responsibilities are fuzzy; change sources are facts. Structure your modules around the forces that will actually edit them.

Reading ≈ 12 minPractice ≈ 25 min

Mission tie-in: "design around reasons to change" is the upgrade from lesson 0002's SRP. It turns a principle into a method you can apply before writing a line.

Knowledge: the change source is the unit

Every future edit to your codebase comes from a finite list of forces: tax law changes, a new payment provider, a new report format, a re-branding. Call each one a reason to change. Design says: code that changes for the same reason lives together; code that changes for different reasons lives apart.

Consider an invoice class:

class Invoice:
    def __init__(self, lines: list[Line], vat_rate: Decimal) -> None:
        self.lines = lines
        self.vat_rate = vat_rate

    def total(self) -> Money:
        subtotal = sum(line.price for line in self.lines)
        return Money(subtotal * (1 + self.vat_rate))

    def to_html(self) -> str:
        rows = "".join(f"<tr><td>{l.name}</td></tr>" for l in self.lines)
        return f"<table>{rows}</table>"

    def to_json(self) -> dict:
        return {"lines": [{"name": l.name, "price": str(l.price)} for l in self.lines]}

Two reasons to change are welded together: how invoices are calculated (tax rules, discounts) and how invoices are rendered (HTML tweaks, new JSON fields for a mobile client). When the mobile client needs a new field, you edit the class that owns the tax calculation — and risk the tax rules.

The stable design separates them:

class Invoice:
    def __init__(self, lines: list[Line], vat_rate: Decimal) -> None:
        self.lines = lines
        self.vat_rate = vat_rate

    def total(self) -> Money:              # reason: pricing rules
        subtotal = sum(line.price for line in self.lines)
        return Money(subtotal * (1 + self.vat_rate))

class InvoiceRenderer:
    def __init__(self, invoice: Invoice) -> None: ...
    def to_html(self) -> str: ...          # reason: web presentation
    def to_json(self) -> dict: ...         # reason: API contract

Now a pricing change edits Invoice and nothing else; a rendering change edits InvoiceRenderer and nothing else. Note what you did not do: you didn't count methods, and you didn't split for symmetry. You named the change sources — the whole method.

How a senior designer finds the line

A 250,000-line commerce codebase, four teams. invoice.py is the file everyone complains about.

They start with the co-change data, not the class diagram. git log --name-only --since=1.year over the last thirty commits that touched invoice.py shows two clusters that barely overlap: seven commits also touching tax_tables.py, all authored by the finance-integration team; twenty-two also touching templates/, all authored by the growth team. Two disjoint editor populations on one file. That is the measurement, and it took two minutes.

Then the question: has any single commit needed both? If tax changes and template changes have never landed together, the file is holding two things that have no reason to be in the same room. If they routinely land together, the coupling is real and splitting them would just move the cost into coordination.

Then they reject the split everyone proposes. The reflex refactor is to layer it: InvoiceModel, InvoiceService, InvoiceRepository. This is the most common wrong answer in the industry, and it is wrong for a precise reason: layering slices along mechanism — data, orchestration, storage — while the forces that issue edits run along subject matter. After the layer split, a VAT rate change touches the model (the rate), the service (the calculation order), and the repository (the stored breakdown); a template change touches the service and the model too. The average edit went from one file to three, the review from one team to two, and the file everybody complained about has become three files everybody complains about. The tell: after a split, count the files an average edit touches. If it went up, the axis was wrong.

The split that works puts tax calculation in one module with a finance owner and presentation in another with a growth owner. Now tax pull requests touch one file and need one reviewer who knows tax; template pull requests touch one file and need one reviewer who knows the brand. The two teams stop appearing in each other's diffs, and — the part that actually shows up in delivery metrics — stop waiting on each other's review queues.

The consequence over a year. Before: median invoice pull request touches three files, needs two reviewers from different teams, and waits on whichever is busier. After: one file, one reviewer, same day. Nothing about the business logic changed. The entire improvement came from putting the boundary where the edits already were.

When this is the wrong move

Do not design around change sources you have invented. In a domain you have worked in for two weeks, the list of "reasons to change" you can produce is a list of guesses, and each guess that turns out wrong leaves a boundary you now have to maintain and eventually move — which is more expensive than the coupling you were avoiding. Keep it in one module, let it get uncomfortable, and split when the history tells you where. Equally, do not split a file whose two "reasons" are really one reason wearing two hats: a rename that touches both the calculation and the label is one change source, not two, and separating them means every rename becomes two commits. And a module with a single owner, a low change rate, and no cross-team traffic is not worth restructuring however many jobs it appears to do — the arithmetic in lesson 0001 multiplies by a change frequency near zero.

Skill: name the change sources

Practice on your own code

Pick your most-edited class and run the measurement rather than the intuition: git log --name-only --since=1.year -- <that file>, then group the commits by author and by subject. If they fall into disjoint clusters, you have found a split that would already have paid for itself. If they do not, you have learned something more valuable — the file is fine and your discomfort was about its size.

In the lab: the returns-resolution service ships with a commit history designed to be read this way. The phase-1 checkpoint asks you to derive the change sources of its largest module from that history, propose the boundary, and say explicitly which layered split you are rejecting and why.

Read and watch deeper

• Clean Architecture, Martin — ch. 7 (SRP as "one reason to change") and ch. 8 (Open-Closed: design for extension along the change source).
• A Philosophy of Software Design, Ousterhout — ch. 2 "The Nature of Complexity": complexity defined as "anything that makes change hard".
• Refactoring, Fowler — ch. 3 "Bad Smells in Code": smells are symptoms; change sources are the diagnosis. "Divergent Change" and "Shotgun Surgery" are this lesson's two failure modes, named.
• Your Code as a Crime Scene, Adam Tornhill — the chapters on hotspots and temporal coupling: how to compute the co-change analysis above from a repository, and what the numbers do and do not license you to conclude.
• Watch: ArjanCodes YouTube — search "single responsibility".
• Reference: Design Principles — SRP; and the glossary on reason to change.

Bring a class you edit often to your agent-teacher and co-list its change sources — disagreement is where the insight lives.

Source page: lessons/0006-designing-around-reasons-to-change.html

Lesson 0007 · Core Designer · Module 2

Composition over Inheritance

Inheritance is a fuse: the subclass detonates with the superclass. Composition is a seam. Learn to tell the two apart — and when the fuse is worth keeping.

Reading ≈ 12 minPractice ≈ 20 min

Mission tie-in: "replace inheritance with composition where it matters" is one of Arjan's seven principles, and the #1 structural fix AI-generated hierarchies usually need.

Knowledge: the fuse and the seam

When FancyLogger extends Logger, every change to Logger — its constructor, its storage, its naming — propagates into FancyLogger. The subclass cannot survive alone, cannot be tested alone, cannot be reused elsewhere. That's the fuse.

The classic failure is subclassing for reuse rather than for polymorphism:

class FileBackedLogger(Logger):
    def __init__(self, path: str) -> None:
        super().__init__()
        self.path = path
        self._file = open(path, "a")

    def log(self, msg: str) -> None:
        super().log(f"[file] {msg}")
        self._file.write(f"{msg}\n")

"I need logging, I'll extend the logger" — that's reuse-by-inheritance, and it pays for the fuse: the file-handling lifecycle is now welded to the logger's, and the subclass can't be used with a different base behavior.

Composition says: hold it, delegate to it, decide its life yourself.

class FileBackedLogger:
    def __init__(self, sink: Logger, path: str) -> None:
        self._sink = sink
        self._file = open(path, "a")

    def log(self, msg: str) -> None:
        self._sink.log(msg)
        self._file.write(f"{msg}\n")

Now FileBackedLogger owns its lifecycle, can wrap any logger, and can be tested with a fake sink. The seam is visible: you can see exactly where one behavior ends and the other begins.

class CountingList(list):
    def __init__(self) -> None:
        super().__init__()
        self.added = 0

    def append(self, item) -> None:
        self.added += 1
        super().append(item)

    def extend(self, items) -> None:
        self.added += len(items)
        super().extend(items)

How a senior designer reviews a new subclass

A pull request adds RetryingHttpClient(HttpClient).

They look at two things before the logic: what the subclass overrides, and what state it adds. Those two answers classify it. If it overrides methods the base declares and adds no state, it varies — legitimate. If it overrides nothing and calls super() everywhere while adding fields of its own, it borrows — the fuse.

Then the question: if I deleted every method this class overrides, would anything about the base's contract change for its callers? For a varying subclass the answer is yes — the whole point was to change behaviour behind a shared type. For a borrowing subclass the answer is no, and you have just discovered that the inheritance is doing no work except giving you access to the base's methods, which delegation would give you with a visible dependency instead of a hidden one.

Two alternatives rejected. The first is to keep the hierarchy but tighten the base — make its helpers private, document which methods may be overridden. This does not help, because it is precisely the base's public surface that the borrowing subclass wants; you have added rules without removing the coupling. The second is a mixin. Mixins look like composition — small, focused, combinable — and are multiple inheritance: same shared namespace, same fragile base problem, plus method resolution order, so the behaviour now depends on the order the classes are listed in. A mixin is the fuse with a friendlier name.

The consequence over time, at scale. The end state of reuse-by-inheritance is not a bug; it is paralysis. On one platform team, a base class accumulated forty subclasses and a dozen protected helpers. A change to one helper's contract meant reading forty subclasses to find out who depended on the old behaviour, so the team did it once, took two weeks, shipped one regression — and thereafter refused to touch the base at all. The hierarchy stopped being a design and became a liability nobody was allowed to edit: new behaviour got bolted on outside it, and the "shared" code stopped being shared in any useful sense. That is the real cost, and it does not appear in any one commit.

When this is the wrong move

• Framework base classes. If the ORM, the test runner, or the web framework requires a subclass, inherit and move on. The coupling is real, but the alternative is fighting a tool that will win.
• Exception hierarchies. class PaymentDeclined(PaymentError) is inheritance used exactly right: the "is-a" is the entire feature, because callers catch by type, and there is no implementation being borrowed.
• Closed sum types. A base plus four dataclasses representing four known variants gives you exhaustive handling and a shared type. The set is closed and small, so the fragile-base risk is bounded.
• Wide interfaces. If delegating means forwarding twenty methods to add one behaviour, the wrapper is worse than the fuse. That is a real signal — the interface is too wide — but if you cannot narrow it today, inheriting and writing down why is the honest call. Do not reach for __getattr__ forwarding to make the boilerplate go away: it recreates the fuse invisibly and defeats every tool that reads the class.

Skill: fuse or seam?

Practice on your own code

Find a subclass in your codebase (or an AI-generated one) and run the classification test before touching anything: list what it overrides and what state it adds, then ask whether deleting its overrides would change the base's contract for any caller. If it borrows, convert it to composition — hold the base, delegate the method — and notice how much smaller the dependency becomes once it is written out explicitly.

In the lab: the returns-resolution service has a small hierarchy where one subclass exists to borrow rather than to vary. The phase-1 checkpoint asks you to identify which one, convert it to delegation, and show that the resulting class can be exercised in a test without constructing its former base at all.

# a CsvExporter that "is a" DatabaseExporter, reusing its row logic
class CsvExporter(DatabaseExporter):          # wrong: borrows, doesn't vary
    ...

# becomes: CsvExporter holds the database reader and formats its rows
class CsvExporter:
    def __init__(self, source: RowSource) -> None:   # RowSource = any row provider
        self._source = source

Read and watch deeper

• Design Patterns, Gamma et al. — the introduction's "Favor object composition over class inheritance": the original statement.
• Head First Design Patterns, Freeman et al. — ch. 1: the duck example that made this principle famous.
• Fluent Python, Ramalho — "Inheritance: For Better or for Worse" (ch. 14 in the 2nd edition, ch. 12 in the 1st): subclassing built-in types, why CountingList-style overrides are unreliable, and when a nominal hierarchy is still the right tool.
• Barbara Liskov & Jeannette Wing, "A Behavioral Notion of Subtyping" (ACM TOPLAS, 1994) — the primary source for the promise inheritance makes on your behalf, and therefore for what it means to break it.
• Watch: ArjanCodes YouTube — search "composition over inheritance".
• Reference: Design Principles — composition over inheritance.

Unsure whether your hierarchy is legitimate variation? Ask your agent-teacher to interrogate the "is-a" claim with you.

Source page: lessons/0007-composition-over-inheritance.html

Lesson 0008 · Core Designer · Module 2

Strategy, Adapter, and Facade, Intentionally

Lesson 0004 taught you to notice Strategy emerging. Here you learn to reach for it — and for its two structural cousins — on purpose, with the problem first.

Reading ≈ 11 minPractice ≈ 25 min

Mission tie-in: "use patterns intentionally" means naming the problem you have before naming the pattern that fixes it. That order is the whole difference between designing and decorating.

Knowledge: three problems, three shapes

Strategy — problem: one behavior varies; the context should not. Shape: interface + implementations + delegation. You saw it emerging in lesson 0004; here you apply it before the branch chain forms, because the variation is already proven.

Adapter — problem: your code needs interface A; a service speaks interface B, and B is not yours to change. Shape: a wrapper that implements A and translates into B.

class PaymentGateway(Protocol):              # your interface: named for the need
    def charge(self, amount: Money, token: str) -> str: ...

class StripeSdkAdapter:                      # adapts a third-party SDK to it
    def __init__(self, client: StripeSDK) -> None:
        self._client = client

    def charge(self, amount: Money, token: str) -> str:
        result = self._client.payment_intents.create(
            amount=int(amount.cents), currency=amount.currency, token=token
        )
        return result.id

Note the naming: the interface is PaymentGateway, not StripeGateway. An adapter that names itself after the thing it adapts has already let the vendor define your vocabulary — the arrow you will straighten in lesson 0009.

Facade — problem: clients must orchestrate several subsystems to do one recurring thing. Shape: one class with a few coarse methods that drive the subsystems.

class CheckoutFacade:
    def __init__(self, inventory, payments, shipping, email) -> None: ...

    def place_order(self, cart: Cart, payment_token: str) -> Order:
        self._inventory.reserve(cart)
        charge_id = self._payments.charge(cart.total, payment_token)
        order = self._shipping.create_shipment(cart)
        self._email.send_confirmation(cart.customer, order)
        return order

Three patterns, three problems: vary a behavior, translate an interface, simplify a ritual. If you cannot name which problem you have, applying any of them is decoration.

How a senior designer chooses in a real review

A payments integration. Three engineers, a six-week window, one vendor live and a second in a commercial conversation that may or may not conclude.

They start by counting call sites, not by naming patterns. The SDK is called in six places across three modules. That number is the input to everything else: it is the size of the edit if the vendor changes, and the size of the indirection tax if it does not.

Then they price both errors. Wrong to adapt: one extra file, about forty lines, and one hop of indirection on six call sites — recoverable in an afternoon. Wrong not to adapt: a vendor migration touching six call sites in three modules, with no test that can run without a network, under whatever deadline the commercial decision arrives with. The costs are wildly asymmetric, so the adapter goes in — not because adapters are good, but because the mistake it prevents is the expensive one.

Then they reject the version of this decision that has no brakes. The same argument, applied uniformly, produces a port for the logger, a port for datetime.now(), and a port for the templating library. The rule that stops it is worth memorising: adapt what you might have to replace; stub what you must control in a test; leave everything else alone. A clock is the second kind — you do not need a ClockPort hierarchy, you need to pass a function. A logger is usually the third kind: you are not going to replace it, and if you do, the migration is a configuration change.

Then the facade gets the same scrutiny. The proposed CheckoutFacade also handles refunds and subscription renewals. Three rituals, one class — and that class becomes the file every team edits, which is the merge-conflict hot-spot from lesson 0006 arriving by a different road. One ritual per facade. If two rituals share steps, share the steps, not the facade.

The consequence, eighteen months on. The payments port did its job: the vendor change was eleven days of work, contained to one adapter and its tests, with the domain untouched. The logging port that nobody needed cost four hours to write, and then cost every new joiner an afternoon of confusion about why log.info was not log.info. Both decisions came from the same principle. Only one of them was priced.

When this is the wrong move

Skip the adapter when there is one call site, no realistic replacement, and a test that already runs without the dependency — the wrapper is then pure ceremony, and ceremony is what gives patterns a bad name. Skip the facade when the ritual happens in exactly one place: a sequence with one caller is a function, and wrapping it in a class hides nothing from nobody. Skip the strategy when there are two stable arms. And treat a facade in a published library differently from one inside your own system: there, freezing a sequence behind one method is a compatibility commitment your users will hold you to for years, so the convenience you are offering is also a constraint you are accepting.

Skill: match the problem to the pattern

Practice on your own code

Find one recurring ritual (three or more lines repeated in several callers) and one interface mismatch in your codebase. Before applying anything, price both errors the way the review above does: what does it cost if you wrap it and never needed to, and what does it cost if you do not and later must? Then apply a Facade to the ritual and an Adapter to the mismatch. If you find neither, say so out loud — refusing to apply a pattern is the same discipline as applying one.

In the lab: the returns-resolution service contains all three problems — a growing branch over resolution outcomes, a third-party carrier client called from several places, and a four-step ritual copied into two callers. The phase-1 checkpoint asks you to label each one with the problem it actually is before naming any pattern, and to defend one case where the right answer is to do nothing.

Read and watch deeper

• Design Patterns, Gamma et al. — ch. 4 (Adapter, Facade) and ch. 5 (Strategy): the canonical intent statements.
• Head First Design Patterns, Freeman et al. — ch. 1 (Strategy) and ch. 7 (Adapter & Facade): problem-first teaching.
• Refactoring Guru — the intent/fit framing for all three.
• A Philosophy of Software Design, Ousterhout — ch. 6 "General-Purpose Modules are Deeper" and ch. 4 on interface versus implementation: the argument for shaping a port by what the caller needs rather than by what the supplier offers.
• Watch: ArjanCodes YouTube — search "design patterns python" for the channel's walkthroughs.
• Reference: Patterns Quick Reference — the “find the pattern by the problem” table, plus Decorator, the fourth structural shape this lesson's trio leaves out.

Describe a messy integration to your agent-teacher and ask which of the three problems it is — before either of you names a pattern.

Source page: lessons/0008-strategy-adapter-facade.html

Lesson 0009 · Core Designer · Module 2

Controlling Dependency Direction

The most important arrows in your architecture point at the domain. Ports & Adapters is the mechanism for drawing them correctly — this lesson is the drawing lesson.

Reading ≈ 11 minPractice ≈ 25 min

Mission tie-in: dependency direction is what makes the domain your asset. Every later phase builds on this: repositories, infrastructure isolation, event-driven systems.

Knowledge: the arrow points inward

In a well-directed system, the domain — the rules that are true regardless of technology — depends on nothing. The world (databases, APIs, files, clocks) depends on the domain. The domain declares ports: the interfaces it needs. The world supplies adapters: implementations of those ports.

# the domain defines the port it needs:
class PaymentGateway(Protocol):
    def charge(self, amount: Money, token: str) -> str: ...

class CheckoutService:
    def __init__(self, gateway: PaymentGateway, orders: OrderRepository) -> None:
        self._gateway = gateway
        self._orders = orders

    def checkout(self, cart: Cart, token: str) -> Order:
        charge_id = self._gateway.charge(cart.total, token)
        order = Order.from_cart(cart, charge_id)
        self._orders.save(order)
        return order

Now the adapter, living outside the domain:

# infrastructure provides the adapter:
class StripeAdapter:
    def __init__(self, client: StripeSDK) -> None:
        self._client = client

    def charge(self, amount: Money, token: str) -> str:
        return self._client.payment_intents.create(...).id

Who owns the interface? The domain does. That single fact is the whole pattern. If the payment SDK defines what your checkout logic looks like, the arrow points the wrong way.

Test it: swap Stripe for a fake adapter and run checkout with no network, no SDK, no mocks — the domain never knows. The port made that possible.

How a senior designer audits an existing hexagon

A team whose README says "hexagonal architecture" and whose codebase has fourteen ports.

The first thing they check is not the arrows but the implementations. For each port: how many classes implement it, counting the test fake? A port with two or more is doing work. A port with exactly one implementation and no fake is unpaid indirection — it obeys the letter of the pattern and buys nothing, and there are usually four or five of them.

The question they ask per port: name the thing on the other side you might have to replace, or the test that needs the seam. If neither answer exists, the port exists because the pattern was applied, not because a problem was solved. Deleting it is a legitimate outcome of an architecture review, and saying so is what stops a good idea from becoming a ritual.

Then the interesting case. One port is ReportRepository, and its single method is:

class ReportRepository(Protocol):
    def run(self, sql: str) -> list[dict]: ...

Every dependency arrow points the right way. The domain imports no database driver. And the boundary is gone anyway, because the database's language crossed it inside a string: the domain is now writing SQL, and swapping the adapter would require rewriting every caller. This is the case worth memorising — you can satisfy the import graph and still lose the boundary, because ports are judged by vocabulary, not by the shape of the imports.

The alternative they reject. The obvious repair is to add a method to the port for each report: top_customers(), refunds_by_week(), and so on. Follow that and in a year the port has forty methods, every one of which is a query with a name — the ORM, reimplemented, with a worse query planner and no composability. The tell: the interface grows one method per use case and never stabilises.

The call they make instead is to stop pretending reporting is domain logic. Reads that answer questions — dashboards, exports, analytics — are given their own module that talks to the database directly and returns plain rows, while the port stays for the transactional domain where invariants actually live. This is not a compromise of the pattern; it is the recognition that the pattern protects rules, and a report has none.

The consequence, measured. While every new report went through the domain port, it needed a change to the interface, a change to the adapter, and a review from the domain owner: median lead time nine days for something an analyst could describe in a sentence. After the read path was split out, the same work was one module and one reviewer, and shipped the same week. The ports that remained got taken seriously again, because they were no longer in the way of work they had nothing to do with.

When this is the wrong move

Do not build a hexagon around a service whose domain is its schema. If the business rules amount to "validate these fields and store the row", the ports are ceremony and the composition root is a second thing to maintain; a straightforward layered service is honest and cheaper. Do not build a port for something you cannot actually replace — your language runtime, your cloud provider's identity model, the framework your whole company standardised on. The insurance premium is real and the claim will never be filed. And do not force read-heavy paths through a domain port: hiding a query language costs more than it protects when there are no invariants on the other side. Rules go through the port; reports go around it.

Skill: which way is the arrow?

Practice on your own code

Pick one external thing your code touches (a database, an API, a filesystem). Draw the arrow: does your domain's shape follow the external thing, or does the external thing conform to your domain? If the former, introduce a port — even if only for that one dependency. Then run the audit in the other direction: for every interface you already call a port, name the second implementation or the test that needs it. Any port that fails that question is a candidate for deletion, and deleting it is as much a win as adding one.

In the lab: the returns-resolution service imports a carrier client and a payments client directly inside its decision logic. The phase-1 checkpoint asks you to introduce one port shaped by what the decision actually needs — not by what the vendor offers — and to prove it by running the resolution rules in a test with no network and no mocking library.

Read and watch deeper

• "Hexagonal Architecture", Alistair Cockburn — the original statement of ports and adapters.
• Architecture Patterns with Python, Percival & Gregory — ch. 2 "Repository Pattern" and ch. 3, "A Brief Interlude: On Coupling and Abstractions": the Python working version of this lesson, including the fake repository that proves the seam.
• Clean Architecture, Martin — ch. 17–18 on drawing boundaries and their anatomy, and ch. 22, where the dependency rule is stated in its strongest form.
• import-linter — the tool that turns this lesson's arrow into a build failure. A rule your CI enforces outlives the review that agreed on it (lesson 0022).
• Watch: ArjanCodes YouTube — search "ports and adapters" or "hexagonal architecture".
• Reference: Glossary — port, adapter, dependency direction.

Map your project's dependency arrows with your agent-teacher — let it push back on where you claim the boundary is.

Source page: lessons/0009-ports-and-adapters.html

Lesson 0010 · Core Designer · Module 2

Guiding AI Toward Better Structure

Lesson 0005 taught you to review AI output. This lesson teaches you to steer it before it writes: specify the seams, then let the AI fill them in.

Reading ≈ 10 minPractice ≈ 25 min

Mission tie-in: "guide AI toward better structure instead of patching bad outputs" — the exact skill that separates developers who stay in control from developers whose codebase becomes the AI's drafting table.

Knowledge: you are the architect, AI is the drafter

A drafter draws what the architect specifies. Ask an AI to "build a checkout" and you will get a god function with SDK calls inside — because you specified a feature, not a structure. Ask it to implement a structure you already designed and the output inherits your design.

The recipe — specify the seams first:

1. Name the boundary. Which parts are domain, which are infrastructure? State it in the prompt: "domain code must not import the SDK."
2. Declare the ports. Give the interfaces: PaymentGateway, OrderRepository. "Implement the adapter, not the port."
3. State the invariants. "An order can never be confirmed twice." AI will encode what you tell it to protect.
4. Ask for the tests. "Write the tests first, with an in-memory fake adapter." The tests document the structure as much as they verify it.

# prompt shape (paraphrased):
# Implement checkout for the CheckoutService below. Do NOT modify this
# class or the PaymentGateway port. Domain code must not import Stripe.
# Write StripeAdapter in infrastructure/, plus tests using a FakeGateway.

class PaymentGateway(Protocol):
    def charge(self, amount: Money, token: str) -> str: ...

class CheckoutService:
    def __init__(self, gateway: PaymentGateway, orders: OrderRepository): ...

Now the AI's freedom is bounded by your structure. Bad output is still possible — AI loves a helper explosion — but the defects are now in the filling, not the frame.

How a senior designer writes the brief

The task: sync inventory from a supplier API, to be generated rather than hand-written.

They start from what they are unwilling to review. Not "what should this code do" but which mistakes would I fail to notice in a diff? Three answers: dependency direction, because an import inside a new file looks like every other import; error semantics under partial failure, because the happy path is what a reviewer reads; and whether the tests actually exercise the seam or quietly patch around it. Those three become the specification. Everything else — naming, HTTP details, retry timings — is left free, because a wrong choice there is visible in review and cheap to change.

The alternative they reject is the forty-line prompt. It dictates naming conventions, file layout to the character, docstring style, and the logging format, and it reads like rigour. In practice it does two harmful things: it buries the three constraints that matter among thirty that do not, and it spends the model's attention on compliance with cosmetics. The better artefact is smaller and harder — the port pasted in as literal code, one forbidden import, one test that must pass. Three sentences you could check mechanically beat forty you could not.

Then the move that outlives the session. A prompt is gone when the window closes; the next developer, and the next generation, know nothing about it. So the durable form of "domain must not import the SDK" is not a sentence in a chat — it is an import contract in CI:

# architecture test: the rule survives the conversation that agreed it
FORBIDDEN = {"stripe", "requests", "boto3"}

def test_domain_imports_no_vendors() -> None:
    for module in walk_modules("app/domain"):
        assert not FORBIDDEN & imports_of(module), module

Now the constraint is enforced by something that does not get tired on a Friday afternoon, and it applies equally to code written by a person, by a model, or by a person in a hurry using a model. This is the fitness-function idea from lesson 0022, aimed at the specific problem that generated code arrives faster than review can inspect it.

The consequence at team scale. Take a team of five where roughly a third of new code is generated. Without a checkable frame, structural defects arrive faster than review removes them; nothing dramatic happens in any given week, and within a quarter the architecture the team believes it has and the architecture in the repository have quietly separated. With three machine-checked constraints, drift is caught by a build, not by a reviewer's diligence — and the reviewer's attention goes where a machine cannot help: whether the business rule is right at all.

When this is the wrong move

Do not frame exploratory work. When the question is "what would this look like using library X", a specification pre-commits you to a design you are still trying to evaluate, and you get a fluent answer that forecloses the alternatives you were asking about. Do not specify a boundary you have not earned: if you do not yet know where the seam belongs, saying it confidently produces a guess embedded in twenty files rather than in one. Do not bother for genuinely mechanical output — a data migration, a batch of fixtures, a translation of a schema — where structure is irrelevant and correctness is checked by running it. And apply the arithmetic honestly: for twenty lines, writing the specification costs more than writing the code, so write the code.

Skill: prompt with the design first

Practice on your own code

Pick a small feature you'd normally hand to AI. Before writing the brief, answer the senior question: which mistakes here would I fail to notice in a diff? Specify only those, as constraints something could check. Then generate, and run the five-point checklist from lesson 0005: how many defects did the spec prevent, and which one of your three constraints could you turn into a test that outlives the session?

In the lab: the returns-resolution service is the place to try this end to end. The phase-1 checkpoint asks you to write a boundary brief for one new capability, generate against it, review the result with the five-point checklist, and then convert your most important constraint into an executable check that fails the build if a later change breaks it.

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 3 "Working Code Isn't Enough" (tactical versus strategic programming: a generator is a tactical programmer with unlimited stamina) and ch. 16 "Modifying Existing Code".
• Architecture Patterns with Python, Percival & Gregory — ch. 2–4: the seams (repository, service layer) this lesson's prompts encode.
• Study the official sdm example code — structure worth imitating in your prompts.
• Watch: ArjanCodes YouTube — search "AI code generation" for Arjan's guidance videos.
• Next: lesson 0011 starts Module 3, protecting the domain core.
• Reference: Patterns — Ports & Adapters and composition root: the two shapes worth naming in every prompt.

Draft a boundary spec with your agent-teacher for a feature you're about to generate — then compare the spec you'd have written alone.

Source page: lessons/0010-guiding-ai-toward-better-structure.html

Lesson 0011 · Core Designer · Module 3

Modeling Domain Invariants Directly

An invariant is a rule the domain cannot break. If your callers must remember to respect it, you don't have an invariant — you have a hope.

Reading ≈ 9 minPractice ≈ 25 min

Mission tie-in: "make invalid states impossible" is the Core Designer's third pillar. It's also the highest-value thing to state to an AI before generation (lesson 0010).

Knowledge: the rule lives where the data lives

Take the rule "you cannot withdraw more than your balance." Two ways to build it:

# way one: everyone remembers
def transfer(from_acct: Account, to_acct: Account, amount: Money) -> None:
    if amount > from_acct.balance:          # caller-enforced
        raise InsufficientFunds()
    from_acct.balance -= amount
    to_acct.balance += amount

# way two: the domain refuses
class Account:
    def __init__(self, balance: Money) -> None:
        self._balance = balance             # private: no caller can assign it

    @property
    def balance(self) -> Money:
        return self._balance                # readable, never writable

    def withdraw(self, amount: Money) -> None:
        if amount > self._balance:
            raise InsufficientFunds()       # the object itself refuses
        self._balance -= amount

    def deposit(self, amount: Money) -> None:
        self._balance += amount

def transfer(from_acct: Account, to_acct: Account, amount: Money) -> None:
    from_acct.withdraw(amount)              # no caller judgment needed
    to_acct.deposit(amount)

In the first version, the rule lives in one caller — the next caller who forgets the check creates a negative balance, silently. In the second, the rule lives in the object that owns the state; it cannot be violated by any caller, present or future, human or AI.

The privacy is not decoration. Leave balance as a public attribute and acct.balance -= amount still walks straight past withdraw — an invariant is only as strong as the widest door into the state it guards. One leading underscore and a read-only property close that door.

That's the design move: find every rule your callers "know" and move it into the object that owns the data it protects. Then invalid states become unrepresentable, and the set of bugs the system can have shrinks.

Notice what this version still does not guarantee. If deposit raises, the money has already left the first account and never arrives at the second: "no money is created or destroyed" is an invariant that spans two objects, and no single object can enforce it. Rules that cross objects need a bigger guard — an aggregate root or a transaction. That is exactly the problem lesson 0012 picks up.

How a senior designer works the case

A refund service on a six-person payments team. A customer is refunded twice for the same order; finance finds it four days later during reconciliation. The ticket says "add a check in the refund endpoint."

What they look at first. Not the endpoint. They grep for every write to the number the rule constrains — grep -rn "refunded" --include='*.py' — and count the sites:

# three paths write the same field; one of them checks the rule
def refund_endpoint(order, amount, payments):
    if amount <= order.refundable_amount():      # checked here
        payments.refund(order.order_id, amount)
        order.refunded += amount

def retry_failed_refunds(rows, orders, payments):
    for row in rows:                             # not checked here
        order = orders.get(row.order_id)
        payments.refund(order.order_id, row.amount)
        order.refunded += row.amount

def csv_import(row, order, payments):
    payments.refund(order.order_id, row.amount)  # or here
    order.refunded += row.amount

The question they ask. Not "where did it break?" but "can I enumerate every path that changes this number, and will I still be able to in a year?" Three paths today; the partner-returns webhook on next quarter's roadmap makes four. If the answer needs a grep, the rule is being observed, not enforced.

The alternative they reject. The obvious refactor is a shared validate_refund(order, amount) helper called from all three sites. It removes the duplication and it is still a hope: the fourth caller — written by someone who never read this file, or generated by an assistant that saw two of the three call sites — has no reason to call it. A helper reduces typing; only a boundary creates enforcement. The test to apply is blunt: can a competent newcomer break this rule without noticing?

class Order:
    def authorize_refund(self, amount: Money) -> Refund:
        if amount.currency != self._total.currency:
            raise CurrencyMismatch()
        if amount > self._total - self._refunded:
            raise RefundExceedsOrder(self.order_id, amount)
        self._refunded += amount              # the only writer of this field
        return Refund(self.order_id, amount)

The consequence over time. The caller-side fix closes one path, and the next incident arrives through a different one — same defect, new stack trace, another on-call night plus a finance reconciliation. The boundary fix closes the class: after it, over-refunding requires a new mutation path, and a new mutation path is visible in review as an assignment to _refunded outside Order. That is the difference worth paying for — not fewer bugs this week, but a bug family that cannot regrow silently as the team and the call sites multiply.

When this is the wrong move

Push a rule inward and you also push a decision inward. Do not do it when:

• The type is a message, not a model. DTOs, event payloads and API request objects should carry whatever the sender actually sent, including the invalid parts — you cannot report a good error about a value your parser refused to construct. Validate at the seam between the message and the domain, in one place, and keep the message type dumb.
• The rule is policy. Thresholds, limits and eligibility windows that a product manager changes are configuration with an owner and an audit trail, not constants welded into a constructor. The invariant is "a limit exists and is respected"; the number is data.
• The object cannot see the data. Uniqueness, "no more than fifty in the queue today", "the sum across all lines" — set-level rules belong to the thing that owns the set. Faking them inside a single object usually means the object secretly reaches for a repository, which is worse coupling than the check it replaced.
• You are reading, not changing. Read models, analytics rows and imported history are frequently invalid by the current rules, because they were created under older ones. Force them through today's constructors and yesterday's data becomes unloadable.

Skill: who enforces the rule?

Practice on your own code

Find a rule your codebase "knows" but doesn't enforce: a check repeated at call sites, a comment saying "must be called after X", an assert at the top of functions. Move it into the object that owns the state it protects.

In the lab: the phase-1 checkpoint gives you the returns-resolution service with its refund rule checked in one HTTP handler and ignored by the retry job and the bulk importer. Your task is to find every writer of the state, move the rule into the object that owns it, and delete the guards that are now unreachable.

# every caller remembered: "status must be DRAFT to edit"
if order.status == "draft":            # repeated in 6 places
    order.edit(lines)

# the order object now refuses:
class Order:
    def edit(self, lines: list[Line]) -> None:
        if self.status != Status.DRAFT:
            raise OrderLockedError()
        self.lines = lines

Read and watch deeper

• Domain-Driven Design, Evans — ch. 6 "The Life Cycle of a Domain Object": invariants as the reason aggregates exist.
• Architecture Patterns with Python, Percival & Gregory — ch. 1 "Domain Modeling": invariants modeled as the domain's own behavior.
• A Philosophy of Software Design, Ousterhout — ch. 10 "Define Errors Out of Existence": designing so errors can't occur, not handling them well.
• Object-Oriented Software Construction (2nd ed.), Meyer — ch. 11 "Design by Contract": the primary source for class invariants, preconditions and postconditions, and the argument that a contract is enforcement rather than documentation.
• Watch: ArjanCodes YouTube — search "domain model" for modeling examples.
• Next: lesson 0012 — value objects and aggregates, the carriers of invariants.
• Reference: Design Principles — make invalid states unrepresentable; glossary — domain invariant.

Show your agent-teacher a "must be called after X" comment and design the refusal together.

Source page: lessons/0011-domain-invariants.html

Lesson 0012 · Core Designer · Module 3

Value Objects and Aggregates

Two containers protect the domain: value objects make data trustworthy, aggregates make change trustworthy. This lesson builds both on one example.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: "use value objects and aggregates to protect integrity" — the mechanism behind lesson 0011's "make invalid states impossible."

Knowledge: the two protectors

Value object: an immutable thing whose identity is its value. Two instances with equal fields are interchangeable. Money is the classic:

@dataclass(frozen=True)
class Money:
    amount: Decimal
    currency: str

    def __post_init__(self) -> None:
        if self.amount < 0:
            raise ValueError("amount cannot be negative")
        if not self.currency.isalpha() or len(self.currency) != 3:
            raise ValueError("currency must be an ISO code")

    def __add__(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise CurrencyMismatch()
        return Money(self.amount + other.amount, self.currency)

Before: amount and currency drifted through the codebase as two unconnected numbers, each function re-validating or forgetting. After: you cannot construct a broken Money, and adding dollars to euros refuses itself. The value object killed a whole family of bugs — and it's shareable and testable because it's immutable.

Aggregate: a cluster of objects that must change together, with one root guarding the cluster's invariants. The order and its lines:

class Order:
    def __init__(self, order_id: str, customer: CustomerId, currency: str) -> None:
        self.order_id = order_id
        self.customer = customer
        self._currency = currency
        self._lines: list[OrderLine] = []
        self._status = Status.PENDING

    def add_line(self, product: ProductId, qty: int, price: Money) -> None:
        if self._status != Status.PENDING:          # invariant: only drafts change
            raise OrderLockedError()
        if price.currency != self._currency:        # invariant: one currency per order
            raise CurrencyMismatch()
        self._lines.append(OrderLine(product, qty, price))

    def total(self) -> Money:
        total = Money(Decimal("0"), self._currency)
        for line in self._lines:
            total = total + line.total()            # Money refuses a mismatch anyway
        return total

Order is the root: every change to the cluster goes through it, and it enforces the invariants from lesson 0011. Lines are edited only via the root — no one reaches into _lines to bend a rule.

Watch the two layers cooperate. Money refuses to add euros to dollars — a rule about one value. Order refuses a line in the wrong currency at the moment it is added — a rule about the cluster, caught at the door rather than three steps later inside total(). The value object makes each datum trustworthy; the aggregate makes each transition trustworthy. Neither can do the other's job.

How a senior designer works the case

The returns-resolution initiative: customers open returns against existing orders, and one rule matters to finance — a customer must never be refunded more than they paid. A modeller's instinct is to put the orders and the returns inside one Customer aggregate, where that rule is a single method away from being an enforced invariant.

What they look at first. Not the class diagram — the write pattern. How many writes per second hit one customer, how many orders does a heavy customer have, and which of these facts have to agree at commit time versus within a few seconds? For a retailer's returns flow, a given customer writes rarely, but the eligibility check reads the order, and the customer with 400 orders is exactly the one who returns things.

The question they ask. "What breaks, in business terms, if these two facts are stale relative to each other for two seconds?" If the honest answer is "a return is accepted against an order that was cancelled a second ago, and we reject it on review", that is a recoverable business event, not a corruption — so the two facts do not need one transaction.

The alternative they reject. The Customer-as-root design. It makes the refund-total rule enforceable in one place, and it costs: every return on any order locks the customer, a heavy customer loads hundreds of orders to add one line, and two teams now write to the same aggregate. Worse, on inspection the rule was never an invariant — the fraud guardrail it was protecting is a policy with thresholds a risk team tunes monthly. Enforcing policy as an invariant means a business tuning decision becomes a domain deployment.

@dataclass(frozen=True)
class OrderId:
    value: str

class Return:                                     # its own aggregate root
    def __init__(self, return_id: str, order_id: OrderId, currency: str) -> None:
        self.return_id = return_id
        self.order_id = order_id                  # reference by identity, not object
        self._currency = currency
        self._lines: list[ReturnLine] = []
        self._state = ReturnState.REQUESTED

    def add_line(self, sku: str, qty: int, refund: Money) -> None:
        if self._state is not ReturnState.REQUESTED:
            raise ReturnLockedError(self.return_id)
        if refund.currency != self._currency:
            raise CurrencyMismatch()
        self._lines.append(ReturnLine(sku, qty, refund))

    def reject(self, reason: str) -> None:        # the compensating transition
        self._state = ReturnState.REJECTED

The consequence over time. Two aggregates mean two teams can hold two locks, ship on two schedules, and reason about two state machines. The price is explicit and paid once: eligibility is checked against a snapshot at creation, the order system stays authoritative, and the race — a return raised against an order that changed underneath it — surfaces as a reject() transition you can test, count and show a customer. Compare that to the contention failure of the big aggregate, which shows up as timeouts at peak, six months later, in code nobody wants to reshape by then.

When this is the wrong move

• Bulk and analytics paths. Reconciling ten million rows through Money constructors buys validation you already have from the source system and costs an object per row. Validate at the ingest boundary; work in primitives inside the loop.
• Screens that read across boundaries. A dashboard needing customer, orders, returns and shipping is not evidence that they belong in one aggregate. It is evidence you need a read model. Growing the aggregate to serve a query is the single most common way aggregates become contention points.
• CRUD with no rules. A settings form with twelve independent fields and no invariants gains nothing from a root that guards nothing. The ceremony is real; the protection is imaginary.
• Facts you do not own. If another system is authoritative for a value, your "aggregate" is holding a replica. Model it as a cached snapshot with an age, not as state you can enforce rules on (lesson 0020).

Skill: which container, and when?

Practice on your own code

Find a pair of values that travel together as primitives (a price and currency, a start and end, a unit and rate) — promote them to a value object. Then find a cluster that must change together and give it a root that refuses invalid edits.

In the lab: the phase-1 checkpoint ships a returns service that passes an amount and a currency code as two separate arguments through four layers, and a return whose line list is appended to from outside. You promote the pair into one value object and decide, with the contention argument above, where the aggregate boundary actually belongs.

# before: temperature and unit passed separately, revalidated everywhere
def display(temp: float, unit: str) -> str: ...

# after: Temperature can't be malformed, and unit conversions live inside it
@dataclass(frozen=True)
class Temperature:
    value: float
    unit: Unit

    def in_celsius(self) -> float: ...

Read and watch deeper

• Domain-Driven Design, Evans — ch. 5 "A Model Expressed in Software" (entities vs value objects) and ch. 6 (aggregates and invariants).
• Implementing Domain-Driven Design, Vernon — ch. 6 "Value Objects" and ch. 10 "Aggregates": the practical rules of thumb.
• Architecture Patterns with Python, Percival & Gregory — ch. 1–2: value objects and aggregates in working Python.
• Vernon, "Effective Aggregate Design" (three essays, dddcommunity.org) — the primary source for the rules used above: model true invariants inside a boundary, keep aggregates small, reference other aggregates by identity, and update one aggregate per transaction with eventual consistency between them.
• Watch: ArjanCodes YouTube — search "value objects" or "aggregate".
• Reference: Glossary — value object, entity, aggregate.

Bring a borderline case — entity or value object? — to your agent-teacher and argue both sides.

Source page: lessons/0012-value-objects-and-aggregates.html

Lesson 0013 · Core Designer · Module 3

Repository Boundaries That Don't Leak

A repository is a collection, from the domain's point of view. When it starts showing its storage internals, the domain stops being protected.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the repository is the port from lessons 0009 and 0010, specialized for storage. It's also the boundary your AI prompts should name explicitly.

Knowledge: a collection, not a query API

The repository's job: let the domain load and save aggregates as if they lived in a collection. The domain never learns about SQL, sessions, or ORMs. The port speaks domain language:

class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...
    def add(self, order: Order) -> None: ...
    def delete(self, order_id: str) -> None: ...


class SqlAlchemyOrderRepository:
    def __init__(self, session: Session) -> None:
        self._session = session

    def get(self, order_id: str) -> Order:
        row = self._session.execute(
            select(OrderRow).where(OrderRow.id == order_id)
        ).scalar_one()
        return Order(...)                # row -> domain aggregate

    def add(self, order: Order) -> None:
        self._session.add(OrderRow.from_domain(order))

The boundary's proof is the fake — a drop-in replacement with no storage at all:

class InMemoryOrderRepository:               # implements the same port
    def __init__(self) -> None:
        self._orders: dict[str, Order] = {}

    def get(self, order_id: str) -> Order:
        try:
            return self._orders[order_id]
        except KeyError:
            raise OrderNotFound(order_id)    # the port's vocabulary, not the ORM's

    def add(self, order: Order) -> None:
        self._orders[order.order_id] = order

Twelve lines, no database, and every domain test runs against it in milliseconds. That is also the diagnostic: if your fake cannot be written in a dozen lines, the port is carrying storage semantics it should not — lazy loading, session lifetimes, flush ordering. Note the error too: the fake raises OrderNotFound, not KeyError and not the ORM's NoResultFound. The port owns its failure vocabulary as much as its methods.

What makes this boundary honest is what it refuses:

• No session, query, or ORM types appear in the port or in domain callers.
• Queries are expressed as domain questions: get_unshipped(), not filter(status=...) with raw column names.
• The domain gets domain objects back — never rows, dicts, or ORM models.
• Persistence details — transactions, lazy loading, caching — live behind the boundary.

Test it the lesson-0009 way: a fake in-memory repository must be a drop-in, and the domain must never know which one it holds. If your fake has to mimic ORM behavior, the boundary leaked.

How a senior designer works the case

An order service: eight engineers, twenty-five endpoints, a repository boundary everyone is proud of. After one sprint, the order-list page's p95 goes from 180 ms to 1.4 s. The ticket says "the repository is slow."

What they look at first. Not the SQL, and not the adapter. The call site, next to the port's signature:

# the port looks immaculate
class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...

# the caller wrote the loop the port invited
def order_list(order_ids: list[str], repo: OrderRepository) -> list[OrderSummary]:
    return [summarize(repo.get(oid)) for oid in order_ids]   # 50 round trips

The question they ask. "Which side of this boundary decides how many round trips happen?" Here, neither did on purpose: the caller wrote an innocent comprehension, the port had no way to express "fifty at once", and the fake — which returns from a dict — made the loop look free in every test. That is the diagnosis. The port hid cost, and the fake made the hiding invisible.

The alternatives they reject. The quick fix is get_many(ids), then get_with_lines(ids) for the next screen, then get_with_lines_and_shipping(ids). Each is reasonable alone; together they grow one method per screen, so a write-model interface slowly becomes a read API with nineteen methods, six of them used once, all of which the fake and every implementation must support forever. The other tempting fix — switching the ORM to eager loading globally — repairs this page and pessimizes every write path, and makes the port's behaviour depend on a configuration line in a different file.

What they choose, and what it costs. Split the two jobs the boundary was doing. The repository stays narrow and aggregate-shaped for the write side: load one thing by identity, change it, save it. A separate read side — a query service — is allowed to know SQL, because reading is a query:

@dataclass(frozen=True)
class OrderSummary:                # a read model, not a domain aggregate
    order_id: str
    customer_name: str
    line_count: int
    total_cents: int

class OrderQueries(Protocol):      # a separate port, read-only
    def recent_summaries(self, limit: int) -> list[OrderSummary]: ...

The consequence over time. Two boundaries with different rules is more code than one, and the honest cost is a second mapping path that can drift from the first. What it buys is that neither side has to lie: the domain keeps its twelve-line fake and its microsecond tests, the list page gets one statement instead of fifty, and the next screen adds a read model instead of another method to an interface eleven classes implement. The failure mode you avoid is the one that kills repositories in practice — a port that grows until nobody can implement it and everybody routes around it.

When this is the wrong move

• Reporting, search and analytics. Go to the engine directly, with a read model. A repository between a dashboard and a warehouse query buys nothing and costs expressiveness.
• Set-based work. "Expire the 40,000 sessions older than a day" is one statement in SQL and a disaster as a loop over a collection. Put it behind a named domain operation, and let the adapter do it in one round trip.
• Small applications where the ORM model is the model. One team, one storage, CRUD rules, no plans to swap: the port is ceremony, and the honest design is to admit the framework is the architecture. Say so in an ADR so the next person knows it was a decision.
• Spikes. A boundary you introduce before you know the domain's questions will be a boundary shaped by your first guess. Write the ugly version, learn the queries, then draw the line.

Skill: what crosses the boundary?

Practice on your own code

Look at how your code fetches and saves domain objects. Grep the domain folder for your ORM's import. If it appears — or if the boundary doesn't exist yet — introduce a repository port with domain-named methods and move the ORM behind it.

In the lab: the phase-1 checkpoint has a returns store that hands ORM rows and a live session back to the service layer, and a list endpoint that loops one lookup per return. You give the port a domain vocabulary, write the in-memory fake, and decide which of the remaining calls belongs on a read side instead.

Read and watch deeper

• Architecture Patterns with Python, Percival & Gregory — ch. 2 "The Repository Pattern": the clearest working treatment, with the fake-repository test.
• Implementing Domain-Driven Design, Vernon — ch. 12 "Repositories": design rules for repository interfaces.
• Domain-Driven Design, Evans — ch. 6: the original repository concept, and why it exists.
• Patterns of Enterprise Application Architecture, Fowler — the Repository entry in the object-relational metadata mapping patterns: the original catalog definition, and the Query Object it is usually paired with.
• Fowler, "CQRS" — the argument for letting the read side and the write side have different models, with an explicit warning about when the split is not worth it.
• Watch: ArjanCodes YouTube — search "repository pattern".
• Reference: Patterns — Repository and Unit of work, the transaction boundary the repository sits inside.

Show your agent-teacher your data-access code and audit the boundary together — grep included.

Source page: lessons/0013-repository-boundaries.html

Lesson 0014 · Core Designer · Module 3

Fail-Fast at the Right Boundaries

The question is never "should we fail?" — it's where. Fail early, at the boundary, loudly, and the error arrives with its address attached.

Reading ≈ 9 minPractice ≈ 25 min

Mission tie-in: fail-fast completes the Core Designer phase — it's how the domain core protects itself from the messy world around it.

Knowledge: fail where the cause lives

A bad value that travels is a bomb with a delayed fuse: it's written here, read there, and explodes in a third place, hours later, in unrelated code. Fail-fast means the bomb detonates at the moment and place of the cause, where the fix is obvious.

Three boundaries deserve loud failures:

1. The input boundary — data enters the system. Validate and refuse before work starts:

def schedule_meeting(request: MeetingRequest) -> Meeting:
    if request.end <= request.start:
        raise InvalidMeetingRequest("end must be after start")
    ...

2. The invariant boundary — domain rules (lesson 0011) refuse invalid transitions, whoever is asking:

class Meeting:
    def cancel(self, reason: str) -> None:
        if self._status is Status.CANCELLED:
            raise AlreadyCancelled(self.meeting_id)   # not a silent no-op
        self._status = Status.CANCELLED

The tempting alternative — returning quietly when the meeting is already cancelled — hides a real bug: something in the system believes it is cancelling a live meeting. Silence turns that into a mystery three days later; the exception turns it into a stack trace now.

3. The integration boundary — the outside world fails; errors surface as errors, not as None:

def process_batch(orders: list[Order], gateway: PaymentGateway) -> BatchResult:
    results = []
    for order in orders:
        try:
            charge_id = gateway.charge(order.total, order.token)
        except PaymentError as e:
            results.append(FailedOrder(order.order_id, str(e)))   # loud, per item
            continue
        results.append(PaidOrder(order.order_id, charge_id))
    return BatchResult(results)

Notice the shape: each failure is caught at the boundary where it can be handled (per-order), recorded loudly, and reported — versus lesson 0005's AI version that swallowed everything and returned early. The difference between "fail-fast" and "fragile": the first fails loudly at the right boundary; the second fails silently at the wrong one.

How a senior designer works the case

A payments API, forty pods, a rolling deploy at 02:00. Startup validates the whole config file strictly and refuses anything it does not recognise — a rule the team adopted after a missing signing key was silently defaulted to empty. Tonight someone ships a typo in an optional feature flag. Every replacement pod fails to boot, the rollout drains the healthy ones, and a service that could have answered every request is down for nineteen minutes.

What they look at first. Not the typo. The question of what the failing check was protecting, and what it took down. Strictness here was not wrong in kind; it was applied at one granularity to two kinds of configuration with opposite risk profiles.

The question they ask. "Does failing here prevent harm, or cause it?" A missing signing key means every subsequent request is processed unverified — failing prevents harm, and must happen before the pod takes traffic. An unparseable flag for a UI experiment means one feature stays off — failing causes harm, and nothing else.

The alternative they reject. The reflex fix, wrapping the config load in try/except and defaulting everything, restores availability by deleting the distinction. It also silently reinstates the original incident: the missing signing key becomes "signature verification disabled", discovered by an auditor rather than by a crash. Trading a nineteen-minute outage for an unbounded security failure is not a trade a senior takes.

REQUIRED = ("database_url", "signing_key", "gateway_url")

def load_config(raw: dict) -> Config:
    missing = [key for key in REQUIRED if not raw.get(key)]
    if missing:                                   # cannot serve correctly: refuse before traffic
        raise ConfigError("cannot start without: " + ", ".join(missing))

    flags, rejected = parse_flags(raw.get("feature_flags", {}))
    for key, problem in rejected:                 # optional: degrade, but countably
        log.error("ignoring feature flag %s: %s", key, problem)
        metrics.config_degraded.labels(key=key).inc()

    return Config(raw, flags=flags, degraded=tuple(key for key, _ in rejected))

The consequence over time. The line between "cannot serve" and "nice to have" is now a list in the source, so adding a required key is a visible diff someone argues about, rather than an accident of which parser ran first. Tonight's typo becomes one ERROR line and a tick on a gauge. The subtler win is that the degraded state is observable: a pod running without an optional feature is now distinguishable from a pod running correctly, which is the property blanket try/except destroys and the reason it keeps producing incidents that take days to attribute.

When this is the wrong move

• Best-effort features. Recommendations, enrichment, avatars, telemetry. A failure here should shrink the response, not replace it. Return the page without the panel and count the omission.
• Streaming ingest. One malformed record must not stop the stream. Dead-letter it with enough context to replay, and alert on the dead-letter rate rather than on the record.
• Startup dependencies that are merely late. Crashing because the database is not up yet is reasonable under an orchestrator that restarts you; crashing because it was slow for four seconds at 03:00 is a self-inflicted outage. Bounded retry with a deadline, then fail.
• Anywhere the failure costs more than the wrong answer. Name that judgment explicitly, in the code, next to the fallback — the next reader needs to know it was chosen rather than forgotten.

Skill: which boundary fails how?

Practice on your own code

Find a silent failure in your code: a swallowed exception, a return None hiding an error, an early return abandoning work. Decide the correct boundary, make the failure loud, and (if useful) add the per-item handling pattern.

In the lab: the phase-1 checkpoint contains a returns pipeline whose gateway call is wrapped in a bare except Exception that returns an empty result, so a failed refund is indistinguishable from a return with nothing to refund. You decide which boundary owns the failure and make the difference visible in the value that comes back.

# before: silent
def load_config(path):
    try:
        return yaml.safe_load(open(path))
    except Exception:
        return {}

# after: loud at the input boundary
def load_config(path: Path) -> dict:
    return yaml.safe_load(path.read_text())   # errors propagate with their cause

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 10 "Define Errors Out of Existence": fail-fast's philosophical home.
• Clean Code, Martin — ch. 7 "Error Handling": why swallowed errors are structural defects.
• Release It!, Nygard — the stability patterns: where loud, early failure protects the whole system.
• Shore, "Fail Fast" (IEEE Software, 2004) — the short primary source that named the practice, including its warning that fail-fast is about making bugs visible, not about crashing more.
• Watch: ArjanCodes YouTube — search "error handling" or "exceptions".
• Next phase: lesson 0015, System Designer.
• Reference: Design Principles — fail fast and its counterpart, define errors out of existence.

Bring a swallowed-error site to your agent-teacher and decide the correct boundary together.

Source page: lessons/0014-fail-fast-error-handling.html

Lesson 0015 · System Designer · Module 1

Classes vs Functions

Not everything needs a class. The decision is not style — it's about what has to change: stateless behavior belongs in functions; state and polymorphism belong in classes.

Reading ≈ 8 minPractice ≈ 20 min

Mission tie-in: "decide when to use classes and when simple functions are enough" is the first System Designer skill — the one AI gets wrong in both directions.

Knowledge: the two habitats

Functions are the natural home for behavior without state: a transformation from input to output, no history, no configuration of its own. Pure functions — same input, same output, no side effects — are the most composable, testable units software has.

def sanitize(word: str) -> str:
    return word.strip(".,!?").lower()

def words(text: str) -> list[str]:
    return [sanitize(w) for w in text.split()]

def word_frequencies(words: list[str]) -> Counter[str]:
    return Counter(words)

# three stateless steps compose into a pipeline with no ceremony:
freqs = word_frequencies(words(raw_text))

Classes earn their keep when there is state to own (something that must stay consistent across calls) or polymorphism (several behaviors behind one interface — lesson 0004's strategy). A class with no state and one method is usually a function wearing a costume:

class TextStats:                      # stateless costume
    def compute(self, text: str) -> Counter[str]:
        return Counter(text.lower().split())

# the function version is the same thing with less ceremony:
def compute_text_stats(text: str) -> Counter[str]:
    return Counter(text.lower().split())

The test is a change question, not a religion: what will vary here? A new behavior variant → a protocol + implementations (classes earn it). New arguments to a transformation → a function with parameters (functions earn it). Lifetime and consistency across calls → state, and a class owns it.

How a senior designer works the case

Two classes surface in the same review, and by the folk rule they are identical: one method, no mutable state.

class Slugifier:                                  # candidate A
    def make(self, title: str) -> str:
        return "-".join(title.lower().split())

class ReturnLabelPrinter:                         # candidate B
    def __init__(self, carrier: CarrierClient, retries: RetryPolicy) -> None:
        self._carrier = carrier
        self._retries = retries

    def print_label(self, ret: Return) -> Label:
        return self._retries.run(lambda: self._carrier.create_label(ret))

What they look at first. Not the method count — the constructor. Candidate A's is empty: nothing is bound, nothing has a lifetime, and the only thing the class contributes is a noun the caller must import before it can call a function. Candidate B binds two collaborators that were chosen elsewhere, and one of them holds a connection pool.

The question they ask. Not "does it have state?" but "does it have a lifetime, and is it a substitution point?" Candidate B is swapped for a fake in tests, for a sandbox client in staging, and for a second carrier when the contract changes — and its lifetime matters, because creating the client per call would open a connection per label.

The alternative they reject. Converting B to a free function print_label(ret, carrier, retries). It reads cleaner in isolation and moves the binding problem to the callers: five call sites today, and the fourteen a year from now each have to obtain a carrier client and a retry policy they do not care about. That is change amplification bought with tidiness. Reaching for functools.partial to fix it recovers the class with a worse name — an object with no type name in a stack trace, no place to hang a second method, and a repr that tells an on-call engineer nothing.

The consequence over time. A converts to a function and one import disappears from six modules. B stays a class and, eighteen months later, absorbs a second method (void_label) and a metric counter without a single call site changing — because the seam already had a name. The rule survives, but its real content turns out to be "pay for a class when you need a lifetime, a seam, or a family", and "no state" is only the most common symptom of not needing any of the three.

When this is the wrong move

• When the framework wants a class. ORM models, serializers, view classes and plugin base classes are the ecosystem's interface. Fighting them to satisfy a habitat rule costs you every convention and every piece of tooling built on top.
• When a function has grown six parameters that always travel together. The answer is a class with no methods at all — a parameter object or a value object. Splitting it back into free arguments is the anti-pattern this lesson is sometimes misread as recommending.
• When you need one seam and the alternative is threading collaborators. As above: the class is cheaper than the plumbing.
• In numeric or per-item hot paths. Attribute lookups and object construction per element are measurable in tight loops. Rare, but real — and worth a benchmark rather than an opinion.

Skill: name the habitat

Practice on your own code

Find a class with no state (no self. assignments in __init__ that vary) and convert it to a function. Then find one place where a function keeps gaining conditional branches and sketch the protocol that would house them.

In the lab: the phase-2 checkpoint has a returns codebase containing both shapes — a ReturnValidator whose methods never read self, and a handful of free functions that pass the same three collaborators to each other. You move each one to the habitat that fits and justify the two decisions differently.

# before
class Slugifier:
    def make(self, title: str) -> str:
        return "-".join(title.lower().split())

# after — same behavior, no costume
def make_slug(title: str) -> str:
    return "-".join(title.lower().split())

Read and watch deeper

• Python docs — Functional Programming HOWTO: pure functions and composition, the function habitat in depth.
• A Philosophy of Software Design, Ousterhout — ch. 4 "Modules Should Be Deep": a well-named function is a module; a class is one module shape among several.
• Fluent Python, Ramalho — ch. 7 (functions as objects): what Python functions can do that classes can't, and vice versa.
• Python docs — dataclasses reference: the standard way to build the parameter objects and value objects that this decision keeps producing.
• Diederich, "Stop Writing Classes" (PyCon US 2012) — the canonical talk against the one-method class. Watch it against this lesson's counter-case, where the constructor, not the method, is the reason to keep it.
• Watch: ArjanCodes YouTube — search "the mighty function".
• Reference: Glossary — deep module, higher-order function.

Bring a borderline class to your agent-teacher and run the habitat test together.

Source page: lessons/0015-classes-vs-functions.html

Lesson 0016 · System Designer · Module 1

Injecting Behavior: Strategies and Higher-Order Functions

Lesson 0004 extracted the Strategy as classes. Python's cheaper version: pass the behavior itself. Functions are strategies too — and often the better ones.

Reading ≈ 8 minPractice ≈ 25 min

Mission tie-in: "inject behavior using strategies and higher-order functions" — the System Designer's move for making code evolve without rewrites.

Knowledge: behavior as an argument

A strategy is just a unit of behavior chosen at runtime. In Python, a callable is the cheapest possible strategy interface — no protocol, no class, no ceremony:

from collections.abc import Callable

Discount = Callable[[Money], Money]             # strategy: total -> amount off

def percentage(rate: Decimal) -> Discount:      # factory: makes a strategy
    def apply(total: Money) -> Money:
        return total * rate
    return apply

def over_threshold(minimum: Money, then: Discount) -> Discount:
    def apply(total: Money) -> Money:
        return then(total) if total >= minimum else Money(Decimal("0"), total.currency)
    return apply

def final_price(total: Money, discount: Discount) -> Money:
    return total - discount(total)

# 10% off, but only on orders of 100 EUR or more:
policy = over_threshold(Money(Decimal("100"), "EUR"), percentage(Decimal("0.10")))

final_price never changes when pricing policy changes — new policies are new functions, passed in. That's the strategy pattern with the interface made implicit.

Higher-order functions — functions that take or return functions — give you composition for free:

def capped(discount: Discount, maximum: Money) -> Discount:   # wraps a strategy
    def apply(total: Money) -> Money:
        return min(discount(total), maximum)
    return apply

# 10% off, only over 100 EUR, never more than 20 EUR off:
policy = capped(
    over_threshold(Money(Decimal("100"), "EUR"), percentage(Decimal("0.10"))),
    maximum=Money(Decimal("20"), "EUR"),
)

Read what just happened: over_threshold and capped take a strategy and return a strategy. Each new rule is a small function, and business policy becomes an expression you can read top to bottom. The class version of this needs a decorator class per rule and an interface they all implement — the same design, three times the ceremony.

When should the strategy be a class instead? When it carries state (lesson 0015) or must participate in polymorphism with a nameable interface (lesson 0017). A stateless one-method strategy is a function's job.

How a senior designer works the case

A retailer's pricing service, injected discount callables, no branch chain anywhere — textbook. Then a customer receives a promotion twice. Support cannot reproduce it; the order log contains one line: discount_applied=12.40. Three engineers spend a day reconstructing which policies were in the list, in what order, for that customer, on that day.

What they look at first. Not the stacking logic. The log line — because the design question here is not "is this extensible?" (it plainly is) but "when this misbehaves at 02:00, what will the on-call engineer be able to see?" The refactor that removed the branch also removed the only place a name existed.

The alternative they reject. Someone proposes moving pricing rules into a YAML rules engine so marketing can change them without a deploy. It is the same instinct — push variation outward — taken one step too far: it produces a second programming language with no type checker, no debugger, no tests and no code review, and it converts the 02:00 problem from "read three Python functions" into "debug an interpreter we wrote ourselves". (Lesson 0029 is the longer argument.) Rejected — but the impulse behind it is right: the rules did need identity.

What they choose. Keep the injected callables; give each one a name, and make the applied names part of the result rather than a log statement:

@dataclass(frozen=True)
class Policy:
    name: str
    apply: Discount                      # Callable[[Money], Money]

def percentage(rate: Decimal) -> Policy:
    def apply(total: Money) -> Money:
        return total * rate
    return Policy(f"percentage:{rate}", apply)

def final_price(total: Money, policies: Sequence[Policy]) -> PricedTotal:
    off = Money(Decimal("0"), total.currency)
    applied: list[str] = []
    for policy in policies:
        amount = policy.apply(total)
        if amount.amount:
            off = off + amount
            applied.append(policy.name)  # the receipt travels with the price
    return PricedTotal(total - off, tuple(applied))

The consequence over time. The next stacking incident is a grep, not an investigation: the order stores ("percentage:0.10", "percentage:0.10") and the duplicate is visible in the data. Finance's quarterly "why did this order get 22% off" is answerable without a code reading. The cost is real and small — a name per policy, and a team rule that lambdas are not allowed at this seam — and it buys back exactly the property injection took away. That is the general shape of the move: when you push a decision outward, push its identity outward with it, or you will pay for the flexibility in incident time.

When this is the wrong move

• One variant, stable for years. Write the branch. A seam with a single implementation is an abstraction with no information in it, and readers pay for the indirection on every visit.
• When the choice arrives as data. If a database row or a queue message names the behaviour, you need a registry of names anyway — so start there rather than passing anonymous callables that no message can refer to.
• When the behaviour must be stored, scheduled or sent. You cannot put a closure in a queue, a database or a retry table. Persist the name and its parameters; resolve to a callable at the edge.
• When the seam becomes a public extension point. Then it is an API with a support obligation and a deprecation policy, and the cheap version — "just pass a function" — is the expensive version in disguise.

Skill: callable or class?

Practice on your own code

Find a function with a flag or a type field that selects behavior (a control-coupling smell from the coupling ladder). Replace the flag with an injected callable, and move the selection to the caller.

In the lab: the phase-2 checkpoint gives you a returns-resolution routine steered by two boolean parameters and a mode string, and asks you to replace them with injected, named behaviour — then to show, from the recorded result alone, which path a given return actually took.

# before: control coupling — the flag steers behavior
def send_report(data, urgent: bool) -> None:
    if urgent:
        channel = pager()
    else:
        channel = email()
    channel.deliver(data)

# after: the behavior is injected; no flag, no branch
def send_report(data, channel: Channel) -> None:
    channel.deliver(data)

send_report(data, pager())     # or email() — the caller decides

Read and watch deeper

• Fluent Python, Ramalho — ch. 7: higher-order functions, closures, and functools.partial as behavior injection.
• Python docs — functools reference: the standard toolkit for binding behavior without classes.
• Head First Design Patterns, Freeman et al. — ch. 1: the strategy intent, re-read now that you know the lighter-weight variant.
• Norvig, "Design Patterns in Dynamic Languages" — the primary source for why several classic patterns, Strategy among them, shrink to a function or become invisible in a language with first-class functions.
• Watch: ArjanCodes YouTube — search "higher order functions".
• Next: lesson 0017 — naming the extension point when you need one.

Convert a flag-parameter function with your agent-teacher and compare the injected-callable design.

Source page: lessons/0016-injecting-behavior.html

Lesson 0017 · System Designer · Module 1

Protocols and ABCs: Clean Extension Points

An extension point is a promise: "anything with these methods works here." Protocols make the promise structural; ABCs make it nominal. Choose by who's making the promise.

Reading ≈ 8 minPractice ≈ 25 min

Mission tie-in: "use protocols and abstract base classes to design clean extension points" — how the System Designer opens a module for extension without weakening its core.

Knowledge: two ways to promise

Protocol — structural typing: an object qualifies by having the methods, whether or not it ever heard of your interface. The extension point is open to anything that walks like the duck:

from typing import Protocol, runtime_checkable

@runtime_checkable
class Notifier(Protocol):
    def send(self, message: str, recipient: str) -> None: ...

def notify_all(notifier: Notifier, users: list[User]) -> None:
    for user in users:
        notifier.send(f"Update for {user.name}", user.email)

ABC — nominal typing: an object qualifies by declaring itself a subclass, and the base can provide default behavior and enforce method presence:

from abc import ABC, abstractmethod

class Notifier(ABC):
    @abstractmethod
    def send(self, message: str, recipient: str) -> None: ...

    def send_bulk(self, messages: list[str], recipient: str) -> None:  # shared behavior
        for m in messages:
            self.send(m, recipient)

How to choose:

• Protocol, when the module must accept things it doesn't own — third-party objects, framework callbacks, your own legacy code. The promise is "if you have these methods, you're in."
• ABC, when you own the family and want shared default behavior, enforced structure, or a place where the extension contract is discovered by subclassing.

Either way, the extension point should be deep (lesson 0001's reading): a small, stable promise that hides how much work it enables. If the interface is bigger than the implementation, it's not an extension point — it's a leak.

How a senior designer works the case

A nine-method Notifier ABC lives in a shared/interfaces package imported by eight services owned by four teams. A new requirement needs a tenth method. The proposed change adds it to the base class.

What they look at first. Not the method. The package the interface lives in, and the list of things that import it — because that list is the blast radius of every future change to this promise. Then the usage: each service calls two or three of the nine methods, and every implementation stubs the rest.

The question they ask. "Who owns this interface — the callers or the implementations?" An interface owned by the implementations is a contract you must negotiate; one owned by a caller is a description of what that caller happens to need, and it can be changed by the person changing the caller.

The alternative they reject. Versioning the shared package, so teams can adopt shared-interfaces 2.x on their own schedule. It works, and it makes the coupling official: every interface change now needs a migration plan across four teams' release trains, and the nine-method promise — which no implementation ever needed in full — is preserved forever because removing anything is a breaking change.

# declared in the module that USES it, naming only what it calls
class SendsAlerts(Protocol):
    def send(self, message: str, recipient: str) -> None: ...

class EscalationPolicy:
    def __init__(self, alerts: SendsAlerts) -> None:
        self._alerts = alerts                 # SlackClient imports nothing of ours

def check_sends_alerts(candidate: SendsAlerts, recorder: Recorder) -> None:
    candidate.send("ping", "ops@example.com")      # one contract test, parameterised
    assert recorder.last_call == ("ping", "ops@example.com")   # over every adapter

The consequence over time. The nine-method interface dissolves into three small ones, each sitting next to its consumer. Adding a method to the Slack client breaks nobody. The shared package stops being a place where four teams negotiate promises and becomes what it was good at — shared implementations. The honest cost: the same client now satisfies three protocols and no single file says so, so a change to it can break a consumer it never heard of. That is what the contract test is for, and it is the trade a senior takes knowingly — decentralised promises plus tests that catch drift, over one central promise that everyone has to schedule around.

When this is the wrong move

• You are publishing a plugin API to people you do not know. A nominal base class gives plugin authors a discoverable contract, a place for defaults, and somewhere to put deprecation shims. Structural typing gives them nothing to read and no signal when the shape changes.
• Your CI does not run a type checker. Then a Protocol enforces literally nothing. Either add the checker — the cheaper fix — or use an ABC, which at least fails at instantiation.
• The variants genuinely share a step. A template method in a base class is the only place that step can live exactly once. Protocols cannot carry behaviour.
• You need runtime dispatch on type. Registries keyed by class, singledispatch and ABCMeta.register exist for this, and structural checks are the wrong tool.

Skill: which promise fits?

Practice on your own code

Find an ABC in your codebase (or an AI-generated one). Ask: do the subclasses share default behavior, or do they each implement everything? If the ABC is just a contract with no shared behavior and no external subclasses, convert it to a Protocol.

In the lab: the phase-2 checkpoint ships a returns codebase with one wide abstract base class that every adapter inherits and only partly implements. You narrow it to the methods each consumer actually calls, decide per seam whether a protocol or a base class fits, and add the contract test that neither mechanism gives you.

# an AI wrote this: a contract with zero shared behavior
class Exporter(ABC):
    @abstractmethod
    def export(self, data) -> str: ...

# every subclass implemented export() fully; nothing shared; nothing external
# convert to a protocol — same contract, open to anything with export()
class Exporter(Protocol):
    def export(self, data) -> str: ...

Read and watch deeper

• Fluent Python, Ramalho — ch. 13 "Protocols and ABCs": the definitive Python treatment of the choice.
• Python docs — typing.Protocol: the structural-typing reference.
• A Philosophy of Software Design, Ousterhout — ch. 4: deep modules as the shape of good interfaces.
• PEP 544 — Protocols: Structural subtyping and PEP 3119 — Introducing Abstract Base Classes: the two primary sources, each with the rationale and the explicit limits of what it checks.
• Watch: ArjanCodes YouTube — search "protocol or abstract base class".
• Reference: Glossary — protocol; and Design Principles — open–closed, the principle an extension point serves.

Show your agent-teacher an AI-generated ABC and argue the protocol conversion together.

Source page: lessons/0017-protocols-and-abc.html

Lesson 0018 · System Designer · Module 1

Memory-Efficient Pipelines with Generators

Processing a terabyte of logs doesn't require a terabyte of RAM. Generators turn "load everything, then process" into "process as it flows" — with the same readable shape.

Reading ≈ 8 minPractice ≈ 25 min

Mission tie-in: "build memory-efficient data pipelines with generators and streaming" — the composability skill that keeps large-data code honest and small.

Knowledge: lazy stages, chained

A generator produces values one at a time, on demand. Chain generators and each stage processes a single item as it flows past — memory stays flat no matter how much data streams through:

def read_lines(path: str):
    with open(path) as f:
        for line in f:                # the file itself streams
            yield line

def parse(line: str) -> LogEntry:
    ...

def error_entries(lines):
    for line in lines:
        entry = parse(line)
        if entry.level == "ERROR":
            yield entry

def summarize(entries) -> Counter[str]:
    counts = Counter()
    for entry in entries:
        counts[entry.service] += 1
    return counts

total = summarize(error_entries(read_lines("app.log")))

At any moment, exactly one line is in memory: the file streams, each stage transforms one item, the counter aggregates. The pipeline reads like a sentence — summarize(error_entries(read_lines(...))) — and each stage is independently testable.

The contrast is the list-based version: read all lines into a list, build a filtered list, build a parsed list… each intermediate list is the whole dataset again. That's the memory failure mode of naive code — and of AI code, which defaults to lists.

How a senior designer works the case

An export endpoint in a long-running web worker. The pipeline is the textbook one above: read_lines opens the file and yields inside the with. A preview feature wraps it in islice(stream, 100). Two weeks later, the box serving the most previews dies with OSError: too many open files.

What they look at first. Not the memory profile — the with statement's position relative to the yield:

def read_lines(path: str):
    with open(path) as f:          # the context manager's exit is inside the generator
        for line in f:
            yield line             # abandoned here, the file stays open

The question they ask. "Who owns this resource, and at what moment does it close?" The answer is uncomfortable: it closes when the generator is exhausted, or when the generator object is collected and CPython throws GeneratorExit into the suspended frame. Refcounting usually makes that prompt — and "usually" is not a design. Hold a reference in a cache, a partially consumed result, or an exception traceback, and the descriptor lives as long as the reference does.

The alternative they reject. Going back to return f.readlines(). It restores deterministic cleanup and reinstates the original problem: this endpoint exports files of several gigabytes, which is why the pipeline was written lazily in the first place. Trading a descriptor leak for an out-of-memory kill is not progress.

def parse_lines(lines: Iterable[str]) -> Iterator[LogEntry]:
    for line in lines:             # owns no resource; owns no lifetime
        yield parse(line)

def export(path: str) -> Response:
    with open(path) as f:          # the request owns the file, and closes it
        return stream_response(parse_lines(f))

The second half of the same case. The fixed pipeline writes its results to Postgres, one row at a time, because streaming is the habit now. Two million rows at half a millisecond per round trip is roughly seventeen minutes of network latency doing nothing else. The fix is the other half of the rule — stream between stages, batch at the sink:

def batched(iterable, size):                    # itertools.batched, on Python 3.12+
    iterator = iter(iterable)
    while chunk := list(islice(iterator, size)):
        yield chunk

for chunk in batched(entries, 1000):            # flat memory, 2,000 round trips
    db.insert_many(chunk)

The consequence over time. Both fixes are small, and both come from the same idea rather than from generator trivia: laziness moves ownership to the consumer, so decide deliberately what the consumer owns. Teams that skip this end up with the two classic outcomes — a service that leaks descriptors under partial consumption, and a nightly job that is memory-perfect and four hours long.

When this is the wrong move

• Small, fixed collections. A list you can print, index, and see in a debugger is worth more than flat memory you did not need.
• Multi-pass work. Sorting, joining, or any statistic that needs a second look at the data. Materialise deliberately and say why in a comment.
• Vectorized numeric code. NumPy, pandas and polars are fast because they operate on whole arrays; per-element Python iteration is the slow path you are trying to avoid.
• When diagnosis matters more than memory. Deferred execution scatters stack traces across modules. On a critical path that fails rarely and expensively, an eager version that fails at the call site can be the better engineering.

Skill: list or stream?

Practice on your own code

Find a function that builds a list, transforms it into another list, then another (three or more materializations). Convert it to chained generator stages with an iterable contract, and measure the peak memory if you can.

In the lab: the phase-2 checkpoint has a returns export that builds three full lists in a row and then writes rows one at a time. You convert the middle to streaming stages, batch the write, and decide where the file handle should be opened once you have.

# before: three full copies of the dataset
rows = fetch_all_rows()
filtered = [r for r in rows if r.active]
parsed = [parse(r) for r in filtered]
total = sum(r.amount for r in parsed)

# after: one pass, flat memory
def active(rows):
    for r in rows:
        if r.active:
            yield r

total = sum(parse(r).amount for r in active(fetch_rows_stream()))

Read and watch deeper

• Fluent Python, Ramalho — ch. 17 "Iterators, Generators, and Classic Coroutines": generator fundamentals and pipeline composition.
• Python docs — itertools reference: the streaming toolbox; and the Functional Programming HOWTO.
• Effective Python, Slatkin — the items on generators: when lazy evaluation wins and when it doesn't.
• PEP 255 — Simple Generators: the primary source, including why a generator's frame is suspended rather than copied, which is the mechanism behind every ownership question above.
• Watch: ArjanCodes YouTube — search "generators python".
• Next module: lesson 0019, managing complexity in growing applications.
• Reference: Patterns — generator pipeline, with the iterable-in/items-out contract.

Bring a list-chained function to your agent-teacher and convert it to a stream together.

Source page: lessons/0018-generators-and-streaming.html

Lesson 0019 · System Designer · Module 2

Identifying and Reducing Global Coupling

A module-level mutable value is a phone line to every file in the project. Global coupling is the quietest way a codebase learns to depend on call order.

Reading ≈ 8 minPractice ≈ 30 min

Mission tie-in: "identify and reduce global coupling" — the System Designer's first complexity leak, and the one AI code most reliably introduces with caches and singletons.

Knowledge: the hidden phone line

Global state is any state reachable from anywhere: a module-level mutable container, a singleton, a cache, a registry. The coupling it creates is invisible — no import declares it, but every consumer shares it:

# config.py
_settings: dict = {}          # module-level mutable state

def set_setting(key: str, value) -> None:
    _settings[key] = value

def get_setting(key: str):
    return _settings.get(key)

# service_a.py
import config
config.set_setting("rate_limit", 10)     # runs at import time

# service_b.py
import config
limit = config.get_setting("rate_limit")  # 10 — only if service_a imported first

The bug is in the wiring, not the values: service_b's behavior depends on service_a having run first. Import order, test order, and deployment order all become part of your program's semantics. Change a test file and the behavior changes — with no diff pointing at the cause.

The fix is to make the dependency explicit — pass it, own it, inject it:

class RateLimiter:
    def __init__(self, limit: int) -> None:
        self._limit = limit
        self._used = 0

    def allow(self) -> bool:
        if self._used >= self._limit:
            return False
        self._used += 1
        return True

# wiring happens once, visibly, at the composition root:
limiter = RateLimiter(limit=10)
service_b = ServiceB(limiter=limiter)

Now the dependency appears in the constructor — reviewable, mockable, and ordered by whoever builds the system, not by import order.

How a senior designer works the case

A twenty-person team, a fourteen-minute pipeline, and three tests that fail perhaps one run in six. Nobody can reproduce them locally. The team's coping strategy is a rerun button.

What they look at first. Not the three tests. They run the whole suite in a randomised order with a recorded seed (pytest-randomly and friends do this), because the question is not "which test is flaky" but "is my suite order-independent at all?" Twenty failures appear. The three flaky ones were the only cases where the usual alphabetical order happened to be unlucky.

The cost they name out loud. Not the twenty failures — the rerun habit. One extra pipeline run per merge on a team merging dozens of times a week is hours of wall-clock delay, and, far worse, it trains everyone to treat a red build as noise. The next real regression will also be rerun. That is the argument that gets the work funded; "globals are bad practice" is not.

The alternative they reject. An autouse fixture that resets the module's dictionaries between tests. It goes green in an afternoon, and it is a tax that grows with every new global, paid by every future test author. It also fixes the wrong system: production still depends on import order, so a worker that imports lazily still behaves differently from the web process. They keep it — as a dated entry in the debt ledger, not as the fix.

What they choose. Strangle it rather than rewrite it. The state gets an owner; the old global becomes a shim over one instance, with a countable number of remaining callers:

class PluginRegistry:                     # step 1: something owns the state
    def __init__(self) -> None:
        self._plugins: dict[str, Plugin] = {}

    def register(self, name: str, plugin: Plugin) -> None:
        self._plugins[name] = plugin

_default: PluginRegistry | None = None    # step 2: an honest, temporary shim

def default_registry() -> PluginRegistry:
    global _default
    if _default is None:                  # 23 call sites remain; see the debt ledger
        _default = PluginRegistry()
    return _default

The consequence over time. New code takes a registry as a parameter; old code goes through the shim; the number of shim callers is a figure in the debt ledger that only ever goes down, and a fitness test (lesson 0022) fails the build if a new module-level mutable container appears in the package. Six weeks later the count reaches zero and the shim is deleted. The team never had to schedule a big-bang refactor, and — the part that actually matters — the suite became evidence again.

When this is the wrong move

• Process-wide infrastructure. Logging configuration, tracing, metrics registries and connection pools are legitimately one per process. Construct them at the composition root, freeze them after startup, and do not let application code reconfigure them at runtime.
• Scripts and short-lived CLIs. One entry point, one run, no test suite to protect: the injection plumbing can cost more than the coupling.
• When the alternative is threading a parameter through layers that don't care. A request context passed through fifteen frames that ignore it is its own kind of noise. Use an explicit context object at the edge, or contextvars with one owner — and write down which you chose and why.
• Caches of genuinely pure functions. functools.lru_cache over a function of its arguments alone is fine. It stops being fine the moment that function reads a config value, a clock or an environment variable.

Skill: find the phone lines

Practice on your own code

Grep your project (and AI output) for module-level mutable containers and singletons. Pick one that two or more modules read or write. Convert it to an owned, injected object and move construction to a composition root.

In the lab: the phase-2 checkpoint asks you to find the module-level registry the returns service mutates at import time, give the state one owner, and leave a shim behind so the migration can be done in slices — plus the order-randomised test run that proves it worked.

# before: settings._registry mutated at import time by several plugins
import settings
settings.register_plugin(MyPlugin())      # import side effects everywhere

# after: a PluginRegistry object built once, explicitly
registry = PluginRegistry()
registry.register(MyPlugin())
app = build_app(registry)

Read and watch deeper

• The Pragmatic Programmer, Hunt & Thomas — the sections on global data and "decoupling": the classic treatment.
• Code Complete, McConnell — ch. 5: global data as the worst coupling level (common coupling).
• A Philosophy of Software Design, Ousterhout — ch. 5 "Information Hiding": what the module exposes is a choice; globals expose everything.
• Fowler, "Inversion of Control Containers and the Dependency Injection Pattern" — the primary source for the distinction this lesson leans on: injection is passing the dependency; the container is an optional extra.
• Watch: ArjanCodes YouTube — search "global state" or "dependency injection".
• Next: lesson 0020 — shared state and ownership.
• Reference: Design Principles — separate creation from use; glossary — global coupling, composition root.

Run the greedy-review grep with your agent-teacher and decide each hit together.

Source page: lessons/0019-global-coupling.html

Lesson 0020 · System Designer · Module 2

Shared State and State Ownership

Lesson 0019 removed the globals. This one handles the harder case: state that must be shared, but must have exactly one owner who is responsible for it.

Reading ≈ 8 minPractice ≈ 30 min

Mission tie-in: "manage shared state and understand state ownership" — the rule that keeps concurrency bugs from becoming your daily life.

Knowledge: one owner per state

Every piece of state has exactly one owner: the object (or module, or process) responsible for its correctness — for its invariants (lesson 0011), its lifecycle, and its writes. Everyone else is a reader or a requester.

The failure is state with no owner — shared and edited by whoever happens to hold it:

# two modules both "own" the user's profile
class ProfileService:
    def update_email(self, user: UserProfile, new_email: str) -> None:
        user.email = new_email                    # writes directly

class SyncService:
    def sync(self, user: UserProfile) -> None:
        if user.email.endswith("legacy.com"):
            user.email = user.email.replace("@legacy.com", "@new.com")  # also writes

# whichever runs last wins; nobody validated the other's write

Two writers, no coordination: the profile's invariants (unique email, verified flag) can be broken by either path, and tests pass or fail depending on call order — the same disease as lesson 0019, now in objects.

Ownership made explicit:

class UserProfile:
    def __init__(self, email: str, verified: bool) -> None:
        self._email = email
        self._verified = verified

    def change_email(self, new_email: str) -> None:     # the owner's door
        if self._verified:
            raise ProfileLockedError()
        self._email = new_email

class ProfileService:
    def update_email(self, profile: UserProfile, new_email: str) -> None:
        profile.change_email(new_email)                 # requests; doesn't grab

class SyncService:
    def sync(self, profile: UserProfile) -> None:
        if profile.email.endswith("legacy.com"):
            profile.change_email(profile.email.replace("@legacy.com", "@new.com"))

Both services still change the email — but only through the owner's door, which enforces the invariant and owns the write. That's the definition of ownership: the object guards its own state; outsiders request.

Ownership also leaks through references, which is where careful-looking code goes wrong. A private attribute handed out by a property is not private:

class Return:
    def __init__(self) -> None:
        self._lines: list[ReturnLine] = []

    @property
    def lines(self) -> tuple[ReturnLine, ...]:
        return tuple(self._lines)      # a copy — callers cannot append behind your back

    def add_line(self, line: ReturnLine) -> None:
        if self._state is not ReturnState.REQUESTED:
            raise ReturnLockedError()
        self._lines.append(line)

How a senior designer works the case

A customer platform. The profile service owns customer records; the CRM has an inline edit field for the email address; a nightly job syncs the two. The symptoms arrive separately: tens of thousands of rows updated every night, a handful of customers whose address flips back and forth over days, and refund notifications failing for addresses that were verified and then quietly changed.

What they look at first. Not the sync job. The fact: which system is authoritative for a customer's email, and what is everyone else holding? Nobody can answer, which is the finding. The sync job was written on the assumption that both sides hold truth and disagreement is a merge problem.

The question they ask. "Which invariant is supposed to hold here, and can the system that enforces it see every write?" The rule is "a verified address cannot change without re-verification". The profile service enforces it. The CRM does not know it exists. So the rule is not enforced at all — it is enforced on one of two paths, which is the same as none.

The alternative they reject. Last-write-wins on timestamps, the standard proposal. It resolves the flapping and fixes nothing that matters: clock skew between two systems makes "last" unknowable at the granularity of a single second, and, more fundamentally, LWW has no opinion about verification. It converts a visible disagreement into a silent one, which is the direction you never want to move.

What they choose, and what it costs. One owner: the profile service. The CRM keeps a replica stamped with a sync time, and its edit control becomes a request — an event the owner may apply, reject, or apply after re-verification. The sync becomes one-directional. The cost is named out loud rather than hidden: the CRM team loses instant inline editing and has to show a pending state, which is a product decision made in favour of an invariant over a UI convenience, and it needs a new state to test.

The consequence over time. The nightly diff falls to near zero, so the job's row count becomes a usable alarm instead of noise. The flapping stops. And when the verification rule changes next year — it will — exactly one codebase changes, and no one has to find out which other system also had an opinion.

When this is the wrong move

• Deliberate replicas and caches. They exist to be stale. Give them an age and no authority, and never let a rule be enforced against a copy.
• Collaborative and offline-first products. Multi-writer is the feature. Then design the merge semantics explicitly — CRDTs, operational transforms, or an application-level conflict rule — rather than pretending one writer exists.
• Read models and projections. Written by a projector, owned by nobody in the domain sense, and correct only as a derivative of the events that produced them.
• Facts that genuinely have two owners. Sometimes the answer is that the fact is two facts: the profile owns identity, the CRM owns marketing consent. Split the data, not the write path — a jointly owned field is an unresolved argument stored in a column.

Skill: who's the owner?

Practice on your own code

Pick a shared mutable object in your codebase (a profile, a session, a document). List its writers. If there is more than one, route them through the object's own methods — then ask whether an immutable handoff would serve better.

In the lab: the phase-2 checkpoint has two services that both assign to a return's status, plus an aggregate that hands its internal line list out through a property. You name the owner, convert the second writer into a requester, and close the reference leak.

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 9 "Better Together or Better Apart": deciding what should share what.
• Designing Data-Intensive Applications, Kleppmann — ch. 7 "Transactions": ownership and coordination when the state outlives a process.
• Robust Python, Viafore — the chapters on state management in Python systems.
• Designing Data-Intensive Applications, Kleppmann — ch. 5 "Replication": single-leader replication is this lesson's rule at system scale, and the multi-leader section is the honest account of what you take on when you allow two writers.
• Watch: ArjanCodes YouTube — search "shared state" or "state management".
• Next: lesson 0021 — error handling strategies.
• Reference: Design Principles — tell, don't ask; glossary — shared state.

Bring a two-writer object to your agent-teacher and design the ownership split together.

Source page: lessons/0020-shared-state-and-ownership.html

Lesson 0021 · System Designer · Module 2

Practical, Maintainable Error Handling

Lesson 0014 said fail fast at the right boundary. This lesson builds the full strategy: where errors are raised, how they travel, and where they are translated, retried, and logged.

Reading ≈ 8 minPractice ≈ 45 min

Mission tie-in: "design practical and maintainable error handling strategies" — the difference between exceptions as a mechanism and exceptions as a language.

Knowledge: a language, not a mechanism

An error strategy has four layers, each with a job:

1. Raise — in the domain, at the moment of refusal (lessons 0011, 0014).
2. Translate — at boundaries, wrap foreign errors in your vocabulary.
3. Retry — at integration boundaries, where failures are transient.
4. Log and report — at the edges, once, with the error's story intact.

The language is your exception hierarchy — flat, named, and domain-shaped:

class CheckoutError(Exception):
    """Base for everything checkout can fail with."""

class InsufficientStock(CheckoutError):
    pass

class PaymentDeclined(CheckoutError):
    def __init__(self, provider_message: str) -> None:
        self.provider_message = provider_message
        super().__init__(f"payment declined: {provider_message}")

class PaymentGatewayUnavailable(CheckoutError):   # retryable, not a decline
    pass

Each layer then handles exactly what it is placed to handle. Retry belongs to the adapter, because only the adapter knows the failure was a transport problem:

# infrastructure/ — retry wraps the port, never the rule
class RetryingPaymentGateway:
    def __init__(self, inner: PaymentGateway, attempts: int = 3) -> None:
        self._inner = inner
        self._attempts = attempts

    def charge(self, amount: Money, token: str) -> str:
        for attempt in range(self._attempts):
            try:
                return self._inner.charge(amount, token)
            except PaymentGatewayUnavailable:
                if attempt == self._attempts - 1:
                    raise                         # out of attempts: let it travel
                time.sleep(2 ** attempt)          # backoff lives here, not in the domain

Translation and logging belong at the edge, where the error leaves the system and someone outside has to be told something useful:

# api/ — translate once, log once
def checkout_endpoint(cart: Cart, service: CheckoutService) -> Response:
    try:
        service.checkout(cart)
    except InsufficientStock as e:
        return Response(409, str(e))              # a client mistake
    except PaymentDeclined as e:
        return Response(402, e.provider_message)  # the bank said no
    except CheckoutError:
        logger.exception("checkout failed")       # logged once, with the traceback
        return Response(500, "checkout unavailable")
    return Response(201, "created")

The domain in the middle contains no try at all. It raises its own vocabulary and gets on with the rules — which is why its tests are three lines long.

Four rules keep it maintainable: never catch Exception bare; never convert an error to None at the raise site; catch only what you can handle, at the boundary where handling means something; log once, where the error leaves the system.

Worked example: the catch that cost a quarter's reconciliation

A four-person payments team runs a nightly reconciliation over roughly 12,000 settlement rows. Inside the row loop sits except Exception: continue. The job is green every morning.

A senior designer reads the line after the catch first. continue is a statement of policy: this failure has no consequence. So the question is not "should we catch here?" but "who is entitled to decide a settlement row doesn't matter?" Nobody in that loop has the standing, because the loop cannot see the reject rate — and the rate is the only thing separating one bad row from a broken feed. Logging inside the loop is rejected for the same reason: it turns a silent failure into an unread one and leaves the decision where it was.

Price the drift. A 0.3% failure rate is 36 rows a night, about 1,080 unreconciled settlements over a month. At a median €48 a row that is roughly €52,000 of cash the ledger cannot attribute — found by finance at quarter close, not by engineering, and reconstructed through a two-week manual audit. The defect was one line; the bill was a fortnight of someone else's quarter.

The fix moves the decision up one layer and makes the rate visible — landing on the boundary the principle box named, where an accumulated result beats an exception per row.

# application/ — the batch owns the run, so the batch decides
@dataclass(frozen=True)
class RowRejected:
    row_id: str
    reason: str

def reconcile(rows: list[dict], ledger: Ledger) -> BatchResult:
    posted, rejected = 0, []
    for row in rows:
        try:
            ledger.post(parse_settlement(row))      # raises SettlementInvalid
            posted += 1
        except SettlementInvalid as invalid:        # one named failure, handled
            rejected.append(RowRejected(row["id"], str(invalid)))
    if len(rejected) > len(rows) * 0.01:            # a broken feed, not a bad row
        raise ReconciliationAborted(posted, rejected)
    return BatchResult(posted=posted, rejected=tuple(rejected))

Three things changed and only one is code. The catch is specific, so an unexpected failure still travels. The rejects are data, so the run reports "11,964 posted, 36 rejected" to a dashboard rather than to a log nobody opens. And the threshold makes the policy reviewable. Eighteen months later, when a partner silently changed its date format, the job failed on the first night instead of the ninetieth.

When this is the wrong move

Skip the machinery when the layers collapse into each other. A one-file script has no boundary worth translating across. A library raises its own types and stops. Loops where failure is the expected case want an accumulated result, not an exception per item. And don't build a hierarchy before two callers actually distinguish two failures — a base class with one subclass is a naming ceremony, and the second class costs nothing to add on the day the second decision appears.

Skill: where does each error go?

Practice on your own code

Audit one module's exception handling: list every try/except, what it catches, and what it does. Mark each as raise, translate, retry, or log-and-report. Delete the bare excepts; move retries to boundaries; name the hierarchy if there isn't one.

In the lab. The phase-2 checkpoint hands you the returns-resolution service with a bare except Exception around the carrier call that quietly returns None. You classify every catch as raise, translate, retry or report, and move the retry into the adapter that can prove the call is safe to repeat.

Read and watch deeper

• Clean Code, Martin — ch. 7 "Error Handling": the exception-hierarchy and boundary-translation rules.
• A Philosophy of Software Design, Ousterhout — ch. 10 "Define Errors Out of Existence": design so many errors never arise.
• "The Error Model", Joe Duffy — the long primary account of bugs vs recoverable errors, and why that distinction decides where you catch.
• Robust Python, Viafore — Python-specific exception design: when to raise, subclass, and wrap.
• Watch: ArjanCodes YouTube — search "error handling python".
• Next: lesson 0022 — organizing modules and folders.
• Reference: Patterns — Decorator, the shape the retrying gateway above is; glossary — fail-fast.

Bring your module's try/except inventory to your agent-teacher and classify each catch together.

Source page: lessons/0021-error-handling-strategies.html

Lesson 0022 · System Designer · Module 2

Organizing Modules and Folders Around Boundaries

Folders are the interface your team reads first. Organize by responsibility and boundary — not by file type — and the architecture announces itself in the tree.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: "organize modules and folders around responsibilities and boundaries" — the layout that keeps a growing application navigable and its dependency arrows visible.

Knowledge: the tree should tell the story

A project organized by file type — models/, services/, controllers/, utils/ — tells you nothing about what the system does. A project organized by boundary — domain, application services, infrastructure, delivery — tells you how change flows before you open a file:

checkout/
├── domain/                # the core: rules, value objects, aggregates (nothing imports out)
│   ├── order.py
│   ├── money.py
│   └── pricing.py
├── application/           # use cases: orchestrate domain via ports
│   ├── checkout_service.py
│   └── ports.py           # PaymentGateway, OrderRepository, Inventory…
├── infrastructure/        # adapters: the world conforming to the ports
│   ├── stripe_adapter.py
│   ├── sqlalchemy_repository.py
│   └── email_adapter.py
└── api/                   # delivery: HTTP, CLI, whatever the outside speaks
    └── endpoints.py

The rules that keep it stable:

• Dependency direction is visible in the tree: domain imports nothing outside itself; application imports domain; infrastructure imports both; api imports application. A cycle shows up as an import you can't explain.
• Naming by role, not by technology: "stripe_adapter" says what it is; "payments" as a sibling folder to "domain" says nothing.
• No utils/ graveyard: a utility that doesn't belong to any boundary is a cohesion failure waiting to be named.
• Boundaries match teams when they can: a boundary that matches a team's ownership (lesson 0033) makes coordination follow the tree.

A convention nobody enforces decays within a quarter. Turn the rules into a test and the tree becomes a fitness function — the arrows fail the build instead of failing review:

# tests/test_architecture.py
FORBIDDEN = {
    "checkout.domain":      ("checkout.application", "checkout.infrastructure",
                             "checkout.api"),
    "checkout.application": ("checkout.infrastructure", "checkout.api"),
    "checkout.infrastructure": ("checkout.api",),
}

def test_dependency_direction() -> None:
    for package, forbidden in FORBIDDEN.items():
        for module in walk_modules(package):
            for imported in imports_of(module):
                assert not imported.startswith(forbidden), (
                    f"{module} imports {imported}: the arrow points outward"
                )

Fifteen lines — walk_modules and imports_of are a few more, built on pkgutil and ast — and the boundary is now a fact about the build rather than a promise in a README. (Tools like import-linter do the same job from a config file; what matters is that something checks.)

Worked example: the re-folder nobody could merge

Nine engineers, one repo, about 90,000 lines, laid out as models/ services/ controllers/. Everyone agrees it should be re-foldered. Two previous attempts died in review.

A senior designer does not start with the folders. They start with the imports, because the folders are an opinion and the imports are evidence: a twenty-line script over ast counts cross-folder import pairs. The finding is specific — services imports controllers in fourteen places, because the request-parsing helpers happen to live there. That is the arrow that should not exist, and it names the actual defect: fourteen files, not nine hundred.

The question they ask next is deliberately not "what should the tree look like?" but "for each folder, what is the reason it changes?" — because a folder whose reason to change you cannot state in one clause is not a boundary (lesson 0006), and moving files into it just relocates the confusion.

The rejected option is the tempting one: re-folder everything in a single pull request. It fails on arithmetic rather than on principle. Nine engineers carry roughly twenty open branches at any time; a 900-file move rewrites the import line of nearly every one of them, so each branch owner pays a manual rebase, and git blame stops answering "why is this line here?" for the next quarter — exactly when the team most needs to read its own history.

What ships instead is a ratchet. Add the fitness test with today's violations frozen into an allowlist; forbid new entries; move one folder per sprint and delete rows from the list as they are fixed. The allowlist is a visible architecture-debt ledger — fourteen lines that only ever get shorter.

# tests/test_architecture.py — today's violations are frozen; new ones fail
KNOWN_VIOLATIONS = {
    ("checkout.application.pricing", "checkout.api.serializers"),
    # …13 more. This set may shrink. It may never grow.
}

def test_dependency_direction() -> None:
    found = set()
    for package, forbidden in FORBIDDEN.items():
        for module in walk_modules(package):
            for imported in imports_of(module):
                if imported.startswith(forbidden):
                    found.add((module, imported))
    assert found <= KNOWN_VIOLATIONS, f"new violation: {found - KNOWN_VIOLATIONS}"
    assert not (KNOWN_VIOLATIONS - found), "fixed — delete these from the allowlist"

Five sprints later the set is empty and the second assertion deletes itself. Nothing was merged that a reviewer could not read in one sitting, and no branch owner paid a rebase they had not chosen. The point worth carrying: the tree was never the deliverable — the arrow count was.

When this is the wrong move

Don't draw boundaries you haven't discovered. A one-file script, a library with a single public module, and a two-week spike are all better flat. In a genuinely new domain, resist foldering until the third feature shows you where the seam actually is — a wrong boundary is more expensive than no boundary, because code starts conforming to it. And never fold to match an org chart you don't have yet: shaping the tree around a team split that may not happen is speculative generality (lesson 0030) applied to directories.

Skill: draw the tree

Practice on your own code

Draw your project's current folder tree and label each folder's job and allowed imports. Then redraw it by boundary. Count the files whose home changes — those files are your mis-organization, and the redraw is your target layout.

In the lab. The phase-2 checkpoint gives you the returns-resolution service as one flat package with the carrier SDK imported from the rules. You write the import table first, add the failing fitness test with today's violations frozen, and only then move a file.

Read and watch deeper

• Clean Architecture, Martin — ch. 12–14: component cohesion and coupling — the principles behind folder boundaries.
• Architecture Patterns with Python, Percival & Gregory — ch. 4: the package layout this lesson's tree comes from.
• A Philosophy of Software Design, Ousterhout — ch. 4 and 7: module depth and "different layer, different abstraction" applied to folders.
• import-linter — the official docs for the contract types (layers, forbidden, independence) that express this lesson's import table as configuration.
• Watch: ArjanCodes YouTube — search "project structure python".
• Next: lesson 0023 — Ports & Adapters for infrastructure.
• Reference: Glossary — fitness function, boundary.

Show your agent-teacher your folder tree and label every folder's allowed imports together.

Source page: lessons/0022-module-organization.html

Lesson 0023 · System Designer · Module 3

Ports & Adapters for Infrastructure

Lesson 0009 drew one arrow. Now draw them all: database, APIs, filesystem, clock, email — every technology behind a port, wired at a single composition root.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: "apply Ports & Adapters to isolate infrastructure concerns" — the System Designer's full application of the pattern, and the shape your AI prompts should prescribe.

Knowledge: everything outside is an adapter

The domain speaks only to ports. The infrastructure — storage, gateways, files, the clock itself — implements them. The full inventory of infrastructure in a typical system:

• Persistence → OrderRepository (lesson 0013)
• External APIs → PaymentGateway, SupplierFeed
• Filesystem → InvoiceStore
• Email/notifications → Notifier
• The clock → Clock.now() — even time is infrastructure worth a port

# domain/ports.py — everything the core needs from the world:
class Clock(Protocol):
    def now(self) -> datetime: ...

class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...
    def add(self, order: Order) -> None: ...

# infrastructure/ — the world, conforming:
class SystemClock:
    def now(self) -> datetime:
        return datetime.now()

class SqlAlchemyOrderRepository:
    ...

# composition root — the only place the two meet:
def build_app() -> App:
    clock: Clock = SystemClock()
    orders: OrderRepository = SqlAlchemyOrderRepository(make_session())
    notifier: Notifier = EmailAdapter(smtp_config())
    checkout = CheckoutService(orders, notifier, clock)
    return App(checkout=checkout)

The composition root — one visible function where everything is constructed and injected — is the pattern's capstone. Nothing anywhere else says "SQLAlchemy" or "stripe" or "datetime.now". Swap a technology by editing this one function.

Worked example: the test that only failed at night

A six-engineer team has a promotional pricing rule that reads datetime.now() to decide whether a promo window is open. Its test asserts "no discount at 23:59". The test passes for eleven months, then starts failing intermittently.

The first thing a senior designer looks for is not the bug but what in this test is not controlled by the test. The answer is the clock: the assertion is about an instant, and the instant is supplied by the machine. CI runs about forty times a day and the flake costs roughly 2% of runs — under one red build a day, and each one buys a re-run plus ten minutes of somebody's attention. That is only a few hours a month, and the hours are not the real cost. The real cost is that the team learns to re-run red builds without reading them, so the next genuine failure is also re-run.

The tempting repair is to monkeypatch datetime in the test. It is rejected for three reasons and it is worth holding all three: it mutates a module global for the whole process (lesson 0019) and leaks into whatever runs next; it silently fails if the rule imported now directly rather than the module; and it leaves the production signature lying — the function still claims to depend on nothing while depending on the wall clock.

The port makes the dependency part of the contract. The fake is three lines, and the test now names the instant it is asserting about:

# domain/ — the dependency is now visible in the signature
class Clock(Protocol):
    def now(self) -> datetime: ...

def promo_price(base: Money, promo: Promo, clock: Clock) -> Money:
    if promo.starts_at <= clock.now() < promo.ends_at:
        return base * promo.factor
    return base

# tests/ — the second implementation, and the reason the port exists
class FrozenClock:
    def __init__(self, at: datetime) -> None:
        self._at = at

    def now(self) -> datetime:
        return self._at

def test_promo_is_closed_one_second_before_it_opens() -> None:
    clock = FrozenClock(datetime(2026, 7, 1, 9, 59, 59))
    assert promo_price(Money(100), july_promo, clock) == Money(100)

Read the two signatures side by side: the old one said promo_price(base, promo) and lied; the new one declares that pricing depends on time. Over the following year the same clock let the team test a daylight-saving boundary, a promo that spans midnight, and an expiry-at-year-end case — none of which anyone would have written while the only way to reach them was to wait.

When this is the wrong move

Skip the port in a spike whose whole purpose is to learn the vendor's API — the abstraction would hide exactly what you are trying to see. Skip it in scripts. Skip it when the proposed port would have one implementation, no fake, and a vocabulary copied verbatim from the vendor: that is not a boundary, it is a rename with an extra file. And be honest about the failure mode on the other side — a system where every stdlib call has been ported is one where finding out what actually happens requires opening four files, and that cost is paid on every read by everyone.

Skill: what gets a port?

Practice on your own code

List every technology your domain touches today (imports of SDKs, datetime.now(), filesystem, env vars). For each, mark: changeable? needs faking in tests? Give a port to every "yes"; wire them all in a composition root function.

In the lab. The phase-2 checkpoint has you build the infrastructure inventory for the returns-resolution service — carrier SDK, database session, datetime.now() inside the eligibility rule, an environment read three files deep — then introduce a clock and a carrier port with fakes, and wire them in one composition root.

Read and watch deeper

• Architecture Patterns with Python, Percival & Gregory — ch. 2–4: the working pattern — repository, service layer, and the composition root.
• "Hexagonal Architecture", Cockburn — the origin, and the "application is a core surrounded by adapters" diagram.
• Growing Object-Oriented Software, Guided by Tests, Freeman & Pryce — ch. 2 and 8: "only mock types you own", which is this lesson's rule arrived at from the testing side.
• Clean Architecture, Martin — ch. 17–18: boundaries, the dependency rule, and crossing the boundary cleanly.
• Watch: ArjanCodes YouTube — search "ports and adapters".
• Next: lesson 0024 — keeping async out of domain logic.
• Reference: Patterns — Ports & Adapters, composition root; Design Principles — depend on abstractions.

Inventory your domain's technology imports with your agent-teacher and decide each port together.

Source page: lessons/0023-ports-and-adapters-for-infrastructure.html

Lesson 0024 · System Designer · Module 3

Keeping Concurrency and Async Out of Domain Logic

Business rules don't care about event loops. When async bleeds into the domain, every rule becomes untestable and every I/O becomes a hidden dependency.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: "keep concurrency and async execution out of domain logic" — the discipline that keeps the core pure and the edges fast.

Knowledge: pure core, async edges

An async function is a statement about how code runs. Domain rules are statements about what is true. When the two mix, the domain's tests need an event loop, and every call site inherits the async decision — whether it wanted it or not.

# the spread: domain logic fused to I/O style
async def apply_refund(order: Order, gateway: AsyncPaymentGateway) -> Refund:
    if order.status == Status.REFUNDED:          # domain rule
        raise AlreadyRefunded()
    result = await gateway.refund(order.total)   # I/O, inside the rule
    order.mark_refunded(result.refund_id)
    return Refund(result.refund_id)

Test that function and you must build an event loop and mock gateway.refund — and if the rule ever needs a synchronous caller (a cron job, a script), the async spreads further.

The clean split:

# domain: sync, pure, no I/O
def apply_refund(order: Order, refund_id: str) -> Refund:
    if order.status == Status.REFUNDED:
        raise AlreadyRefunded()
    order.mark_refunded(refund_id)
    return Refund(refund_id)

# application/service layer: async at the edge
async def refund_order(order: Order, gateway: AsyncPaymentGateway) -> Refund:
    result = await gateway.refund(order.total)
    return apply_refund(order, result.refund_id)     # sync rule, called once

The rule is now testable with plain function calls; the async lives only where I/O lives. Same for threads: domain code never spawns, never locks, never sleeps — it receives decisions and returns results; concurrency is an edge concern.

Worked example: three awaits inside one eligibility rule

A returns-resolution service decides whether a return is eligible. The rule needs three things: the order, the carrier's scan events, and the customer's prior return rate. The first draft is an async def that awaits all three.

What a senior designer checks first is not the keyword but the dependency between the fetches: does any of the three depend on the result of another? Here, no — they are three independent lookups keyed on the same order id. That single observation decides the shape, because independent fetches can be gathered at the edge and handed to the rule as data, whereas dependent ones cannot.

The alternative that gets proposed in review is to keep the rule async so it can fetch lazily — "we only pay for what the rule actually reads". It is rejected on two grounds. First, it makes cost invisible: a rule that reads three attributes now issues three sequential network calls, 3 × 120 ms instead of one gathered 130 ms, and nothing in the rule's text says so. Second, it hides an N+1 the moment the rule runs over a batch.

Put the batch number on it. The nightly job evaluates about 8,000 returns. Sequential in-rule fetching at ~360 ms each is roughly 48 minutes; gathered at the edge — and batched where the repository allows it — the same work finishes in under four. The rule's own test suite drops from seconds of event-loop setup to milliseconds, which is what makes anyone willing to add the fourteenth eligibility case.

# application/ — the edge gathers, because the edge owns I/O
@dataclass(frozen=True)
class EligibilityInput:
    order: Order
    scans: tuple[CarrierScan, ...]
    prior_return_rate: float

async def evaluate(order_id: str, orders, carrier, history, policy) -> Decision:
    order, scans, rate = await asyncio.gather(
        orders.get(order_id), carrier.scans(order_id), history.rate(order_id)
    )
    return is_eligible(EligibilityInput(order, tuple(scans), rate), policy)

# domain/ — sync, pure, and readable as a policy document
def is_eligible(data: EligibilityInput, policy: ReturnPolicy) -> Decision:
    if data.order.age_days > policy.window_days:
        return Decision.refuse("outside the return window")
    if data.prior_return_rate > policy.fraud_threshold:
        return Decision.review("prior return rate above threshold")
    if not any(scan.is_delivery for scan in data.scans):
        return Decision.refuse("no delivery scan on record")
    return Decision.approve()

Note what the split bought beyond speed. is_eligible is now readable as a policy document by someone who does not write Python — which is how the fraud threshold got questioned by the operations lead, and corrected, before launch. That conversation is not available about a function that also opens sockets.

When this is the wrong move

Don't extract a pure core when the concurrency is the domain: schedulers, rate limiters, lease and lock managers, protocol state machines, streaming operators. There, timing and ordering are the rules being modelled, and pushing them to the edge produces a core that describes something the system does not do. Don't do it either when the fetch plan depends on intermediate results — keep a pure "what next?" function and let an async driver walk it. And in a three-function service where the whole application is one async layer, the split buys a file and returns nothing.

Skill: what's where?

Practice on your own code

Grep your domain folder for async, await, thread, sleep, lock. For each hit, move the concurrency out: the service layer awaits, the domain decides. Re-run your domain tests without an event loop.

In the lab. The phase-2 checkpoint has the returns eligibility check awaiting the carrier client from inside the rule, once per return, in a loop. You gather the inputs at the edge, turn the rule into a pure function over a frozen input record, and watch the domain test file lose its event loop.

Read and watch deeper

• Architecture Patterns with Python, Percival & Gregory — ch. 7–8: the sync domain + async edges shape, and the message bus that replaces scattered awaits.
• "What Do You Mean by Event-Driven?", Fowler — the vocabulary for why async belongs at the edges.
• "What Color Is Your Function?", Bob Nystrom — the primary statement of why async is viral through a call graph.
• Robust Python, Viafore — concurrency chapters: keeping the core free of threading primitives.
• Watch: ArjanCodes YouTube — search "asyncio" for the channel's async guidance.
• Next: lesson 0025 — event-driven architecture.
• Reference: Patterns — async boundary.

Show your agent-teacher your async domain and extract one function together.

Source page: lessons/0024-async-out-of-domain-logic.html

Lesson 0025 · System Designer · Module 3

Event-Driven Architecture

When one event sets off many reactions, direct calls chain every component to every other. Events break the chain: the producer doesn't know its consumers exist.

Reading ≈ 9 minPractice ≈ 45 min

Mission tie-in: "use event-driven architecture to decouple workflows and components" — the System Designer's last module, and the stepping stone to the trade-offs of Phase III.

Knowledge: facts, not instructions

An event is a fact that happened, named in the past tense: OrderConfirmed, PaymentReceived, StockDepleted. It is an immutable value object (lesson 0012) carrying what happened, not what to do. Consumers decide their own reaction.

@dataclass(frozen=True)
class OrderConfirmed:
    order_id: str
    occurred_at: datetime

# the bus: routes events to handlers
class MessageBus:
    def __init__(self) -> None:
        self._handlers: dict[type, list[Callable]] = {}

    def register(self, event_type: type, handler: Callable) -> None:
        self._handlers.setdefault(event_type, []).append(handler)

    def publish(self, event: object) -> None:
        for handler in self._handlers.get(type(event), []):
            handler(event)

# the domain records the fact; it does not publish it:
class Order:
    def __init__(self, order_id: str) -> None:
        self.order_id = order_id
        self._status = Status.PENDING
        self.events: list[object] = []       # facts, collected

    def confirm(self) -> None:
        if self._status != Status.PENDING:
            raise OrderLockedError()
        self._status = Status.CONFIRMED
        self.events.append(OrderConfirmed(self.order_id, now()))

# the service publishes only after the write succeeded:
def confirm_order(order_id: str, orders: OrderRepository, bus: MessageBus) -> None:
    order = orders.get(order_id)
    order.confirm()
    orders.save(order)                       # commit first…
    for event in order.events:               # …then announce
        bus.publish(event)

# the wiring — handlers care, the Order doesn't:
bus.register(OrderConfirmed, send_confirmation_email)
bus.register(OrderConfirmed, issue_invoice)
bus.register(OrderConfirmed, reserve_stock)

The two-step — collect in the domain, publish after the commit — is not ceremony. Publish inside confirm() and a failed save leaves three handlers acting on an order that does not exist: an invoice for nothing, an email about nothing, stock reserved for nothing. The domain records what happened; the layer that owns the transaction decides when it is true enough to announce.

Order knows nothing about email, invoicing, or stock — it announced a fact, and the bus did the rest. Adding a fourth reaction (analytics) touches the wiring only. That's the decoupling: producer ignorance.

The honest price: the flow is no longer visible in one call stack. Reading the code tells you what happened, not what will happen next — that knowledge lives in the wiring. Event-driven is a trade, not a free lunch (the full accounting comes in Phase III's sync vs async).

Worked example: the handler that stopped the two after it

An order service publishes OrderConfirmed to four in-process handlers: email, invoice, stock reservation, analytics. At about 6,000 orders a day it runs quietly for a year. Then the invoicing handler starts raising on a malformed partner VAT number — and because publish is a plain loop, handlers three and four never run for those orders.

The first thing a senior designer inspects is not the invoice bug. It is the failure semantics of the publish loop: what happens to handler N+1 when handler N raises? That is a property of the bus, and nobody had ever written it down. The bug in the VAT parser is a week's worth of incident; the unwritten semantics are the thing that will produce the next three incidents.

The second question is the one that reframes the design: "is each of these reactions genuinely allowed to fail, and who finds out when it does?" Asked plainly, three of the four answer "yes, and nobody needs to know today". Stock reservation answers "no — if this doesn't happen we oversell". That answer means stock reservation was never an event reaction at all. It is a step in the workflow that happens to have been wired like a notification.

The rejected repair is to wrap each handler in try/except and log. It fixes the ordering bug and leaves the real one untouched: the stock is still unreserved, and now silently so. Count the damage before choosing. Malformed VAT numbers appeared on 1.2% of orders for three days — roughly 216 orders shipped without a reservation. Roughly one in eight became an actual oversell: about 27 items, each costing an apology, an expedited restock and a support contact at something like €40 all-in, so a little over €1,000 in direct cost and a much larger dent in the "we have it in stock" promise. The try/except would have prevented none of it.

So two changes ship, and only one of them is the bus. Stock reservation moves out of the event chain into the confirmation workflow, where its failure fails the operation. The remaining three handlers get isolated, with failures preserved for replay rather than logged and lost:

class MessageBus:
    def __init__(self, dead_letters: DeadLetterQueue) -> None:
        self._handlers: dict[type, list[Callable]] = {}
        self._dead_letters = dead_letters

    def publish(self, event: object) -> None:
        for handler in self._handlers.get(type(event), []):
            try:
                handler(event)
            except Exception as failure:      # one handler, one blast radius
                self._dead_letters.put(event, handler.__name__, failure)

That except Exception looks like a violation of lesson 0021 and is not. Lesson 0021's rule is "catch only what you can handle" — and this code can handle it, because its job is isolation: it changes the outcome by preserving the event for replay instead of discarding it, and it is the one layer that knows the blast radius is meant to stop here. A catch that changes the outcome is handling; a catch that only continues is not.

When this is the wrong move

Don't reach for a bus when there is one consumer, when the producer needs the result, when the order of reactions matters, or when a reaction must happen — that last one is a command, and dressing it as an event is exactly the misclassification the worked example cost money on. Be honest about the small-team case too: in a service where "who reacts to this?" is answered by one grep, indirection has a real read-tax and no offsetting benefit. Events earn their keep when the set of consumers changes more often than the producer does.

Skill: what's the decoupling?

Practice on your own code

Find a workflow where one event triggers three or more reactions (a save that emails, logs, and syncs). Extract the fact as an event value object, emit it from the domain, and register the three reactions in the wiring. Then answer honestly: is the flow easier or harder to follow?

In the lab. The phase-2 checkpoint has the returns-resolution service sending the customer email from inside the domain method, before the save. You collect the fact on the aggregate, publish after the commit, and then decide which of the four reactions is actually a command that must not be allowed to fail quietly.

Read and watch deeper

• "What Do You Mean by Event-Driven?", Fowler — event notification vs event sourcing vs CQRS: the vocabulary.
• Architecture Patterns with Python, Percival & Gregory — ch. 8–10: the message bus in working Python, events as domain objects.
• "Event Sourcing", Fowler — when events become the storage, not just the communication.
• "Dead Letter Channel", Hohpe & Woolf — Enterprise Integration Patterns, the catalogue entry for what the isolated publish above does with a failed handler.
• Watch: ArjanCodes YouTube — search "event driven architecture".
• Next: lesson 0026 — libraries vs building.
• Reference: Patterns — message bus and unit of work, the transaction the publish must wait for.

Map your workflow's reaction chain with your agent-teacher before converting it to events.

Source page: lessons/0025-event-driven-architecture.html

Lesson 0026 · System Designer · Module 3

Libraries and Packages vs Building It Yourself

Every dependency you skip is code you maintain forever. Every dependency you take is a contract you must follow. This lesson gives you the decision procedure.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: "understand when to use libraries/packages vs building solutions yourself" — the last System Designer skill, and the bridge to Phase III's first trade-off, Build vs Buy.

Knowledge: three questions decide

Ask three questions about the problem you're about to solve:

1. Is it generic or is it yours? Serialization, auth, date math, HTTP — generic problems with mature solutions. Pricing logic, fraud rules, workflow semantics — your domain. Generic → library. Yours → build.
2. Is the library boring? Mature, widely used, slowly changing (Dan McKinley's "choose boring technology"). A library three days old, or a fashionable rewrite every quarter, is a dependency you'll maintain at its pace, not yours.
3. Can you wrap it? Any dependency worth taking is worth hiding behind a port (lessons 0009, 0023) so its churn never reaches your domain.

# take: JSON Schema validation? mature, generic, boring — take it
import jsonschema
jsonschema.validate(payload, schema)

# hide: the schema library's version churn stays inside the adapter
class PayloadValidator:
    def validate(self, payload: dict) -> None:
        try:
            jsonschema.validate(payload, self._schema)
        except jsonschema.ValidationError as e:
            raise InvalidPayload(str(e))

The cost of building: you own every bug, every missing edge case, every security review forever. The cost of taking: an external contract, upgrade cadence, and supply-chain surface. The tie-breaker is always the same — is this problem your business's differentiator? If yes, build (and own it deliberately). If no, take (and wrap it).

Worked example: fourteen partner feeds and "it's just CSV"

A team ingests daily CSV files from fourteen retail partners. The proposal on the table is to write the parser: it's just splitting on commas, forty lines, no dependency.

A senior designer does not argue about the forty lines. They go and get the data: pull two hundred real files and count how many violate the naive assumption. The result decides the conversation. Six partners emit a UTF-8 byte-order mark. Three quote inconsistently, so a quoted comma appears in one file a week. Two send European decimals (1.234,56). One appends a summary row that is not a record. Nine of fourteen partners break the forty-line parser, and none of those nine knows it.

The question that follows is "how many of these will I meet in production if I hand-roll, and how will I meet them?" — the answer being: all of them, one incident at a time, each discovered because a number in a report is wrong rather than because a parse failed.

The obvious library, pandas, is rejected — and the reason is the third boundary condition, not capability. It would drag a large dependency and a DataFrame model into a domain that wants one typed record per row, so every call site would translate between the two forever. The impedance layer would be permanent and would grow.

What ships is stdlib csv for tokenizing (mature, boring, zero dependencies) plus a schema library for typing and validation, both behind a FeedReader port. The partner quirks — decimal commas, the summary row — are genuinely yours and stay in your adapter, one small class per partner.

Price the difference honestly, because it is smaller than the argument suggests. The hand-rolled path met three of those edge cases in its first year; each cost roughly four hours to diagnose, two to fix, and a feed re-run, so about eighteen hours plus three out-of-hours interruptions. Learning and wiring the library cost six. The gap is not enormous — but the eighteen hours arrived as three surprises, and the six were spent on a Tuesday afternoon by choice. Surprise is the cost that no ledger line shows.

What "boring" means, made checkable: when was the last release, and the one before it? How long do issues stay open? How many maintainers can merge? Is there a changelog and a deprecation policy? Has the public API broken twice in two years? A library that fails three of these is not a dependency, it is a fork you have not taken yet.

When this is the wrong move

Build — or vendor a small, understood copy — when the library's model fights yours, when the transitive surface is unacceptable (regulated builds, embedded targets, cold-start-sensitive functions), or when the library is unmaintained and you would be forking it anyway. Build when you need 5% of something and that 5% is both simple and fully specified: a documented checksum is not a parser. In every one of those cases, write down that you now own it, with a name attached — the failure mode is not the decision, it is the decision nobody recorded.

Skill: take, build, or wrap?

Practice on your own code

List the last three "small utilities" you (or an AI) hand-wrote. Run the three questions on each: generic or yours? boring available? wrapable? Replace at least one hand-rolled utility with the mature library — and wrap it.

In the lab. The phase-2 checkpoint gives you a returns-resolution service that hand-rolls retry with backoff, ISO-date parsing, and money rounding. You run the three questions on each, replace the ones that fail, and put a port around whatever you take.

Read and watch deeper

• "Choose Boring Technology", Dan McKinley — the default posture for dependencies.
• "Simple Made Easy", Hickey — the framework-flavored version of the same cost accounting.
• OpenSSF Scorecard — the checks (maintenance, review, dependency-update tooling, signed releases) that turn "is this library boring?" into a measurement rather than a vibe.
• The Pragmatic Programmer, Hunt & Thomas — the sections on reusable code and buying vs building.
• Watch: ArjanCodes YouTube — search "library vs framework" or "boring technology".
• Next: lesson 0027 — Build vs Buy, the first Master Designer trade-off.
• Reference: Trade-offs — build vs buy, the Master Designer version of this decision.

Bring your hand-rolled utilities to your agent-teacher and run the three questions on each.

Source page: lessons/0026-libraries-vs-building.html

Lesson 0027 · Master Designer · Module 1

Build vs Buy

Lesson 0026 gave the developer's version. The Master Designer's version adds the full accounting: licensing, upgrades, vendor risk, and the one question that overrules everything.

Reading ≈ 9 minPractice ≈ 50 min

Mission tie-in: the first Complexity Trade-Off — where you learn to make decisions under constraints instead of by preference.

Knowledge: the full cost ledger

Both options have costs that are easy to undercount. The discipline is writing both ledgers:

The overruling question (from lesson 0026, now with the ledger behind it): is this your differentiator? If the thing you're building is the reason customers choose you, build — you cannot outsource the thing that makes you you. If it's plumbing — identity, billing infrastructure, file storage, a data-grid component — buy, and spend your team on the differentiator instead.

The third option, often missed: buy the boring 80% and build the 20% that matters. A vendor library + your adapter (lesson 0026's wrap rule) is usually the honest middle: their maturity, your edge.

The middle path has a shape, and it is the port from lesson 0009:

# your 20%: the workflow vocabulary, owned by you
class SignatureService(Protocol):
    def request(self, doc: Document, signer: Party) -> RequestId: ...
    def status(self, request: RequestId) -> SignatureStatus: ...

# their 80%: maturity, contained behind the port
class VendorSignatureAdapter:
    def __init__(self, client: VendorSDK) -> None:
        self._client = client

    def request(self, doc: Document, signer: Party) -> RequestId:
        envelope = self._client.envelopes.create(...)   # their words stop here
        return RequestId(envelope.id)

The port is the boundary of the purchase. Everything the vendor is genuinely good at lives on one side; everything that makes the workflow yours lives on the other. When their v3 renames envelopes to agreements, exactly one file changes — and the upgrade tax stops being a project.

Worked example: what the senior looked at before the price

Same document-signing decision, watched over the shoulder of someone who has made it before. They do not open the pricing page first. They ask two questions the ledger cannot answer.

"If this vendor triples the price at renewal, or is acquired and sunset, what do we do on the Monday after?" That is the reversibility question, and it produces a number: sixteen hours to write a second adapter plus roughly forty hours to export and verify the historical signature records — about €5,000, once. A vendor whose exit costs more than a year of licence owns you, whatever the ledger says. Here it does not.

"Which of our twelve workflow steps does the vendor do natively, which need configuration, and which need a workaround?" Ten native, one configured, one workaround. That last count is the number to watch: past about two workarounds you are on the road to the failure mode where half the codebase exists to fight the 20% that never fitted.

Only then does the ledger get written, and only then does the tempting middle option get considered and rejected: a "thin build" implementing just the three signature types actually needed. It looks like the 80/20 move and it is not. Signature validity is a legal question with jurisdictional edge cases that nobody on a four-person team can evaluate, and the €36,000 build price does not include the liability transfer — which is most of what the vendor is actually selling. Recognising what is really being purchased is the skill; the arithmetic is bookkeeping.

The sequel is the part worth remembering. Three years later the vendor raised prices 22% at renewal. Because the port existed, the team ran a three-week spike against a competitor, priced the switch at the €5,000 they had estimated, and used a credible alternative to negotiate the increase down. They never migrated. The port's return was not the migration it enabled — it was the negotiating position it created, and that return does not appear on any line of the ledger.

When this is the wrong move

Don't run the full ledger on a cheaply reversible decision. If the component is a library behind a port you could swap in a week, spend an hour and take the boring option — the meeting costs more than either choice. Don't run it when the component is small enough that the evaluation dominates the work: in an enterprise with a procurement process, a forty-hour component can take six weeks to buy, and procurement time is a cost of buying that no ledger line captures. And don't run it at all before you have named the unit: "build or buy our platform" is not a decision, it is a dozen decisions wearing one coat.

Skill: which ledger wins?

Practice on your own code

Pick a system component you're about to build or buy (or already built). Write both ledgers — visible and hidden — for each option. Then state, in one sentence, why the differentiator test lands where it does.

In the lab. The phase-3 checkpoint has you run the build-vs-buy ledger for the carrier-label integration on the returns-resolution service — both columns, the exit cost, and the workaround count against the workflow steps — and then write the one sentence in which the differentiator test lands.

Read and watch deeper

• "Choose Boring Technology", Dan McKinley — the buying-side posture, upgrade tax included.
• "Simple Made Easy", Hickey — the cost-of-complexity frame that makes the ledger honest.
• Software Architecture in Practice, Bass et al. — the quality-attribute trade-off analysis (ATAM) this ledger is a small version of.
• "In Defense of Not-Invented-Here Syndrome", Joel Spolsky — the primary statement of the differentiator rule: build your core competency, buy everything else.
• Watch: ArjanCodes YouTube — search "build vs buy".
• Next: lesson 0028 — Abstraction vs Duplication.
• Reference: Trade-offs — build vs buy, including the signal that you chose wrong.

Run your real ledger past your agent-teacher and let it poke the hidden columns.

Source page: lessons/0027-build-vs-buy.html

Lesson 0028 · Master Designer · Module 1

Abstraction vs Duplication

DRY (lesson 0002) says don't repeat knowledge. The Master's version: duplication is often the cheaper rent — the wrong abstraction is a mortgage you pay forever.

Reading ≈ 9 minPractice ≈ 45 min

Mission tie-in: the second Complexity Trade-Off — where the principles of Phase I become something you balance instead of obey.

Knowledge: two kinds of rent

Duplication costs you on every change — edit N copies. Abstraction costs you on every read — everyone must understand the shape, and if the shape is wrong, every consumer pays. The trade is between these two rents.

Why the wrong abstraction is so expensive:

# the abstraction that guessed wrong
class FeeCalculator:                 # "all fees are one thing" — wrong
    RATE = Decimal("0.01")

    @classmethod
    def fee(cls, amount: Money, kind: str) -> Money:
        if kind == "bank":
            return amount * cls.RATE
        if kind == "wire":
            return amount * cls.RATE
        raise ValueError(kind)

# now wire fees change (clearing house), and the abstraction must be bent:
def fee(self, amount, kind):
    if kind == "wire":
        return amount * Decimal("0.02")      # a branch, because one RATE was wrong

The two fees were never one knowledge (lesson 0002's false DRY) — the abstraction forced them into one shape, and every future divergence has to fight the shape. The duplicated version would have been two obvious functions, each change contained.

Sandi Metz's rule: duplication is far cheaper than the wrong abstraction. And the corollary — the abstraction isn't wrong if it was earned: three occurrences with the same change pattern, then extract. The rule of three is a rent calculation: by the third occurrence, the duplicated copies' change-rent exceeds the abstraction's read-rent.

Worked example: six copies of one authorization check

A platform team runs six independently deployed services. Each carries its own five-line copy of "can this user see this order?" — deliberately, on the reasoning that the services might diverge. They did diverge. Service four was written before a B2B feature introduced account scoping, and its copy never gained the extra clause.

The senior designer's first move is not to count the copies. It is to ask "if these two copies disagree, what is the worst outcome?" Here the answer is cross-tenant data exposure — and that answer, not the copy count, selects the strategy. This is the boundary condition made concrete: everything Sandi Metz says about the wrong abstraction is true of shapes, and an authorization rule is not a shape, it is a fact that must hold everywhere.

The second question separates the two things people conflate: is this shared knowledge, or merely shared shape? Two fee formulas that happen to look alike are shape. One policy about who may read an order is knowledge. Only knowledge must be single.

The obvious fix — extract a shared helper library and have all six services import it — is rejected, and not because it is wrong in principle. It creates a lock-step release dependency across six independently deployed services: a policy change now needs six coordinated deploys in a specific order, and until the last one lands the fleet disagrees with itself anyway (lesson 0033). Sharing code across a deployment boundary is a different trade than sharing code inside one.

What ships makes the knowledge single without making the deployments joint: the policy becomes a contract rather than a library — one authorization decision the services call, or a policy bundle shipped as data and versioned independently of the code that evaluates it. One source of truth, six independent release trains.

The bill for the seven weeks the drift went unnoticed: 340 B2B orders visible to the wrong account, contractual disclosure obligations to two customers, and a quarter of the account team's time on remediation. The engineering fix took twenty minutes. That ratio is the point — the expensive part was never the code, it was that nobody had asked what divergence would cost before choosing to allow it.

Read the table as one rule: the cost of divergence, not the count of copies, chooses the strategy. The rule of three lives in the top row.

When this is the wrong move

Do not prefer duplication for security and correctness invariants, for externally specified shapes you did not guess, or for code duplicated across a boundary where nobody will ever discover the second copy. In those cases pay the abstraction rent deliberately — and if the boundary is a deployment boundary, pay it as data or a contract rather than as shared code, so that "one truth" does not silently mean "one release train".

Skill: whose rent is cheaper?

Practice on your own code

Find an abstraction in your codebase that was extracted before its time (a helper with a kind/type flag, a base class with branchy subclasses). Ask: was it earned by three occurrences with one change pattern? If not, sketch the duplication it should have been.

In the lab. The phase-3 checkpoint gives you the returns-resolution service with two near-identical refund calculations and one eligibility check copied into three call paths. You decide each with the divergence-cost question before the copy count, and justify why the two answers differ.

Read and watch deeper

• "The Wrong Abstraction", Sandi Metz — the essay this lesson is built on.
• The Pragmatic Programmer, Hunt & Thomas — the DRY chapter, read now with its limits visible.
• A Philosophy of Software Design, Ousterhout — ch. 6 "General-Purpose Modules Are Deeper": what an abstraction must earn to be deep.
• Refactoring (2nd ed.), Fowler — ch. 3 "Bad Smells in Code", the Duplicated Code entry, and the rule-of-three note in ch. 2.
• Watch: ArjanCodes YouTube — search "DRY" or "duplication".
• Next: lesson 0029 — Configuration vs Convention.
• Reference: Trade-offs — abstraction vs duplication; glossary — false DRY, rule of three.

Bring a flag-driven helper to your agent-teacher and decide whether it's an earned abstraction.

Source page: lessons/0028-abstraction-vs-duplication.html

Lesson 0029 · Master Designer · Module 1

Configuration vs Convention

Every config knob is a promise that the system varies in that way. Convention says "we already decided" — and removes a class of decisions. Choose by measuring real variation.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: the third Complexity Trade-Off — deciding where the system stays open and where it decides for you.

Knowledge: knobs are promises

Configuration — the system exposes a setting, an env var, a parameter. The cost: every knob must be documented, validated, tested, and understood; every combination is a potential state the code must survive.

Convention — the system decides: "tables named by the model", "endpoints in api/", "config from config.py". The cost: the decision is invisible; newcomers must learn the convention; and when the convention doesn't fit, you fight it.

The deciding question is measured variation:

# convention: one decision, made once, everywhere
class OrderService:
    TIMEOUT_SECONDS = 30        # the team decided; no knob to mis-set

# configuration: real, measured variation — per deployment, per tenant
class OrderService:
    def __init__(self, timeout: timedelta, retries: int) -> None:
        self._timeout = timeout  # differs between prod and a slow partner

The Twelve-Factor rule gives the boundary: settings that vary between deploys (credentials, hosts, feature flags) are configuration. Settings that don't vary are convention — hardcode the decision, don't expose a knob. And the framework lesson (Rails' "convention over configuration"): when you control the whole stack, conventions buy productivity for the 80% case; configuration exists only where the 20% genuinely diverges.

Worked example: forty-one settings and one that mattered

A payments service carries 41 settings. Nobody proposes deleting any, because each one might be needed.

A senior designer does not open the settings file. They dump the effective configuration from production, from staging, and from each tenant, and diff them — because the file is an inventory of possibilities and the diff is evidence about reality. The result: 34 of the 41 are identical everywhere. Of the seven that differ, three differ by accident, left over from hotfixes nobody reverted.

The question they ask next is answered from the config repository's history, not from opinion: "which of these has a human ever deliberately changed, and what happened when they did?" The git log answers in five minutes what a meeting would not settle in an hour.

The tempting response is to document all 41 and add validation. It is rejected because it addresses the wrong risk. Documentation makes a knob explicable and validation makes a bad value fail loudly, but neither shrinks the state space, and the incidents come from combinations of individually valid values that nobody ran together.

Here is what one of those combinations cost. CONNECTION_POOL_SIZE was 5 in one region and 50 everywhere else — drift from a two-year-old hotfix, never intended as a variation. A traffic spike queued checkout requests behind the small pool; p99 latency went from 240 ms to about 9 s for 38 minutes. At roughly 1,900 checkouts an hour and an observed 12% rise in abandonment, that is about 145 lost checkouts at a €62 average basket: near €9,000 of revenue, plus the incident review, plus the two days spent proving it was not the database. The knob had never been deliberately varied. It was a convention wearing a knob's clothes, and the disguise is what made the diagnosis slow.

What ships: delete the 34, keep the 7, give the survivors a typed settings object that fails at startup rather than at first use, and log the effective non-default settings on boot so the next incident responder can see the actual configuration in one line instead of inferring it.

# config.py — the knobs that survived, and the defaults that are conventions
@dataclass(frozen=True)
class Settings:
    database_url: str                 # varies per deploy: genuine configuration
    log_level: str = "INFO"           # varies during incidents: earns its knob
    pool_size: int = 20               # a default that IS the team's decision

    @classmethod
    def from_env(cls, env: dict[str, str]) -> "Settings":
        try:
            url = env["DATABASE_URL"]
        except KeyError:
            raise ConfigError("DATABASE_URL is required") from None
        return cls(
            database_url=url,
            log_level=env.get("LOG_LEVEL", "INFO"),
            pool_size=int(env.get("POOL_SIZE", 20)),
        )

def log_effective(settings: Settings) -> None:
    defaults = Settings(database_url=settings.database_url)
    changed = {f.name: getattr(settings, f.name) for f in fields(Settings)
               if getattr(settings, f.name) != getattr(defaults, f.name)}
    logger.info("effective non-default settings: %s", changed or "none")

One more knob deserves naming: the feature flag. A flag is configuration with a scheduled death — it exists to carry a transition and it should be removed when the transition ends. Without a removal date it becomes a permanent branch in the code and a permanent row in the test matrix, and the branch that was never meant to survive is the one running in production two years later.

When this is the wrong move

Expose the knob anyway when your users are not your team: a library or platform that hardcodes your convention forces its users to fork it, and the seam you saved costs them a maintenance burden. Expose it for genuinely per-tenant behaviour. And expose it for incident controls — kill switches, log levels, rate limits, circuit-breaker thresholds — where the knob's value is measured in recovery time rather than in variation. A knob that has never been turned but can be turned in thirty seconds during an outage is earning its keep in a currency the variation test does not measure.

Skill: knob or decision?

Practice on your own code

List the config settings in your system. For each, answer: does it vary per deployment or per tenant? If it doesn't, convert it to a convention — hardcode the decision and delete the knob. Grep for settings read nowhere and delete those too.

In the lab. The phase-3 checkpoint has you diff the effective configuration of the returns-resolution service across its environments, delete every setting that has never varied, and give the survivors a typed settings object that fails at startup.

Read and watch deeper

• The Twelve-Factor App — Config: the canonical statement of what belongs in configuration.
• "Convention over Configuration", The Rails Doctrine — the strongest statement of the trade, from the framework that made it a movement.
• "Feature Toggles", Pete Hodgson on martinfowler.com — the taxonomy of flags by lifespan, and why a toggle without a removal plan becomes permanent configuration.
• Software Architecture in Practice, Bass et al. — configurability as a quality attribute with a price.
• Watch: ArjanCodes YouTube — search "configuration" or "12 factor".
• Next: lesson 0030 — Generality vs Specificity.
• Reference: Trade-offs — configuration vs convention; glossary — config graveyard.

Bring your settings inventory to your agent-teacher and run the variation test on every knob.

Source page: lessons/0029-configuration-vs-convention.html

Lesson 0030 · Master Designer · Module 1

Generality vs Specificity

A general module is a bet on the future; a specific module is a fact about today. Ousterhout's law: generality is earned when it makes the specific case simpler — not when it adds cases.

Reading ≈ 8 minPractice ≈ 40 min

Mission tie-in: the last Complexity Trade-Off — and the one that decides how much machinery every module carries.

Knowledge: generality that pays vs generality that costs

Two kinds of generality:

1. Earned generality — the module solves today's case through a shape that naturally covers tomorrow's. It makes the current code simpler because the general interface is cleaner than the specific one.
2. Speculative generality — parameters, hooks, and abstractions for cases that don't exist. It taxes every read of the current code to pay for futures that may never arrive.

# speculative: a "pipeline" framework for one transformation
class Transformer:
    def __init__(self, steps: list[Step], concurrency: int = 1,
                 retry: RetryPolicy | None = None, metrics: Metrics | None = None):
        ...

Transformer(steps=[normalize], concurrency=1, retry=None, metrics=None).run(data)

# earned: the general name covers the specific case, no extra machinery
def transform(data: list[dict]) -> list[dict]:
    return [normalize(row) for row in data]

The specific version is also the general one: any future step is a new function, composed (lesson 0016). The framework added configuration (lesson 0029), concurrency, and retries — none of which the one case needs.

The test, from Ousterhout: does the generality make the current problem simpler? If the general module is harder to use for today's case than the specific one would be, the generality is speculative. Generalize only when the second use case is real — then the general shape is usually visible (rule of three again).

Worked example: the export framework that was bypassed

Product asks for a CSV export of returns. The engineer proposes an Exporter framework: pluggable formats, streaming, configurable columns, so that "adding XLSX later is one class".

The senior designer's first move is to sort the decisions by reversibility, because that is the axis on which this trade actually turns. Three decisions are hiding in one ticket. The function signature has one caller and is free to change. The file format is written, downloaded and forgotten, so nobody is holding an old one. The stored per-tenant export configuration is neither: it is persisted, so every change to its shape is a migration across every tenant. The question they ask is "which of these can I not take back?" — and the answer is only the third.

So the framework is rejected, with a number attached. It is roughly 380 lines and five new concepts, read by everyone who touches export for as long as it exists. The second format arrived nine months later — and wanted a workbook rather than a stream of rows, so it did not fit the framework's row-at-a-time assumption anyway. The machinery was paid for over nine months and then bypassed. That is the characteristic failure of speculative generality: not that the future never came, but that it came in a shape the guess did not cover.

What shipped was one 30-line function. When XLSX arrived it became a second function and a two-line dispatch — about 75 lines in total, with the two formats' differences visible rather than dissolved into a shared shape they do not share (lesson 0028):

def export_returns(rows: list[ReturnRecord], fmt: str) -> bytes:
    if fmt == "csv":
        return _to_csv(rows)          # a stream of rows
    if fmt == "xlsx":
        return _to_xlsx(rows)         # a workbook: genuinely a different shape
    raise UnsupportedFormat(fmt)

Two branches and two honest functions. When a third format arrives and all three share a real step — say, redacting personal fields before writing — extract that step. Not the framework.

The rule the team wrote down afterwards is the one worth stealing: generalise code on the second real case; design persisted shapes and public contracts for the third. The two halves differ only in what it costs to be wrong.

When this is the wrong move

Pay for generality up front at published boundaries — public APIs, wire formats, persisted schemas, plugin contracts — where the cost of being wrong is everyone else's migration rather than your afternoon. Pay for it when a second consumer already exists and is dated. And accept that a library has a larger generality budget than an application, because serving callers you have not met is its whole job: the same optional parameter that is speculative in your service is the reason someone can adopt your package without forking it.

Skill: earned or speculative?

Practice on your own code

Find a module with parameters or machinery no caller uses (defaults never overridden, hooks never hooked, config from lesson 0029 that's always the same). Remove the machinery — make the specific case the whole module — and check that every caller got simpler.

In the lab. The phase-3 checkpoint gives you the returns-resolution service with a configurable "resolution strategy" registry holding exactly one strategy. You strip the machinery, then argue the counter-case: which one of its shapes is persisted, and therefore should keep its version field.

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 6 "General-Purpose Modules Are Deeper": the simplification test this lesson uses.
• "Simple Made Easy", Hickey — the distinction between complexity carried and complexity deferred.
• Refactoring, Fowler — the "speculative generality" smell entry.
• "Hyrum's Law" — the one-sentence primary statement of why a published interface is not cheap to narrow later, whatever the contract says.
• Watch: ArjanCodes YouTube — search "YAGNI" or "simplicity".
• Next module: lesson 0031 — System Trade-Offs.
• Reference: Trade-offs — generality vs specificity; glossary — speculative generality.

Bring a never-overridden parameter to your agent-teacher and de-generalize it together.

Source page: lessons/0030-generality-vs-specificity.html

Lesson 0031 · Master Designer · Module 2

Synchronous vs Asynchronous Systems

Sync is simple until it isn't fast; async is fast until it isn't simple. The Master's move: choose per workflow, not per system — and know the failure modes you're buying.

Reading ≈ 8 minPractice ≈ 25 min

Mission tie-in: the first System Trade-Off — where lesson 0025's event-driven machinery becomes a measured decision instead of a default.

Knowledge: the ledger of the two modes

The deciding question is about the workflow: does the caller need the result to continue? Confirming an order needs the payment result now — sync. Sending the confirmation email doesn't gate anything — async. Most systems are a mix:

def place_order(cart: Cart, gateway: PaymentGateway) -> Order:
    charge = gateway.charge(cart.total, cart.token)      # sync: caller needs it
    order = order_service.confirm(cart, charge.id)
    bus.publish(OrderConfirmed(order))                   # async: reactions don't gate
    return order

The async failure modes you must be able to name before you adopt it: ordering (handlers may see events out of order), at-least-once delivery (idempotency needed), dead letters (what happens when a handler keeps failing), and observability (the flow isn't in one stack trace). If you cannot answer "what happens when the handler dies mid-way?" — the workflow isn't ready for async.

Worked: one step, reasoned out loud

A returns flow: the customer files a return, the service decides eligibility, then a carrier API mints a shipping label. Volume is 3,000 requests a day. The carrier's label endpoint answers in 240 ms at p50 and 2.4 s at p99, and fails about 0.3% of the time. Where does the sync/async boundary go?

The first thing a lead looks at is not the latency graph. It is the customer's next action. Eligibility decides what the customer does next — pack the item, or call support — so it gates. The label does not: the customer's next action is to wait for an email, and a label that arrives ninety seconds later changes nothing they do. That one question, what does the caller do differently with this result?, settles more sync/async arguments than any percentile.

# the shape that follows from the question
def request_return(req: ReturnRequest, bus: Bus) -> ReturnCase:
    case = policy.decide(req)             # sync: the customer acts on this now
    bus.publish(ReturnApproved(case.id))  # async: label, restock, email react
    return case

# the rejected shape: tidy, straight-line, and on the customer's path
def request_return_inline(req: ReturnRequest, carrier: CarrierApi) -> ReturnCase:
    case = policy.decide(req)
    label = carrier.create_label(case)    # p99 2.4 s, 0.3% failure, not gating
    return case.with_label(label)

The alternative the lead rejects is the tidy one: both calls inline, so the response carries the label and the code reads as a straight line. It is rejected on arithmetic. 0.3% of 3,000 is nine customers a day told their return failed when the return had in fact succeeded — eligibility was already decided; only the label step broke. Their recovery is to refile, which produces exactly the support contact the work was meant to remove.

The mirror-image move is rejected too: making eligibility async as well, "so everything is uniform". Uniformity is not a force. Async eligibility turns a two-second answer into a case the customer must come back for, raises the contact rate rather than lowering it, and buys the team a status-polling screen nobody asked for.

The consequence shows up over the following year, not on launch day. In the event-shaped version, every new reaction — restock, fraud scoring, warehouse pre-notice — is one more subscriber to a fact that has already happened, and the customer's path stays one call long. In the inline version, each new reaction adds a call to the critical path: after four features the p99 is the sum of five p99s, and any one of those five dependencies can now fail a return that the business had already approved.

When this is the wrong move

The sync-first default is the wrong starting point in three recognisable situations. When a step fans out to several downstream systems, sync makes you inherit the union of their downtime — five 99.9% dependencies is a worse promise than any of them made. When the callee is a third party whose latency you do not control and whose contract gives you no percentile, a synchronous call exports their bad day onto your customers. And when the work is inherently bulk — reprocessing 40,000 rows, regenerating every label — a synchronous request times out before correctness is even in question.

There is also a team-shaped exception. If the organisation already runs a bus with dead-letter monitoring, replay tooling and correlation ids in every log line, the marginal cost of one more consumer is near zero, and the "async is complex" argument is quoting a price the team has already paid. Judge the machinery you actually have, not the machinery a blog post assumes.

In the lab: the companion Phase 3 exercise hands you a returns service that awaits a carrier call inside the customer's request. You classify each step by whether the caller gates on it, move the non-gating work behind an event, and answer the four failure questions before the change counts as done.

Skill: which mode for this workflow?

Practice on your own code

List the workflows in your system. For each, mark: does the caller gate on the result? Where failure modes exist (ordering, duplicates, dead handlers), write the answer to "what happens if the handler dies mid-way?" — on paper, before you build more async.

Read and watch deeper

• Designing Data-Intensive Applications, Kleppmann — ch. 11 "Stream Processing": async systems and their guarantees, rigorously.
• "What Do You Mean by Event-Driven?", Fowler — the vocabulary for choosing between the modes.
• Release It!, Nygard — 2nd ed., ch. 4–5 (stability antipatterns and patterns): where the availability multiplication and its circuit breakers come from.
• Enterprise Integration Patterns, Hohpe & Woolf — the messaging vocabulary (channel, dead letter, idempotent receiver) this lesson's inventory uses.
• Watch: ArjanCodes YouTube — search "async" or "event driven".
• Next: lesson 0032 — Consistency vs Availability.
• Reference: Trade-offs — synchronous vs asynchronous; glossary — idempotent, dead-letter queue, correlation id.

Walk your workflow list past your agent-teacher and classify each one together.

Source page: lessons/0031-sync-vs-async-systems.html

Lesson 0032 · Master Designer · Module 2

Consistency vs Availability

When the network fails, a distributed system must choose: answer with possibly-stale data, or wait for the truth. The Master's skill is choosing per operation — not per database.

Reading ≈ 9 minPractice ≈ 25 min

Mission tie-in: the second System Trade-Off — where lesson 0011's invariants meet the real world of partitions and timeouts.

Knowledge: the choice under failure

CAP says: during a partition (network failure between nodes), you choose between consistency (every read sees the last write) and availability (every request gets an answer). The catch — Kleppmann's correction: almost no system is purely one or the other, and CAP is a framing, not a product picker. The real question per operation: what does a stale answer cost, and what does a timeout cost?

The engineering that makes this a design instead of a gamble:

• Decide at the data boundary: what must be strongly consistent (a balance, a reservation) vs what tolerates eventual consistency (a stock hint, a cache, a search index).
• Make staleness visible: "as of 2 minutes ago" — an honest UI beats a silently stale one.
• Prefer constraints that work offline: an idempotency key on writes (charge once, even if retried) buys a lot of the safety without sacrificing availability.
• Contain the strong-consistency core: the smaller the always-consistent surface (lesson 0012's aggregates), the less the system pays for it.

Both of the middle two are code you can point at. The idempotency key buys availability without giving up write safety:

def charge(self, amount: Money, token: str, key: IdempotencyKey) -> ChargeId:
    existing = self._charges.find_by_key(key)
    if existing is not None:
        return existing.id            # the retry returns the first answer
    charge_id = self._gateway.charge(amount, token, key)
    self._charges.record(key, charge_id)
    return charge_id

The detail that makes this work: the key is generated by the caller and reused across every retry of the same intent. A client that mints a fresh key per attempt gets two charges, and the mechanism has bought nothing — the safety lives in the caller's discipline as much as in the server's table.

And staleness, made visible instead of silent:

@dataclass(frozen=True)
class StockHint:
    quantity: int
    as_of: datetime              # the UI can say "as of 2 minutes ago"

A number with a timestamp is an honest answer. The same number without one is a promise the system cannot keep — and the customer discovers that at checkout instead of on the product page.

Worked: the same call, two different answers

A returns service checks eligibility by reading the order system, which is authoritative for orders. The check needs two facts: when was this ordered (the 30-day window) and has it already been refunded. One API call, so most teams treat it as one consistency decision. The order system degrades for 40 minutes. What should the returns service do?

The first thing a lead looks at is not the endpoint — it is each field's mutability and the action it authorises. The order date is immutable: once written it never changes, so a copy from an hour ago is as true as a copy from a millisecond ago. The refund status is mutable and it authorises money leaving the company: a stale "not yet refunded" is the precise input that produces a second refund. Same call, same partition, opposite answers.

def check_eligibility(order_id: str, orders: OrderReader) -> Eligibility:
    snapshot = orders.local_snapshot(order_id)         # date: immutable, cache freely
    if not snapshot.within_days(30):
        return Eligibility.rejected("outside the window")
    try:
        status = orders.refund_status(order_id, max_staleness=timedelta(0))
    except Unavailable:
        return Eligibility.deferred("decision within 4 hours")   # the third answer
    return Eligibility.approved() if status.none_yet else Eligibility.rejected("already refunded")

The alternative a lead rejects is the one that sounds like availability: cache the whole order response for five minutes so the flow keeps working. Price it. At 3,000 returns a day, a 40-minute degradation covers about 83 requests; roughly 4% are re-filings of a request the customer already made, so about three of them can be approved twice. At an average refund of €62 that is €186 — trivial money, and entirely the wrong number to look at. Each duplicate is a manual clawback, twenty minutes of an agent's day, an awkward conversation, and a measurable move in the fraud-loss guardrail the initiative promised not to worsen.

The opposite alternative is rejected too: block every check until the order system returns. Those 83 customers see a spinner and then an error. If only half of them contact support — conservative, since the baseline contact rate for returns is 41% — that is 34 contacts at roughly six minutes each, 3.4 agent-hours bought in exchange for a strictness the date field never needed.

Which is why the honest design has a third answer. "Stale or timeout" is a false binary produced by assuming every request must resolve now. A deferred case — "received, decision within four hours" — keeps the promise the outcome actually made, needs no stale read, and blocks no one. It comes with its own arithmetic: 83 deferred cases in one outage would swamp a manual review queue capped at 50 a day, so deferrals must route to an automatic retry once the dependency recovers, with the agent queue as the exception path, not the default.

Over a year the difference is which conversation the team keeps having. With per-field decisions written down, a new field arrives and someone asks "immutable or authorising?" — a two-minute conversation. With one blanket TTL on the whole response, every new field silently inherits a staleness budget nobody chose for it, and the next duplicate-refund incident is discovered by finance, not by monitoring.

When this is the wrong move

Per-operation reasoning is overhead you should decline in three cases. A single-node, single-region system has no partition to reason about: the ceremony buys nothing, and the cache you add "for availability" only adds a way to be wrong. A legally constrained read — a regulated balance, a consent record, a credit decision — is not a cost comparison; the stale answer is not cheaper, it is prohibited. And a user reading back their own action is a special case worth knowing: a technically defensible stale read of a change they just made reads as a broken product. Session (read-your-writes) consistency for that one caller is far cheaper than making the whole operation strongly consistent for everyone.

In the lab: the companion Phase 3 exercise gives you a returns service that caches an authoritative read wholesale and auto-approves from it. You separate the immutable fields from the authorising ones, add the deferred third answer, and prove with a test that a duplicate submission during a simulated outage cannot produce a second approval.

Skill: which way does this operation lean?

Practice on your own code

List your system's read operations. For each, write the two cost sentences: "a stale read costs…" and "a timeout costs…". Mark the lean. Then check: where staleness is served, is it visible to the user?

Read and watch deeper

• "Please stop calling databases CP or AP", Kleppmann — the framing this lesson's per-operation choice comes from.
• Designing Data-Intensive Applications, Kleppmann — ch. 5 (replication), 8 (the trouble with distributed systems), 9 (consistency and consensus).
• Release It!, Nygard — 2nd ed., ch. 5: graceful degradation, the "third answer" this lesson uses.
• Daniel Abadi, "Problems with CAP, and Yahoo's little known NoSQL system" — the original PACELC argument: consistency also costs latency when there is no partition at all.
• Watch: ArjanCodes YouTube — search "CAP theorem" or "eventual consistency".
• Next: lesson 0033 — Coupling vs Coordination.
• Reference: Trade-offs — consistency vs availability; glossary — eventual consistency, idempotency key.

Bring your read-operation ledger to your agent-teacher and cost the failures together.

Source page: lessons/0032-consistency-vs-availability.html

Lesson 0033 · Master Designer · Module 2

Coupling vs Coordination

Decouple two systems and they stop breaking each other — but someone must keep them aligned. Conway's law says the alignment cost follows team boundaries. This is the trade where people are a force.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the third System Trade-Off — where architecture stops being code-only and starts being about teams.

Knowledge: the two costs

Coupling — two components share a contract: an interface, a schema, a synchronous call. When one changes, the other must change with it. Cost: change amplification (lesson 0006) — a deploy on one side is a coordinated deploy on both.

Coordination — two components are independent, but someone must keep them aligned: versioned contracts, migration windows, compatibility rules, message schemas with both-ways guarantees. Cost: an ongoing conversation that never ends.

You cannot have neither. Zero coupling with zero coordination is two systems that stopped agreeing. The design question is which currency you pay in:

• Coupling pays when the contract is stable: a shared library for a domain concept used by two services, versioned together, deployed together.
• Coordination pays when the sides evolve at different speeds: an event contract (lesson 0025) where consumers tolerate unknown fields and producers keep compatibility.

Conway's law is the tiebreaker: systems mirror the communication structure of the people who build them. A boundary that separates two teams is a coordination boundary whether you design it or not — design it deliberately. And team topologies adds the human cap: every boundary is cognitive load on the teams that must hold both sides of it in their heads.

Coordination only exists if someone writes it down. Here it is as code both sides can run:

# the published contract — the coordination artifact, versioned
@dataclass(frozen=True)
class OrderConfirmedV1:
    order_id: str
    confirmed_at: datetime

def parse_order_confirmed(payload: dict) -> OrderConfirmedV1:
    return OrderConfirmedV1(                        # a tolerant reader
        order_id=payload["order_id"],               # required: removing it breaks us
        confirmed_at=datetime.fromisoformat(payload["confirmed_at"]),
    )                                               # unknown keys: ignored, on purpose

Three rules turn a schema into a contract: producers may add fields and never remove or repurpose them; consumers ignore fields they don't recognise; both sides support N−1 versions for a stated window. A consumer-driven contract test in each team's suite makes those rules fail the build rather than fail in production.

Written down and tested, that is coordination doing its job. Left in a chat thread — "we agreed the field is optional" — it is coordination debt: person-dependent, undiscoverable, and payable at 3 a.m.

Worked: pricing the boundary instead of arguing about it

Checkout (six engineers) calls warehouse (five engineers) for a stock check, synchronously, against a shared schema with no versioning. Every checkout release waits for a warehouse release: two release trains a month, and each one costs two people roughly three hours of sequencing, verification and Slack — 12 person-hours a month, 144 a year, about three and a half person-weeks burned on a runbook line that says "deploy warehouse first".

The first thing a lead looks at is not the diagram; it is git log on the contract. How often has this schema actually changed? Eleven times in twelve months. That number is the whole decision. At eleven changes a year the coupling multiplier is live and the bill is real, so the machinery pays: a written compatibility contract plus consumer-driven tests costs about three days to set up and two hours per subsequent change — 24 hours once, plus 24 hours a year — against 144 hours a year saved. It breaks even in roughly four months. Had the answer been "changed once, in 2023", the same machinery would have been an expensive way to make a stable thing look modern.

The alternative the lead rejects is the popular one: "split them into proper microservices so the teams are decoupled". Rejected because the coupling is not in the deployment unit — it is in the shared schema and the shared concept. Splitting the process without splitting the data ownership adds a network hop, a retry policy and a new failure mode to exactly the same negotiation. Deployment independence is not change independence, and only the second one was costing 144 hours.

The second rejected alternative is subtler: keep the synchronous call but "just version the endpoint". Versions with no stated support window are names, not commitments. Without "we support N−1 for 90 days" written down and tested, both sides still deploy together — you have added ceremony to the runbook and removed nothing from it.

A year on, the difference is visible in what a new engineer has to know. With the contract written and tested, warehouse can ship a field on a Tuesday and checkout finds out from the test suite, not the incident channel; onboarding reads one document. Without it, the alignment lives in the heads of two long-serving engineers, and the day one of them leaves is the day you discover which rules were never rules at all.

When this is the wrong move

Do not buy coordination machinery for a boundary inside one team. When the same six people own both sides and ship on one train, the versioned event contract, the compatibility window and the consumer-driven test suite are ceremony around a conversation that already happens at standup — and worse, they make the cheap move (change both sides in one commit) feel illegal.

Nor should you freeze a contract early. In the first months of a product the model is wrong in ways you cannot yet name; a compatibility document written then locks in that wrongness and charges you a migration every time you learn something. Couple hard, refactor freely, and write the contract when the concept stops moving — the signal is usually a second consumer you do not control.

In the lab: the companion Phase 3 exercise gives you a returns service whose agreement with the order system exists only as field names copied between two modules. You write the compatibility rules down, add a contract test that fails when a required field disappears, and decide out loud which side pays when the two disagree.

Skill: which currency do you pay?

Practice on your own code

Map your system's service boundaries onto your team structure. For each boundary: who changes on each side, who must talk when a contract changes, and is that conversation written down anywhere? The gaps you find are coordination debt — write the compatibility contract.

Read and watch deeper

• Team Topologies, Skelton & Pais — ch. 3–4: cognitive load as the cap on how many boundaries a team can hold, and the four interaction modes.
• "Consumer-Driven Contracts", Robinson on martinfowler.com — the test that turns an agreement into something a build can fail on.
• Conway's law — the original observation, read as a design principle.
• Designing Data-Intensive Applications, Kleppmann — ch. 11: the coordination guarantees (at-least-once, ordering) behind event contracts.
• Watch: ArjanCodes YouTube — search "conway's law" or "team boundaries".
• Next: lesson 0034 — Performance vs Maintainability.
• Reference: Trade-offs — coupling vs coordination; glossary — tolerant reader.

Map your boundaries and teams with your agent-teacher and find the undocumented contracts.

Source page: lessons/0033-coupling-vs-coordination.html

Lesson 0034 · Master Designer · Module 2

Performance vs Maintainability

The fast version is usually the ugly version. The Master's move: keep the system clean, measure, and hide the few hot paths behind deep modules — so the ugliness has a small address.

Reading ≈ 8 minPractice ≈ 25 min

Mission tie-in: the last System Trade-Off — where premature optimization and cargo-cult caching both get their verdicts.

Knowledge: clean until measured

The sequence that keeps both forces happy:

1. Build clean. Correct, clear, well-bounded code (everything Phase I taught). Performance is not yet a requirement — it's a guess.
2. Measure. A profiler, a load test, a real metric — not "this feels slow". The requirement is a number: "the checkout must return in 300ms p95".
3. Find the hot path. Usually 2–3% of the code does 95% of the work. Only those places trade maintainability for speed.
4. Hide the trade behind a deep module. The fast implementation lives behind the same clean interface — caches, indexes, and cleverness contained where no one else must read them.

# the interface stays clean:
class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...

# the hot path gets its speed, hidden:
class CachedOrderRepository:
    def __init__(self, inner: OrderRepository, cache: Cache) -> None:
        self._inner = inner
        self._cache = cache

    def get(self, order_id: str) -> Order:
        cached = self._cache.get(order_id)
        if cached is not None:
            return cached
        order = self._inner.get(order_id)
        self._cache.set(order_id, order)
        return order

The domain never learns about the cache (lesson 0023's ports at work). The fast-but-complex code has one address: the adapter. Knuth's verdict stands: premature optimization is the root of much evil — because it spends maintainability before the measurement exists. But the measured optimization, contained behind a boundary, spends a little maintainability for a lot of performance, deliberately.

Worked: the same optimisation, two opposite verdicts

A nightly reconciliation job takes four hours on eight vCPUs. An engineer proposes rewriting its inner loop — three days of work, and the result is code that only they will enjoy reading — for a measured 20% saving.

The first thing a lead does is convert both sides into the same unit. Twenty per cent of four hours is 48 minutes a night: 8 vCPU × 0.8 h = 6.4 vCPU-hours, at roughly €0.04 per vCPU-hour, about $0.26 a night, $93 a year. Three days of loaded engineering time is roughly €1,920, plus a permanent readability tax on whoever debugs the job at 2 a.m. Payback: about twenty years. The proposal is not wrong about the speed-up; it is wrong about the scale, and no amount of profiling would have revealed that, because the profiler measures the job, not the business.

Now change one fact. The same 20% applied to a fleet of 400 always-on instances is 3,504,000 instance-hours a year; at €0.09 an hour that is €315,360, so 20% is about €63,000 a year. The same three days now pays for itself in under a fortnight, and a lead who refused it on principle ("premature optimisation") would be wrong by two orders of magnitude. Identical code change, identical measurement, opposite verdict — decided entirely by the multiplier the code sits behind.

The alternative a lead rejects in both cases is the generalising one: "the ORM is slow, let's drop it across the service". The profile said 78% of one endpoint's time went into serialising a 5,000-row response. That finding does not travel: the other 140 endpoints return a handful of rows each, so raw SQL buys them nothing measurable while charging every one of their future readers. Fix the one path, behind the one interface, and leave the other 140 alone.

The consequence over time is the thing seniors actually protect. Maintainability is what buys the option to optimise later: an implementation hidden behind a port can be replaced in an afternoon, whereas a data model that has leaked into forty call sites cannot be replaced at all without a migration project. "We will optimise it later" is only true if someone kept the boundary that makes later possible.

When this is the wrong move

"Clean first, measure, then optimise the few hot paths" assumes a cold majority exists. Three situations where it does not: a compute kernel, codec or simulation loop where essentially all of the time is in one place and the memory layout must be chosen before the first line is written; an embedded or battery-constrained target where the budget is fixed by physics rather than by preference; and any deadline that is part of the contract — a fraud check that must answer inside the authorisation window is not slow-but-correct, it is wrong. In those cases performance is a quality-attribute scenario with a number attached from day one (lesson 0043), and the design is built around it rather than cleaned up afterwards.

In the lab: the companion Phase 3 exercise puts a hand-rolled cache and a per-row lookup into the same returns service. You profile it against a realistic case volume, find which of the two the numbers actually accuse, and either delete the cache or hide the fix behind the existing interface — with the measurement recorded next to the change.

Skill: where does the speed live?

Practice on your own code

Find the "optimization" in your codebase — the cache, the micro-optimized loop, the clever data structure. Ask: what number justified it? If there is no number, delete it or write the number that would justify it. If there is a number, confirm the fast code is hidden behind a clean interface.

Read and watch deeper

• Designing Data-Intensive Applications, Kleppmann — ch. 1 (reliability, scalability) and ch. 12: what performance actually means and how to measure it.
• A Philosophy of Software Design, Ousterhout — ch. 20 "Designing for Performance": keep the clean design, then optimize the hot paths.
• Knuth, "Structured Programming with go to Statements", ACM Computing Surveys 6(4), 1974, pp. 261–301 — the premature-optimization quote in its original context, three sentences that are almost always cut short.
• Brendan Gregg, Systems Performance — 2nd ed., ch. 2: workload characterisation, and why the workload is the measurement.
• Watch: ArjanCodes YouTube — search "profiling" or "optimization".
• Next module: lesson 0035 — Evolution Trade-Offs.
• Reference: Trade-offs — performance vs maintainability; Design Principles — deep modules.

Bring a cache or clever loop to your agent-teacher and hunt for its justifying number.

Source page: lessons/0034-performance-vs-maintainability.html

Lesson 0035 · Master Designer · Module 3

Stability vs Speed of Change

Stable systems resist change; fast systems court it. The master's toolkit — feature flags, strangler fig, branch by abstraction — exists to buy both at once.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the first Evolution Trade-Off — where the techniques from lessons 0009 and 0025 become instruments of organizational speed.

Knowledge: speed is a design property

The naive framing: stable or fast, pick one. The reframe: change speed is a property of the design, not a personality. A system changes fast when changes are small, local, and reversible (Phase I's whole point). A system changes slowly when every change is big, cross-cutting, and risky.

The three instruments that buy both stability and speed:

1. Feature flags — ship the code dark; the behavior's visibility, not its presence, is the deploy. Roll back by flipping a flag, not reverting a release.
2. Strangler fig (lesson reference: patterns sheet) — replace a system incrementally: new behavior routes to the new implementation; the old one shrinks slice by slice. The system stays stable while it's being replaced.
3. Branch by abstraction — insert an interface over a component, migrate all users to it, swap the implementation behind it. Every step is a small, mergeable, reviewable change.

# feature flag: the code is in production; the behavior waits
def checkout(cart: Cart, flags: FeatureFlags) -> Order:
    if flags.is_enabled("new_pricing"):
        return new_pricing_checkout(cart)      # dark: no users see it yet
    return legacy_checkout(cart)

# branch by abstraction: every consumer migrates to the seam first
class StockService(Protocol):                  # the seam
    def reserve(self, sku: str, qty: int) -> None: ...
# then: legacy impl swapped for new impl behind the same seam

The honesty clause: flags and seams are machinery — each carries complexity (lesson 0029's knob cost). A flag that lives forever is config debt; a seam for a component that never changes is indirection. The master removes the machinery when the transition is done.

There is a fourth instrument, for the change the other three cannot touch — data:

# expand / contract: never rename a column in one step
# 1. expand    add `delivery_address`; write BOTH; keep reading `address`
# 2. backfill  copy the historical rows, in batches, idempotently
# 3. switch    read `delivery_address`; still writing both
# 4. contract  stop writing `address`; only then drop it

Four deploys instead of one, and every single one is reversible. The one-step rename is the change that looks fastest and is the only one you cannot roll back once the first write lands — the exact profile lesson 0037 calls irreversible.

Worked: why the one-step rename is the expensive one

The returns service stores a shipping address in address; a new carrier integration needs it split out as delivery_address. The table holds 4.2 million rows. An engineer proposes the obvious thing: a migration that renames the column, deployed with the code that uses the new name.

The first question a lead asks is not "how long does the migration take?" but "what is running while it runs?" Deploys roll: six instances, roughly thirty seconds each, so for about three minutes half the fleet writes address and half writes delivery_address. Even at two requests a minute, that is a handful of returns whose address lands in a column the other half of the fleet is no longer reading — and you will not find them now. You will find them weeks later, by their absence, when a warehouse agent cannot print a label.

The second question is what an undo looks like. The four-step version is reversible at every step: stop the rollout, and the old column is still there, still written to. The one-step rename is reversible only until the first new write lands, after which restoring means a backup restore and reconciliation of everything that happened in between — the change has quietly moved from lesson 0037's reversible class into the irreversible one, in exchange for saving three deploys.

The alternative the lead rejects is the compromise that feels responsible: a 3 a.m. maintenance window. Price it. Backfilling 4.2 million rows in batches of 5,000 at about two seconds a batch is 840 batches, roughly 28 minutes — before verification, and before anything goes wrong. So the window is either too short to finish or long enough that its own failure is the incident. The maintenance window buys the illusion of atomicity and charges for it in the one currency that matters at 3 a.m.: nobody rested is making the rollback decision.

The four-step version is three more deploys and a backfill script, perhaps a day of work spread across a week, during which the service never stops being correct. A year later the difference is cultural rather than technical: teams that have done expand/contract twice stop treating schema changes as events, and schema changes stop being the reason a release is delayed to a Thursday.

When this is the wrong move

Slicing is not free, and there are changes where the machinery costs more than the risk it removes. A one-line copy fix behind a flag is theatre. A two-week migration that needs forty hours of flag plumbing has spent its own budget. And a rewrite is occasionally the honest answer — not when the code is ugly, but when the constraint is not code at all: a platform going end-of-life, a licence expiring, a compliance regime the old design cannot satisfy, or a domain that changed so much that preserving the old behaviour is the mistake rather than the goal.

The other counter-case is self-inflicted. A codebase with thirty long-lived flags is not agile; it is a configuration graveyard where no two environments run the same program and no one can say what production actually does. When flags outnumber transitions, the instrument has become the instability, and the fix is a deletion sprint rather than another flag.

In the lab: the companion Phase 3 exercise asks you to change the shape of a field the returns service already persists, without a maintenance window. You plan the expand, backfill, switch and contract steps, and demonstrate that stopping after any one of them leaves the service correct.

Skill: which instrument, when?

Practice on your own code

Find a change you're about to make that feels "big". Split it: what's the smallest invisible slice (flag), the smallest structural seam (branch by abstraction), or the smallest routed slice (strangler)? Write the slice list — then do the first slice.

Read and watch deeper

• "Strangler Fig Application", Fowler — the incremental-replacement pattern.
• "Technical Debt", Fowler — the loan framing for what flags and shortcuts accumulate.
• Working Effectively with Legacy Code, Feathers — ch. 1–2: changing software without breaking it, slice by slice.
• Monolith to Microservices, Newman — ch. 3: strangler fig, branch by abstraction and parallel run, with their failure modes.
• Accelerate, Forsgren, Humble & Kim — ch. 2 and 4: the measured relationship between small batches, deploy frequency and change-failure rate.
• Next: lesson 0036 — Isolation vs Integration.
• Reference: Trade-offs — stability vs speed of change; Patterns — strangler fig, branch by abstraction, expand / contract, feature flag.

Bring your big change to your agent-teacher and slice it together before writing code.

Source page: lessons/0035-stability-vs-speed-of-change.html

Lesson 0036 · Master Designer · Module 3

Isolation vs Integration

Isolated parts evolve independently; integrated parts stay consistent. The bounded context is the master's unit of this trade: isolation where meanings differ, integration where they can't.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the second Evolution Trade-Off — lesson 0009's boundaries, now at the scale of whole contexts and their shared meanings.

Knowledge: the context is the unit

Isolation — a context owns its model, its schema, its vocabulary. It evolves at its own speed; other contexts can't break it, and it can't break them. Cost: duplicated concepts across contexts (lesson 0028's duplication — but here it's earned: the "customer" in sales and the "customer" in support are genuinely different knowledge).

Integration — contexts share a model, a schema, an API. Consistency is guaranteed; divergence is impossible by construction. Cost: change amplification — one context's change ripples through all the others (lesson 0006 at system scale).

The deciding test is meaning, not overlap. When two teams use the word "order" to mean the same thing with the same rules, integration is honest. When their rules differ — sales' "confirmed order" vs warehouse's "picking order" — they are two concepts wearing one name, and forcing a shared model means every change negotiates the difference forever.

# integration where meaning is shared: a contract both sides truly share
class OrderConfirmed(Event):      # both contexts agree on this fact
    ...

# isolation where meaning diverges: each context owns its vocabulary
# sales.Order has "confirmed", warehouse.PickingOrder has "ready to pick"
# they meet only through the event — the anti-corruption boundary

The instruments: bounded contexts (isolation drawn at meaning), an anti-corruption layer (the adapter that translates between two vocabularies — lesson 0008's Adapter at context scale), and shared kernels (the small, stable set of concepts that genuinely must be shared, integrated on purpose).

Worked: one word, three sets of rules

A retailer has one returns table with 34 columns, written by three teams. Support treats a return as a case: notes, reasons and outcomes stay editable, because agents amend them while talking to the customer. Finance treats it as a refund transaction: once the refund posts, the record is immutable, because the tax position depends on it. The warehouse treats it as an expected parcel: it cares about a tracking number and an arrival, and nothing else on the row.

The first thing a lead looks at is not the column list — eleven of the 34 columns are genuinely used by all three, and that overlap is what keeps the shared table looking reasonable. The first thing to look at is the invariants: support requires editability, finance requires immutability. Those two rules cannot both hold for one record, so the shared table has already resolved the conflict, silently, with a locked flag and a convention. Every support feature now needs a finance reviewer, not because finance owns the feature, but because finance owns a rule that lives in the same row.

The cost is visible in lead time, which is the number worth collecting before the meeting. Migrations on the shared table need three sign-offs and take about nine days from proposal to production; migrations on a single-owner table take about one. With fourteen migrations across the three teams last year, that is roughly 112 days of waiting — not of work — spent on a coupling nobody chose.

The alternative the lead rejects first is the compromise: extract a shared returns-core library so everyone uses the same model "properly". That does not remove the negotiation; it relocates it into a release cycle. Three teams now coordinate on a version bump instead of a migration, with the added charm that upgrading is optional, so the drift becomes invisible instead of merely expensive.

The second rejected alternative is maximal isolation: three fully independent models with no shared anything. Something genuinely is shared — the return's identity and the fact that a return was requested. Without a common identifier and a common event, no one can join the three views, and the finance reconciliation that used to be a query becomes a project. So the shared kernel is exactly two things, deliberately: the return id, and ReturnRequested. Everything else — status vocabulary, editability rules, retention — diverges, and each side translates at its own edge.

A year later, the metric that shows it worked is not "number of services". It is the count of nullable columns that exist only for another team's purpose, and how often a code change waits on a stranger's calendar. Support ships copy changes daily; finance's model stops accreting fields it does not understand; and the words status2 never enter the schema.

When this is the wrong move

Drawing contexts too early is the common self-inflicted wound. In a young product the language is still moving; boundaries drawn now cut in the wrong place, and the anti-corruption layer becomes a museum of a model you abandoned six weeks later. One team, one product, unstable vocabulary: keep one model and refactor freely until a second consumer or a second set of rules shows up.

Analytics is the honest counter-case for integration. Cross-context questions — returns per region, refund value by cohort — need conformed dimensions and a single shape, and answering them from four isolated models is exactly the pain that data warehouses exist to remove. Isolate the transactional models; integrate deliberately downstream, in a place where a shared schema costs no one their autonomy.

In the lab: the companion Phase 3 exercise gives you a returns module where one class serves the customer flow, the finance record and the warehouse's expectations at once. You list the rules each purpose enforces, split what the rules force apart, and keep the smallest honest shared kernel between them.

Skill: same meaning or same name?

Practice on your own code

Find two modules (or teams' code) that share a name for a concept. Write the rules each side holds for it. If the rules match — deliberate shared kernel or honest merge. If they differ — draw the bounded context line and the translating adapter.

Read and watch deeper

• Domain-Driven Design, Evans — ch. 14 "Maintaining Model Integrity": bounded contexts, shared kernels, anti-corruption layers — the originals.
• "Bounded Context", Fowler — the concept and its signals, in five minutes.
• Implementing Domain-Driven Design, Vernon — ch. 3 (context maps) and ch. 13 (integrating bounded contexts): the relationship patterns, including shared kernel and published language.
• Team Topologies, Skelton & Pais — context boundaries as team boundaries (Conway's law, lesson 0033).
• Watch: ArjanCodes YouTube — search "bounded context".
• Next: lesson 0037 — Correctness vs Delivery Speed.
• Reference: Trade-offs — isolation vs integration; Patterns — anti-corruption layer; glossary — bounded context, shared kernel.

Bring your shared-schema pain points to your agent-teacher and draw the context lines together.

Source page: lessons/0036-isolation-vs-integration.html

Lesson 0037 · Master Designer · Module 3

Correctness vs Delivery Speed

Right or now — the oldest trade. The master's resolution: classify the change as reversible or irreversible. Reversible changes may go fast; irreversible ones can't afford to be wrong.

Reading ≈ 9 minPractice ≈ 25 min

Mission tie-in: the third Evolution Trade-Off — where Phase I's fail-fast and Phase II's tests meet the real pressure of shipping.

Knowledge: reversible or irreversible?

Every change has a failure cost: what happens when it's wrong? Classify:

• Reversible — wrong means a rollback, a revert, a fix-forward. The blast radius is a deploy cycle. These can ship fast: tests cover the essentials, the team watches the metrics, and the correction loop is cheap.
• Irreversible — wrong means money lost, records corrupted, legal exposure, data destroyed, trust burned. These ship with the full apparatus: invariants (lesson 0011), fail-fast (lesson 0014), tests around the domain rules, and a slow, staged rollout (lesson 0035).

The trick that collapses the trade: tests are the speed technology. A suite that locks the domain rules (characterization tests from lesson 0005, TDD for new rules) makes fast shipping safe — the team's speed comes from the safety net, not from skipping it.

# reversible: a display change — ship fast, watch the metric
def render_header(title: str) -> str:      # tests: the essentials
    ...

# irreversible: a charge — ship with the apparatus
class ChargeService:
    def charge(self, amount: Money, token: str) -> str:
        charge_id = self._gateway.charge(amount, token)   # idempotency key
        self._ledger.record(charge_id, amount)            # invariants, fail-fast
        return charge_id

The discipline is naming the class out loud: before cutting the corner, say "this is reversible — a rollback fixes it" or "this is irreversible — it needs the apparatus." The silent version is where the trade goes wrong: irreversible changes shipped at reversible speed.

Worked: the same bug, priced by how long it hides

An automated returns-eligibility rule is being changed. If it is wrong in the permissive direction it will approve items that fall outside the policy window. Volume is 3,000 returns a day; suppose a bad rule wrongly approves 6% of them — 180 a day — at an average refund of €62.

The first thing a lead asks is not "how many tests do we have?" but "if this is wrong, how long until we know?" That single number sets the price of the mistake. Caught within an hour: 125 returns pass through, 7.5 of them wrongly approved, about €465. Caught after nine days: €11,160 a day, roughly €100,000, plus a reconciliation project and a conversation with finance about a guardrail the initiative promised to hold. Same bug, same code, same tests — the entire difference is detection time.

So the apparatus this change earns is not simply "more tests". It is a daily reconciliation that recomputes approvals from the policy independently and reports disagreements, which caps detection at 24 hours by construction. A lead will often take that over three extra unit tests, because the tests only encode what somebody already thought of, whereas the reconciliation catches the thing nobody thought of at all.

The alternative the lead rejects is the traditional one: a manual QA pass before every release. It lengthens the feedback loop for every change, including the 90% that are reversible, and it cannot see what production data actually looks like — the case that breaks the rule is a 2019 order with a null shipping date, and no one writes that test by hand.

The more interesting rejection is "ship it, it's behind a flag". A flag at 1% does not make the money reversible; it makes the loss bounded — about €111 a day instead of €11,160. That is not nothing: it is a known price for information, and choosing to pay it deliberately is a legitimate senior move. Pretending it makes the change reversible is not.

Over a year, the teams that classify out loud diverge from the ones that do not in a specific way. Both ship at similar speed most weeks; the difference is that one of them has never had an incident it could not undo, because the two or three genuinely irreversible changes each quarter were recognised in advance and got the apparatus. Wisdom here is not caution — it is knowing which three.

When this is the wrong move

The classification is overhead for a team whose real problem is elsewhere. If you release once a quarter, every release is a giant irreversible batch and the useful work is shrinking it (lesson 0035), not labelling it. If you are pre-launch with no users, nothing is irreversible because nobody depends on anything yet — the apparatus is pure cost, and speed of learning is the only force in the room. And in a regulated or safety-critical domain the class is fixed in advance by policy: everything is irreversible, so the discipline that pays is the evidence trail, not the sorting.

There is also a failure mode on the cautious side. A team that classifies everything as irreversible has not become careful; it has stopped deciding, and it will spend its apparatus budget on colour changes and have none left for the migration that actually deserved it.

In the lab: the companion Phase 3 exercise asks you to classify each pending change in a returns service — a copy tweak, an eligibility rule, a refund calculation, a schema drop — and to add, for one irreversible change, the detection mechanism that bounds how long it can be wrong.

Skill: which class is this change?

Practice on your own code

Take your last three shipped changes. Classify each: reversible or irreversible? For any that shipped fast without the apparatus while being irreversible — name the loan you took (and the next lesson's ledger will make it honest).

Read and watch deeper

• Test-Driven Development by Example, Beck — the discipline that makes speed safe: tests as the design and delivery instrument.
• Accelerate, Forsgren, Humble & Kim — ch. 2: the evidence that throughput and stability rise together, and the four measures that expose it, including time to restore.
• Working Effectively with Legacy Code, Feathers — ch. 1–2: characterization tests as the bridge into changes you can't fully verify.
• A Philosophy of Software Design, Ousterhout — ch. 10 "Define Errors Out of Existence": design the irreversible class so it can't go wrong.
• Watch: ArjanCodes YouTube — search "testing" or "TDD".
• Next: lesson 0038 — the final trade-off.
• Reference: Trade-offs — correctness vs delivery speed; Patterns — characterization test.

Classify your pending changes with your agent-teacher before you start — the out-loud version is the discipline.

Source page: lessons/0037-correctness-vs-delivery-speed.html

Lesson 0038 · Master Designer · Module 3

Short-Term Productivity vs Long-Term Maintainability

You may borrow from the future — every team does. The master's rule: record the loan. Debt that is invisible is never repaid; debt that is named gets a repayment plan.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the final trade-off closes the Master Designer phase — maintainability is not the enemy of productivity; it is productivity, compounded. The Initiative Lead phase applies that judgment to a whole project.

Knowledge: the loan, the ledger, and the compounding

Ship the quick version now and the slow version later? That is a loan — you are borrowing future maintenance time to buy present shipping time. Loans are legitimate. What is never legitimate is a loan with no ledger entry: the debt exists, invisibly, and compounds through every future change (lesson 0035's flags, lesson 0037's skipped apparatus).

The ledger entry has three lines:

1. What was borrowed. The corner cut, named precisely: "the pricing logic lives in the endpoint, not the domain."
2. What it costs. The interest: "every pricing change now edits a route handler and needs a manual regression check."
3. The repayment. The trigger: "repay when the third pricing variant arrives."

# borrowed: a quick, coupled implementation
def endpoint(request: Request) -> Response:
    if request.json["tier"] == "gold":            # pricing logic in the route
        price = request.json["amount"] * 0.9
    ...
# ledger entry:
#   borrowed: pricing rules in the endpoint (not the domain)
#   interest: every pricing change edits routes + manual QA
#   repay when: third pricing variant arrives → extract PricingStrategy
#               (lesson 0004's shape, already visible)

And the compounding works the other way too: the clean code from Phase I isn't a luxury — it is future productivity purchased at small present cost. Ousterhout's point, now fully earned: a working system that's hard to change is not an asset, it's a liability that grows. The final summary of this course: maintainability is productivity over time, and every trade-off in this phase was the same trade in different clothing.

Worked: pricing one loan, and choosing which to repay

The pricing rule lives in the route handler because the first version needed to ship for a launch date. A year on, pricing changes arrive about three times a quarter. Each one now edits a route, cannot be unit-tested without spinning up the web layer, and needs a manual regression pass: roughly three hours. Extracted behind a strategy, the same change is about half an hour.

That is the interest, and it is arithmetic, not opinion: 2.5 hours × 12 changes a year = 30 hours a year, around €2,400 of loaded engineering time, charged annually and rising as variants multiply. The extraction costs about six hours once. Payback lands in roughly ten weeks, so this loan should be repaid at the next pricing change rather than scheduled, discussed, or added to a backlog where it will lose to a feature every time.

The part worth noticing is that taking the loan was correct. At the time there was one pricing rule, the launch date was real, and the extraction would have been speculative structure for a case that had not appeared (lesson 0030). What separates engineering from drift is not refusing to borrow; it is that the entry named a trigger — "the third variant" — and the third variant is the thing that arrived.

Now the harder decision. A team of six keeps a ledger with fourteen entries, and can repay perhaps two this quarter. The instinct is to rank by ugliness, which is why most debt lists are sorted by how much they annoy the person who wrote them. A lead ranks by rate instead, and gets it from version control: how many commits touched each file in the last ninety days. Two entries turn out to sit in files touched forty and thirty-one times; four sit in files touched once. The four are not repaid, and saying so out loud is the point — they are not debt this quarter, and pretending otherwise would spend a quarter of the team's repayment budget on hours that were never going to be charged.

The alternative a lead rejects is the tidy policy: "we dedicate 20% of every sprint to technical debt". It sounds disciplined and it is untargeted — it funds repayment of principal in code with no interest, and it lets genuinely expensive debt survive because it was not this sprint's turn. Repayment is triggered by the change that makes the debt expensive, and the trigger belongs next to the code, not in a document nobody opens at the moment of the edit.

When this is the wrong move

Do not open a ledger entry for code with no future. Spikes, migration scripts, a promotional page with a fixed end date and anything you will delete before the next quarter charges no interest, and structuring it carefully is a cost with no matching return. Nor does the discipline pay before product-market fit: when the odds are good that the whole feature is deleted, the option value of shipping now exceeds the interest you would avoid.

And there is a repayment that is itself the wrong move: the one whose risk exceeds the interest. A rewrite of a critical path to remove an inconvenience you pay three hours a year for is not repayment; it is a new, larger loan taken to settle a small one — lesson 0037's irreversible class, entered voluntarily.

In the lab: the companion Phase 3 exercise closes the phase by having you write the debt ledger for the returns service you have been repairing — three entries with what was borrowed, what it charges, and the trigger — then rank them by how often version control says those files are touched.

Skill: name the loan

Practice: close the trade-off phase

Write the ledger for your own codebase's three largest invisible loans — each with borrowed / interest / repay-when lines. Then carry the largest one into lesson 0039: it is part of the constraint and risk context for the next initiative you lead.

Read and watch deeper

• "Technical Debt", Fowler — the loan metaphor, properly: principal, interest, and the decision to borrow.
• "Technical Debt Quadrant", Fowler — deliberate versus inadvertent, prudent versus reckless: the distinction between a loan and a mess.
• A Philosophy of Software Design, Ousterhout — ch. 2–3: the final statement that complexity is the enemy and working code isn't enough.
• "Simple Made Easy", Hickey — the closing keynote for everything this course taught.
• Watch: ArjanCodes YouTube — Arjan's own summary videos on software design; and the official sdm examples as living reference.
• Take your learning to the communities in Resources — trade-offs become judgment only in the wild.
• Reference: Trade-offs — short- vs long-term, and the three moves that run every trade-off in this phase.

Your agent-teacher remains available for any lesson — re-explanations, code reviews, or designing your next feature together. Ask anything.

Source page: lessons/0038-short-term-productivity-vs-long-term-maintainability.html

Lesson 0039 · Initiative Lead · Module 1

Turn a Product Brief into an Initiative Frame

A brief is an invitation to investigate, not a specification to estimate. Your first leadership move is to turn requested output into a decision-ready frame.

Reading ≈ 9 minPractice ≈ 40 min

Mission tie-in: architecture starts before boxes and arrows. The outcome, constraints, uncertainty, and cost of failure decide which architecture is responsible.

Knowledge: make the problem testable

Imagine product brings this brief: “Build a self-serve returns portal by Q3. It needs automated approvals, carrier labels, and status notifications.” It sounds precise because it names features. It is not. You do not yet know whose problem matters, what improvement counts, which policies must hold, or whether a portal is the cheapest intervention.

A lead does not reject the brief or silently accept it. Product, design, and engineering rewrite it together into six decisions:

1. Outcome and baseline. Whose behavior changes, from what to what, by when? “Reduce median resolution from 72 hours to under 4 hours for eligible domestic returns by the end of the pilot.”
2. Guardrails. What must not get worse? Fraud loss, support contacts, accessibility, manual workload, and carrier cost are measures too.
3. Scope boundary. Name the first users and situation, plus explicit non-goals. International returns and exchanges are out of the pilot.
4. Constraints. Facts the design cannot negotiate: the existing order system remains authoritative; labels come from a contracted carrier; PII is retained for 30 days.
5. Assumptions. Beliefs that might be false: customers want self-service; policy rules are codifiable; the carrier can meet the latency target.
6. Decision and ownership. Who decides scope, experience, architecture, and rollout—and what evidence will reopen each decision?

The distinction that protects the whole initiative is outcome versus output. “Ship a portal” is output. “Resolve eligible returns in four hours” is an outcome. Output can be on time while the customer problem remains untouched. The outcome lets the team change its solution when evidence changes.

Worked: the arithmetic that changes the frame

Take the brief as given — portal, automated approvals, carrier labels, notifications — and watch where a lead's attention goes first. Not to the feature list. To the baseline and the population: 72 hours median, 41% of returns producing a support contact, and roughly 3,000 returns a day across the whole book.

Then the question that reshapes the frame: what share of the problem does the proposed output actually touch? The pilot cohort is signed-in domestic customers with unopened items inside 30 days — about 38% of volume, some 1,140 returns a day. Suppose the initiative works perfectly and those 1,140 resolve in four hours. The median across all returns barely moves, because the other 62% still take 72 hours and the median sits among them. An initiative whose stated success metric it cannot move by arithmetic is not an ambitious initiative; it is a mis-specified one, and it will be judged in October by a number that was never in its reach. That is why the outcome in the frame reads "for eligible domestic returns" — the population is not a caveat, it is the difference between a measurable claim and an unwinnable one.

The same arithmetic converts a guardrail into a design driver. The frame caps the manual review queue at 50 cases a day. If automation handles 90% of the cohort — the figure the team believes but has not evidenced — the remaining 10% of 1,140 is 114 cases a day, more than double the cap. So the guardrail silently requires the policy engine to decide at least 95.6% of pilot cases automatically, or requires the cohort to be narrower. Nobody wrote that requirement down; it fell out of two numbers already in the frame. Finding it in week one costs a conversation. Finding it in week nine costs the pilot.

The alternative a lead rejects is the appealing one: widen the pilot to all returns so the headline metric moves. It multiplies the policy surface — international shipping rules, exchanges, guest checkout — while the review-queue guardrail is already stretched, and it converts a testable bet into a programme. The narrower cohort is chosen precisely because being wrong about it is cheap.

What the frame buys is visible on the other side of the pilot. If contact rate falls 25% and that holds across the book, 3,000 × 41% = 1,230 contacts a day become about 307 fewer; at six minutes each that is roughly 31 agent-hours a day, near four full-time roles. Stated as an outcome, that is a result the team can claim, argue about and extend. Stated as "we shipped the portal", it is an activity report, and the first person to ask "did it work?" will have no way to answer.

A useful frame is short enough to argue with. Attach evidence and longer research; do not bury the decision beneath it. Version the frame as facts change. A changed frame is learning, not failure.

When this is the wrong move

Three situations where reframing is the wrong instinct. When a regulator, a contract or an end-of-life date makes a specific deliverable the obligation, the output is the point and the useful leadership work is sequencing and risk, not outcome discovery. When the initiative is a like-for-like migration whose entire success criterion is "nothing changes for users", an outcome statement adds a layer of translation over a goal everyone already shares. And when nothing is instrumented, an outcome is unfalsifiable — the honest frame then commits to producing the baseline first and names the date on which the real target will be set.

There is also a timing failure. Reframing a brief that arrives the same week as a hard deadline can be correct engineering and bad leadership: if the conversation cannot change the decision, run it as a risk conversation instead, and save the framing energy for the initiative that is still shapeable.

In the lab: the companion Phase 4 exercise starts from the flawed returns service you repaired in Phase 3 and asks you to write the frame the code should have been built from — outcome, guardrails, cohort, non-goals — then to name which module in the existing code contradicts each guardrail. For a fully worked version of this artifact, see the capstone's initiative frame.

Skill: separate the bet from the build

Practice: rewrite a real brief

Take one initiative in your organization. In one page, write its baseline, target outcome, guardrails, first cohort, non-goals, constraints, top five assumptions, and decision owners. Circle every number without a source and every “must” without an owner. Those circles are your first discovery backlog.

Read and watch deeper

• Continuous Discovery Habits, Teresa Torres — ch. 3–6: outcomes, opportunity mapping, and turning assumptions into tests.
• Inspired, Marty Cagan — product discovery chapters: separating the problem to solve from the feature to ship.
• Software Architecture in Practice, Bass, Clements & Kazman — 4th ed., ch. 3 and 19: business goals, stakeholders, and turning them into architecture drivers.
• Escaping the Build Trap, Melissa Perri — ch. 1–4: the organisational reasons output commitments survive even when everyone agrees outcomes are better.
• Reference: Initiative Playbook · frame template and the trade-off method.

Bring a brief to your agent-teacher and ask it to label every sentence outcome, output, constraint, assumption, guardrail, or unresolved.

Source page: lessons/0039-framing-an-initiative.html

Lesson 0040 · Initiative Lead · Module 1

Facilitate Discovery and Brainstorming

“Get everyone in a room” is not a workshop design. A strong facilitator makes evidence, independent thinking, disagreement, and a decision happen in that order.

Reading ≈ 9 minPractice ≈ 40 min

Mission tie-in: design quality depends on which options and risks become visible. Facilitation is how a technical lead increases the search space without surrendering the decision.

Knowledge: design the conversation

Unstructured brainstorming rewards the fastest speaker, the highest-ranking person, and the first plausible idea. The group then spends an hour decorating an anchor. For the returns initiative, that anchor is already “portal.” Your job is to make other interventions—policy clarification, proactive status, agent tooling, automated eligibility—available for comparison.

Use a deliberate diamond:

1. Frame. Put one decision at the top: “What is the smallest intervention that can cut eligible resolution time during the pilot?” Share the frame and evidence before the session.
2. Diverge silently. Each person writes observations, questions, and options alone. Silent first work prevents anchoring and gives design, operations, and quieter engineers equal surface area.
3. Make meaning together. Share round-robin, cluster without judging, then name themes. Separate evidence (“38% are unopened domestic items”) from belief (“customers will trust automatic approval”).
4. Converge with criteria. Score options against outcome impact, confidence, effort, reversibility, and guardrails. A dot vote may reveal sentiment; it does not make the decision.
5. Close. Record the decision, dissent, unknowns, owners, and next evidence. A workshop without a closed loop is a meeting-shaped delay.

Worked: choosing the test that could change the decision

The room's strongest belief is that "90% of returns match codifiable policy". Everyone nods; support's most experienced agent said it, and it sounds right. It is the assumption the whole automated-eligibility option rests on, and it has no evidence behind it at all.

The first thing an experienced facilitator does with a belief like that is not to argue with it. It is to ask what decision would change if it were false — and then to size the cheapest test that could distinguish the two worlds. Sampling 200 recent agent decisions takes an analyst about a day. If the true rate really is near 90%, a sample of 200 pins it to roughly ±4 percentage points at 95% confidence, so the answer comes back as a range like "86–94%".

Now put that beside the frame from lesson 0039. The manual review queue is capped at 50 cases a day and the pilot cohort is about 1,140 returns a day, so automation must decide at least 95.6% of them without a human. A measured 86–94% does not merely fail to confirm the plan — it refutes it, decisively, for one analyst-day. That is what a well-chosen test looks like: not "learn more about returns", but "a result that forces a different design".

And the design does change, in a way the workshop can now discuss with something real on the table: narrow the cohort until the exception volume fits the cap, or add an agent-assist path that clears exceptions faster than a full manual review, or renegotiate the guardrail with the operations lead who set it. Three options, all defensible, none of them available while the assumption was still a nod.

The alternative the lead rejects is the impressive one: a five-day design sprint, next week, to produce a prototype of the portal. It spends the most expensive week of the initiative decorating an option whose feasibility is unknown, and at the end of it the same unmeasured 90% is still holding up the whole structure. The other rejected move is quieter and more common: accepting the anecdote because it came from the most senior person in the room, which converts the highest-status guess into the initiative's foundation.

Over a few months the compounding shows up in calibration. A team that closes every session with an owner, a test and a date accumulates a record of which of its confident beliefs were wrong — and starts discounting the next confident belief appropriately. A team that closes with a photograph of a wall has no such record, and will have the same argument about the same assumption next quarter, with the same confidence.

Map the most consequential assumptions across two axes: impact if false and evidence strength. Test the high-impact, weak-evidence corner first. Label assumptions by risk:

• Value: will the user choose or understand this?
• Usability: can they complete it without assistance?
• Feasibility: can the system and team make it work?
• Viability: can the organization support its policy, cost, and operation?

For returns, “90% of requests match codifiable policy” is high-impact and weakly evidenced. Before designing a rules engine, sample two weeks of agent decisions. “Carrier supports label creation” is evidenced; “carrier returns within two seconds at peak” is not. Different uncertainty deserves different tests.

When this is the wrong move

Do not run this when the decision is already made. Staging divergence to produce a conclusion you have chosen is manipulation with a whiteboard, and people can tell; announce the decision, explain the reasoning, and spend the workshop budget on a question that is still open. Do not run it when the group lacks the context either — the silent phase then produces confident guesses, and clustering guesses makes them look like findings. Run a facts round, or send a pre-read and delay a week.

Two smaller counter-cases. With two or three people who already speak daily, the ceremony costs more than the anchoring it removes: talk, decide, write the paragraph. And when the question already has an answer somewhere — a documented rate limit, a legal constraint, a published benchmark — a workshop is an expensive way to reinvent it. Go and read, then bring the answer to the room as a constraint.

In the lab: the companion Phase 4 exercise asks you to list the beliefs the existing returns implementation silently encodes — about eligibility, exception rates and carrier behaviour — rank them by impact and evidence, and design the cheapest test for the top one. For a fully worked version, see the capstone's assumption map.

Skill: choose the facilitation move

Practice: design the workshop before inviting people

Choose one unresolved initiative decision. Write the decision question, participants and why each is needed, pre-read evidence, divergent prompt, convergence criteria, decider, and the exact closing artifact. If you cannot name the decision, cancel the meeting and find it first.

Read and watch deeper

• Gamestorming, Gray, Brown & Macanufo — opening, exploring, and closing a collaborative session.
• Sprint, Knapp, Zeratsky & Kowitz — ch. 2–4: structured divergence, sketching, and decision-making.
• Continuous Discovery Habits, Teresa Torres — ch. 7–9: assumption mapping, the four product risks, and sizing a test to the decision it informs.
• Thinking, Fast and Slow, Kahneman — the anchoring and availability chapters: why the first number said aloud in a room keeps its grip on everyone in it.
• Reference: Initiative Playbook · workshop script.

Ask your agent-teacher to act as the sceptic in a pre-mortem, then cluster its risks with the team's rather than treating generated ideas as evidence.

Source page: lessons/0040-facilitating-discovery-and-brainstorming.html

Lesson 0041 · Initiative Lead · Module 1

Map the Workflow Before the Components

The fastest route to a bad architecture is to turn nouns in a brief into tables and services. Start with what happens, who decides, and where the work breaks.

Reading ≈ 7 minPractice ≈ 90 min

Mission tie-in: good boundaries follow behavior, language, policy, and ownership. Workflow discovery supplies the evidence that folder trees and system diagrams cannot invent.

Knowledge: behavior before structure

For the returns initiative, a noun-first design finds Return, Customer, Label, and Refund, then draws a service around each. A workflow tells a different story:

Build this with the people who do the work, not only their managers. Ask for the last real case, including spreadsheets, copied identifiers, manual messages, exceptions, and waiting. The “unofficial” steps often contain the actual domain rules.

A lightweight EventStorming sequence helps a cross-functional group uncover the model:

1. Write domain events—facts that happened—in past tense and order them.
2. Add commands that caused them and the actors who initiated those commands.
3. Add policies: “when parcel received, authorize refund if inspection passed.”
4. Add external systems, time, manual steps, questions, and failures.
5. Mark hotspots where language, rules, responsibility, or confidence changes.

Those hotspots are design evidence. “Approved” means policy eligibility to support, warehouse inspection to operations, and settled money to finance. One global status would collapse three models. The workflow suggests separate states and a translation boundary, just as lesson 0036 predicts.

Map the current state before the desired state. Otherwise the team will unknowingly preserve invented steps and miss real constraints. Then design the target workflow by removing waiting, duplicate entry, and decisions the system can safely make—not by automating every current step.

How the lead actually ran it

Week 2. Seven people: product, design, the tech lead, four engineers. The brief already says “portal” and two engineers have started sketching tables. The lead does not open the brief. She asks the support lead for one thing—the case that went badly last week—because exceptions are where the rules live and a representative case has had its exceptions averaged away. She rejects the obvious starting point, the support ticket taxonomy: tidy, available, and encoding the current tool's dropdown rather than the domain.

Ninety minutes, two rules: one real case, no whiteboard theory. Tomas objects that this is a two-day tax on a ten-week pilot. The lead does not overrule him; she accepts the timebox as the price of the objection and asks him to write the events. He finds the three meanings of “approved” himself. Two further findings changed the design:

• The warehouse clerk keeps a spreadsheet reconciling parcels against a printed sheet. It was the only place the fact parcel received had ever been recorded—a system of record nobody had listed as a system. It is why, in lesson 0045, a warehouse event is what moves a return to received.
• The policy is less codifiable than the brief assumes. The 200-case sample commissioned in lesson 0040 came back at 143 clean matches against written policy and 57 needing human judgement—71%, not the 90% the brief implied. At the pilot's expected 160 requests a day, a 29% exception rate is roughly 46 manual cases daily against a guardrail of 50. The manual review queue is not a fallback here; it is load-bearing, and it has almost no headroom.

Nine weeks on, the payoff of the first hotspot is invisible—one module writes the refund state, and a class of “both components set refunded” defects never happened. The second is highly visible: it caps the pilot cohort, and it is why lesson 0050's week-four review watches queue depth as closely as median resolution time.

When this is the wrong move

Skip the session when a formal specification already governs the process more precisely than a workshop can, when the process is a single automated step with no human hand-off, or when this team has mapped this workflow twice in six months and nothing changed—that last case means the blocker is an unmade decision, not missing knowledge, and a third map is a way of avoiding it. Where there is genuinely no current state, prototype and observe real behavior instead; there is nothing yet to elicit.

Skill: read design evidence from a workflow

Practice: tell one real story end to end

Invite one domain expert, product, design, and two engineers. Map a recently completed real case as events. Add commands, actors, policies, external systems, waiting time, manual work, failures, and vocabulary collisions. Finish by writing three candidate boundaries and the evidence for each—do not draw deployables yet.

In the lab and the capstone. The lab's phase-4 checkpoint asks you to do this against code rather than a whiteboard: recover the workflow the existing returns package implements, and mark where its vocabulary changes meaning between modules. The finished artifact is the workflow map in the strong capstone packet—every hotspot it records is used later by a driver, a contract, or a rollout gate. Compare with the weak version, which lists the same steps with no actors, no waiting, and no collisions, and so supports no later decision.

Read and watch deeper

• Introducing EventStorming, Alberto Brandolini — the canonical guide to events, commands, policies, hotspots, and collaborative modeling.
• User Story Mapping, Jeff Patton — ch. 3–5: tell the whole story and build shared understanding through activity.
• Domain-Driven Design, Eric Evans — ch. 2 and 14: ubiquitous language and maintaining model integrity.
• EventStorming, Alberto Brandolini — the technique's own site: workshop formats, notation, and the big-picture-to-design progression.
• Reference: Initiative Playbook · workflow map, and glossary: bounded context.

Give an anonymized workflow transcript to your agent-teacher and ask it to extract events, commands, policies, ambiguities, and missing actors; validate every extraction with the domain expert.

Source page: lessons/0041-mapping-workflows-and-domain.html

Lesson 0042 · Initiative Lead · Module 1

Shape User Stories into Vertical Slices

A flat backlog hides the user journey and rewards component work. A story map lets the team cut the smallest end-to-end path that can teach something.

Reading ≈ 8 minPractice ≈ 60 min

Mission tie-in: slicing is software design. It decides dependency order, integration timing, feedback speed, and whether the architecture grows around real behavior or imagined reuse.

Knowledge: the story is a conversation

A user story sentence is a placeholder, not a miniature contract. “As a customer, I want to create a return so that I can receive a refund” omits policy, failure, evidence, state, accessibility, and the outcome being tested. Its value is the conversation it starts.

Turn the workflow from lesson 0041 into a two-dimensional story map:

A vertical slice crosses the system and produces observable behavior. “Create return table,” “build rules API,” and “design status component” are horizontal layers; none helps a user or tests the integration alone. “Eligible signed-in customer receives a label and can see status” crosses UI, policy, persistence, carrier, and telemetry—but only for one controlled case.

Attach examples before implementation. Use Given/When/Then when it clarifies, but the syntax is less important than the specificity:

Good acceptance examples cover the rule, its boundary, a meaningful failure, and a guardrail—not every implementation detail. Refine them with product, design, engineering, and whoever tests or operates the flow. This “three amigos” conversation catches ambiguity when it is still cheap.

Do not create a bureaucratic “Definition of Ready” gate. Use a readiness question: does the team understand the user and outcome, examples, dependencies, design state, telemetry, and unresolved risk well enough to start while preserving room to learn?

How the lead actually cut it

Week 3, seven people, ten weeks to the 30 September pilot. Product wants rows one and two, because guest orders are 29% of demand and the sponsor keeps asking about them.

The lead's first question is not “what can we build?” but “if this slice ships and the median does not move, what will we have learned?” Row one answers it: automatic eligibility plus visible status is either the cause of faster resolution or it is not. Guest orders would double the identity and fraud surface without changing what the slice can teach, so guest becomes an explicit non-goal with a revisit trigger rather than a silent omission.

Karl argues the opposite order: eligibility engine first, because policy is the hard part. The lead rejects it for a specific reason rather than a preference—policy correctness can be proven cheaply with executable examples, while nothing but a live path can prove the carrier call, the retry, and the status loop. Sequence what only production-shaped evidence can settle. Bea, the support lead, dissents on the cohort; her belief that guests will dominate the queue is written down with the test that would settle it, and it resurfaces in lesson 0050's week-four review.

The manual seam is chosen by arithmetic. With 71% of sampled cases matching written policy, roughly 46 of the pilot's 160 daily requests need a human against a guardrail of 50 per day—so the slice automates the clean 71%, routes the rest to an agent queue, and instruments queue depth from day one. Slice one shipped in nine working days, and on day four it surfaced the carrier's duplicate-label behavior on retry: a defect that, under a layered plan, would have arrived in week seven with a policy engine, a UI, and a notification service already built on top of it.

When this is the wrong move

Do not force a vertical slice when there is no integration to discover: a batch recalculation inside one service, a change with no user-visible surface. Do not force one when the scaffolding costs more than the risk—if a slice needs a fake adapter, a flag, a seeded cohort, and a data migration to demonstrate anything, the honest move may be a spike instead. And in a release that legally cannot expose partial behavior to anyone, slice for internal evidence and accept that the external release is a single event with a rehearsed reversal.

Skill: find the learning slice

Practice: cut a journey, not a layer

Build a story map for one initiative: backbone activities left to right, variations beneath. Draw a line across the smallest slice that reaches an outcome or answers a risky assumption. Write four examples: happy path, rule boundary, meaningful failure, and guardrail. Then identify the manual seam that could remove the largest unproven automation.

In the lab and the capstone. The lab's phase-4 checkpoint makes you cut one slice through the existing returns code and prove it end to end—the rollout gate for that slice is written as a test rather than a paragraph. The worked artifacts are the story map and its executable examples in the strong capstone packet; trace how the boundary example there becomes a refusal reason in the contract and a segment in the rollout telemetry. Compare with the weak version's story map and examples, where the backbone is a component list and every example describes a happy path.

Read and watch deeper

• User Story Mapping, Jeff Patton — ch. 4–8: the backbone, release slices, and using maps for discovery and delivery.
• Specification by Example, Gojko Adzic — ch. 2–4: deriving scope and tests from concrete examples collaboratively.
• Essential XP: Card, Conversation, Confirmation, Ron Jeffries (2001) — the origin of the three Cs, and why the sentence on the card is the least important part.
• Reference: Initiative Playbook · story-map and example templates.

Ask your agent-teacher for five smaller slices, then reject every proposal that does not reach observable behavior end to end.

Source page: lessons/0042-story-mapping-and-vertical-slices.html

Lesson 0043 · Initiative Lead · Module 2

Find the Architecture Drivers

“Fast, scalable, secure, maintainable” is not a set of requirements. Architecture begins when a quality has a situation, a response, and a number.

Reading ≈ 8 minPractice ≈ 45 min

Mission tie-in: every architecture is good for some conditions and poor for others. Drivers make those conditions explicit enough to design and test.

Knowledge: the few requirements that shape the system

Most requirements do not change the architecture. A new return reason may add a rule inside an existing boundary. A requirement to keep accepting requests while the carrier is unavailable changes data ownership, failure handling, and workflow shape. Architecture drivers are the small set of functional needs, quality attributes, constraints, and risks with enough force to shape the structure.

Turn vague “non-functional requirements” into quality-attribute scenarios with six parts:

1. Source: who or what causes the condition?
2. Stimulus: what happens?
3. Environment: under which operating condition?
4. Artifact: what part of the system is affected?
5. Response: what must the system do?
6. Measure: how will you know it did so?

Prioritize five to seven drivers, not fifty. Rank by business impact, uncertainty, and architectural reach. If two drivers conflict—800 ms response and a live carrier confirmation—write the trade-off rather than letting an engineer discover it mid-sprint. Here the team returns eligibility quickly and makes label creation a separately observable state.

Separate constraints from preferences. “Orders remain in the existing platform during the pilot” is a constraint. “Use Kafka because we already know it” is a proposed decision. Treating preferences as facts is how architecture becomes cargo cult.

Every selected driver needs an evidence mechanism: load test, architecture fitness function, contract test, recovery exercise, security test, cost alert, or production measure. A requirement that cannot fail a check will eventually lose to a feature that can pass a demo.

How the lead actually narrowed it

Week 4. Twenty-three “requirements” arrive in a shared document, contributed by four groups who have never had to reconcile them. The lead does not start writing scenarios. She applies one filter to each line: name two designs that would respond to this differently. Nineteen fail the filter. They are real needs—audit logging, sensible error messages, a metrics dashboard—but every plausible architecture handles them the same way, so they are backlog items, not drivers.

The alternative she rejects is a full structured architecture evaluation with all fifteen stakeholders. It would be defensible and it would cost two days plus the calendar to convene it, against a seven-person, ten-week pilot. She takes the scenario form and drops the ceremony: five scenarios, one hour, the four people who carry the consequences.

Sam, from security, wants a scenario for every category in the team's threat checklist. The lead keeps one—object-level authorization on order identifiers—and moves the rest into a review checklist attached to the design. The reason is stated out loud so it can be argued with: a driver must change the structure, and most of that checklist changes only the code. Sam's dissent is recorded; if a scenario in that list later forces a boundary, it is promoted.

The conflict that matters shows up immediately. The 800 ms eligibility target and “confirm the label with the carrier before responding” cannot both hold: the four-hour spike in lesson 0046 measured the carrier sandbox at 1.9 s p95 and 6.4 s p99. Rather than let an engineer discover this in week eight, the driver table writes the trade explicitly—eligibility answers fast, label creation becomes a separately observable state. That one sentence is why the availability scenario exists, why the ADR is decidable at all, and why the rollout in lesson 0049 has a “pending label” gate to watch.

When this is the wrong move

Skip formal scenarios when the initiative's dominant risk is whether anyone wants the thing: write assumptions and buy user evidence instead, because a latency target for an unvalidated product is precision in the wrong place. Skip them for genuinely short-lived work—a two-week internal migration tool does not need a modifiability scenario. And refuse to write one when the honest answer to “what is the measure?” is “nobody knows”: record the unknown, name the spike that would settle it, and leave the row empty rather than filling it with a number the team will later defend.

Skill: make the driver measurable

Practice: write the five scenarios

For your initiative, select the five qualities with the greatest combined impact, uncertainty, and structural reach. Write source, stimulus, environment, artifact, response, and measure for each. Add one evidence mechanism and one owner. Delete every generic “scalable” or “secure” statement left over.

In the lab and the capstone. The lab's phase-4 checkpoint turns one of these scenarios into outcome telemetry and a rollout gate that fails as a test rather than as an opinion. The worked artifact is the driver table in the strong capstone packet—each row there names an evidence mechanism and an owner, and each is referenced later by an ADR or a rollout stage. Compare with the weak version, whose qualities are adjectives with no environment, no measure, and therefore nothing a design review can disagree with.

Read and watch deeper

• Software Architecture in Practice, Bass, Clements & Kazman — ch. 3 and 13: the six-part quality-attribute scenario, and architecturally significant requirements.
• Documenting Software Architectures, Clements et al. — the quality-attribute scenario as a precise design input.
• The Elephant in the Architecture, Cartwright — justify cross-functional requirements with business value.
• Quality Attribute Workshops (QAW), Third Edition, Barbacci et al. — SEI technical report CMU/SEI-2003-TR-016: how to elicit and refine scenarios with stakeholders.
• Reference: Initiative Playbook · driver table, and fitness function.

Ask your agent-teacher to attack each quality statement with “under what condition, which response, and how measured?” until no adjective survives alone.

Source page: lessons/0043-architecture-drivers-and-quality-attributes.html

Lesson 0044 · Initiative Lead · Module 2

Draw the Context, Then Choose Boundaries

The valuable architecture diagram is not the most detailed one. It is the smallest view that lets its audience inspect a decision.

Reading ≈ 8 minPractice ≈ 60 min

Mission tie-in: system design turns drivers and workflows into boundaries with controlled dependency direction. Diagrams are review instruments, not wall art.

Knowledge: three views, three questions

Start with a system context view: the system in scope, the people who use it, and external systems it touches. This answers what is ours, who needs it, and where are the external dependencies and trust boundaries?

Then draw a container view—C4's word for a deployable application or data store, not specifically Docker. This answers what runs, what stores data, how do they communicate, and who owns each part? Finally, draw one dynamic view for the risky workflow. This answers what happens in time when the happy path or failure case runs?

For a 6–8 person cross-functional team, a modular monolith is the responsible default: one deployable, explicit modules, one composition root, and enforced dependency rules. It minimizes coordination and operational surface while preserving seams. Choose another deployable only when a driver requires independent scaling, isolation, security, availability, release cadence, technology, or ownership—and record the cost.

Inside the deployable, draw modules around four kinds of evidence:

• Language: eligibility, journey, and settlement mean different things.
• Change: policy changes weekly; carrier integration changes on vendor cadence.
• Invariants and state: the eligibility decision must be internally consistent.
• Ownership: one owner can change a module without negotiating every edit.

Keep technology at the edges, as lesson 0023 established. The domain-facing interface says create_label(intent), not carrier_sdk.shipments.post(payload). On the diagram, label every arrow with the interaction and protocol. Unlabelled arrows conceal assumptions.

A diagram should carry a title, scope, audience, date/version, legend, ownership, and the significant qualities or risks it addresses. Delete boxes that do not help the stated audience make a decision. Code-level detail belongs in code unless it explains an unusually important mechanism.

How the lead actually reviewed it

Week 5, container view on the screen. The lead looks at the arrows first, not the boxes, and specifically at which arrows cross an ownership line. Her question to the room is operational, not aesthetic: who is on call when this arrow fails at two in the morning? Three arrows have an answer. One—the call into the order platform—does not, which is how Asha's team becomes a named adviser on the contract rather than an assumed dependency.

Dana proposes extracting an Eligibility Service. Her reasoning is good: policy changes weekly and the rest of the system does not, so why should a policy change redeploy the carrier code? The lead rejects the extraction and says why in the same terms. Release cadence is only a driver when the cadences belong to different owners; here one team owns both, so an enforced module seam buys the same isolation of change for none of the operational cost. Dana's counter is recorded rather than dismissed: if returns policy moves to a second team next quarter, the seam must become a service. That sentence becomes the revisit trigger on the ADR in lesson 0046.

The seam is then made real, because an agreed boundary that nothing enforces is a naming convention. The team writes an import rule as a test that fails the build:

import ast
import pathlib

ALLOWED = {                      # a module may import only what is listed here
    "journey": {"eligibility", "shared"},
    "eligibility": {"shared"},
    "carrier": {"shared"},
    "shared": set(),
}


def imported_roots(path):
    tree = ast.parse(path.read_text(encoding="utf-8"))
    for node in ast.walk(tree):
        if isinstance(node, ast.ImportFrom) and node.module:
            yield node.module.split(".")[0]


def test_modules_depend_only_downward():
    root = pathlib.Path("returns")
    for path in root.rglob("*.py"):
        owner = path.relative_to(root).parts[0]
        for target in imported_roots(path):
            if target in ALLOWED and target != owner:
                assert target in ALLOWED[owner], f"{path}: {owner} -> {target}"

Ten weeks later the system is one deployable and one worker: two processes on call rather than five, and the journey module still cannot reach the carrier adapter directly, because the build says so. The cost the team accepted is visible too—a policy release redeploys everything, and twice the team waited for an unrelated change to clear the pipeline.

When this is the wrong move

Do not draw the packet when the audience already shares the model—redrawing the context view for the third time to the same four people is ceremony. Do not draw it when the question can be settled by a twenty-line spike, and do not draw a container view for a system with one container. The counter-case for the enforced import test is smaller than it looks, but it exists: in a codebase of three modules whose owners sit together and review everything, the test costs more attention than the mistake it prevents. Add it when the team grows past the point where every import is seen by someone who cares.

Skill: draw only what earns its place

Practice: make a three-view architecture packet

Draw a context diagram, a container diagram, and one dynamic diagram for your riskiest workflow. On each: state audience and question; label every boundary, owner, arrow, and data store; annotate which driver it addresses. Run a review where every comment must point to a driver, workflow, or risk.

In the lab and the capstone. The lab's phase-4 checkpoint asks you to record one boundary decision as an ADR and to enforce it with a test like the one above, so the seam survives the next contributor. The worked artifact is the three-view architecture packet in the strong capstone packet, where every arrow is labelled and every view names the driver it answers. Compare with the weak version: one crowded diagram, a service per noun, unlabelled arrows, and a shared database drawn as though ownership were obvious.

Read and watch deeper

• The C4 model, Simon Brown — official model; especially context, container, dynamic diagrams, and notation checklist.
• Fundamentals of Software Architecture, Richards & Ford — architecture styles, characteristics, and component boundaries.
• Team Topologies, Skelton & Pais — ch. 6–7: aligning ownership boundaries and interaction modes.
• MonolithFirst, Fowler — why teams that start with services usually get the boundaries wrong, and what to do instead.
• Reference: Initiative Playbook · architecture packet, and deep modules.

Show the diagrams to your agent-teacher with the driver set and ask which box or arrow has no justification and which driver has no visible response.

Source page: lessons/0044-system-context-and-boundaries.html

Lesson 0045 · Initiative Lead · Module 2

Design State, Data Ownership, and Contracts

Most integration bugs are unanswered state questions wearing API syntax. Model transitions, ownership, failure, and change before polishing endpoints.

Reading ≈ 8 minPractice ≈ 45 min

Mission tie-in: data is the durable part of a system. A lead makes its invariants, writer, lifecycle, and compatibility explicit before code makes accidental promises.

Knowledge: state first, transport second

“Return status” sounds like a field. It is actually a state machine with allowed transitions and actors:

The state machine answers what is legal. Data ownership answers who may establish each fact. Prefer one authoritative writer for a piece of state; other modules receive a contract, event, or read model. A shared database does not require shared ownership. If both Journey and Payments can set refunded, the invariant lives nowhere.

For every command, API, or event contract, answer:

• Meaning: command, fact, or query? What business promise does success make?
• Identity: what identifies the resource and the user's intent? How are retries deduplicated?
• Validation and authorization: which edge rejects malformed data, and which domain rule refuses valid-but-forbidden behavior?
• Failure: timeout, unavailable dependency, conflict, partial success—what may the caller safely do?
• Compatibility: which fields are required, what may be added, how will consumers migrate, and when can old behavior be removed?
• Lifecycle: classification, encryption, retention, deletion, audit, and who may read it.

Design retries with an idempotency key representing one intent. A client retry after timeout must return the original return and label, not create another. Design consumers as tolerant readers, and evolve persisted data with expand/contract. Compatibility is a delivery feature, not cleanup.

Draw data flows across trust boundaries and minimize data early. The carrier needs recipient name and address for a label; it does not need return reason notes or order history. Record retention and deletion in the model, not only a policy document.

How the lead actually reviewed it

Week 6, contract review, ninety minutes, with Asha from the order platform and Sam from privacy in the room. The lead's first move is not to read the API draft. She scans the state table for any row where two components could write the same fact, and finds one: refunded, which both the journey module and the payments context believed they owned. Nobody had disagreed, because nobody had asked.

Her second move is the question that has repaid itself on every initiative she has led. She asks the producer and the consumer separately: what does a timeout on create_label mean? Journey answered “no label was created.” The engineer holding the carrier adapter answered “maybe a label was created.” Both answers are reasonable and they cannot both be built on. The four-hour spike settled it: retrying a timed-out label call without an idempotency key produced a duplicate label in 12% of attempts.

The obvious fix—a unique database constraint on the return—was rejected, and the reason matters. It converts a duplicate into an error at the wrong layer, at the wrong time, and it throws away the thing the caller actually needs: the label that was already bought. The design chosen instead stores the intent before the call and returns the original answer to every retry:

class DuplicateIntent(Exception):
    """Same intent key, different content — a client bug, not a retry."""


def request_label(store, carrier, intent_key, return_id, address):
    existing = store.find_label(intent_key)
    if existing is not None:
        if existing.return_id != return_id:
            raise DuplicateIntent(intent_key)
        return existing.label_id            # a retry gets the first answer

    reservation = store.reserve(intent_key, return_id)   # committed before the call
    label_id = carrier.create_label(reservation.id, address)
    store.attach_label(intent_key, label_id)
    return label_id

Rui dissented: the carrier offers its own idempotency header, so why hold state on this side? The lead recorded the objection and answered it with a boundary argument rather than a technical one—the carrier's semantics are outside the team's control and can change with a vendor release, while the promise made to the customer cannot. The header is used as well; it is not relied on.

Sam's contribution took four minutes and removed a liability. The carrier needs a recipient name and an address to print a label. It was being sent the return reason and the order history because the payload was built from an existing internal object. Minimizing that payload at design time cost nothing; removing it after two consumers depend on it would have been an expand/contract migration across a vendor boundary.

The consequence appears at the staff-account gate in lesson 0049: fifty cases, zero duplicate labels. Nothing was celebrated, which is what a well-designed contract feels like from the outside.

When this is the wrong move

A full state-and-contract review is waste for a read-only internal report, or for an entity that is created and never changes again. Inside a single deployable, where one module calls another and both ship together, a typed function signature is the contract; adding a versioning policy and a compatibility window to it buys nothing and costs a document nobody updates. The apparatus earns its cost exactly where the two sides can be deployed, operated, or changed independently—which is also the moment most teams notice it is missing.

Skill: locate the durable promise

Practice: review one critical state transition

Draw the state machine for one initiative entity. For every transition, name command, actor, rule, owner, emitted fact, retry behavior, and audit need. Then choose one cross-boundary contract and document its meaning, failure semantics, compatibility policy, PII, and a contract test.

In the lab and the capstone. The lab's phase-4 checkpoint makes the retry semantics executable: a test that replays one intent twice and fails if the system produces two labels. The worked artifact is the state and contract review in the strong capstone packet, which names one writer per fact and states what a timeout means before any endpoint is designed. Compare with the weak version, where “status” is a free-text field, two components update it, and the failure semantics are left to whoever writes the client.

Read and watch deeper

• Designing Data-Intensive Applications, Kleppmann — ch. 4 and 8: evolvable data, partial failure, and distributed-system ambiguity.
• Domain-Driven Design, Evans — entities, aggregates, repositories, and context boundaries as consistency tools.
• OWASP Threat Modeling Cheat Sheet — model data flows and trust boundaries early, then ask what can go wrong.
• Idempotent requests, Stripe API reference — a production contract that states key scope, retention, and what a repeated key returns.
• Reference: Initiative Playbook · state and contract review.

Ask your agent-teacher to generate adversarial sequences—duplicate, reorder, timeout, stale read, unauthorized identifier—then decide which your contract prevents or absorbs.

Source page: lessons/0045-data-state-and-contracts.html

Lesson 0046 · Initiative Lead · Module 2

Compare Options and Record Decisions

Senior judgment is not having the first answer faster. It is exposing credible alternatives, buying evidence where uncertainty matters, and leaving a decision future teammates can reconstruct.

Reading ≈ 8 minPractice ≈ 45 min

Mission tie-in: explicit forces turn architecture from personal taste into organizational reasoning. Decision records make that reasoning durable without freezing it.

Knowledge: design it twice, decide once

For any consequential choice, produce at least two genuinely different designs. “Kafka” versus “managed Kafka” is one mechanism with two suppliers. For carrier failure, credible options are: fail the whole request synchronously; accept and retry from a local outbox; or route work to an agent queue. Compare them against the drivers from lesson 0043.

Use a spike only when evidence could change the decision. A spike has one question, a timebox, a result format, and a discard rule: “In four hours, measure carrier label p95 and duplicate behavior under timeout using the sandbox; publish numbers and throw away the harness.” “Explore the carrier API” is an unbounded implementation prelude.

Match decision apparatus to reversibility. A local class shape can be changed in a pull request. A public contract, data ownership boundary, expensive vendor, or privacy model deserves broader advice and a written record. Review with the people who carry the consequences: product for outcome, design for experience, security/privacy for trust, operations for failure, and affected teams for contracts.

Use an Architecture Decision Record (ADR) for one decision:

Keep ADRs immutable as historical facts. If the decision changes, write a new one that supersedes it. A one-page record written near decision time beats a forty-page design document updated after everyone has forgotten the disagreement.

Name the decider before review. Advice should improve a decision, not create consensus veto. Record meaningful dissent and the evidence that would prove it right. Psychological safety and technical rigor meet here: a concern can survive even when its preferred option does not.

How the lead actually decided it

Week 7. The carrier-failure decision has been circling for four days in a chat thread. The lead's first move is not to open the carrier documentation; it is to reread the availability scenario from lesson 0043, because a decision without a driver is a preference contest. Then she asks the question the thread had never asked: what does the customer see between “accepted” and “label ready”? That question, not the technology, is what eliminates one option and creates another.

Synchronous failure is attractive and is rejected on evidence, not taste: it is roughly forty fewer lines, no worker, no queue to operate—but the availability scenario requires accepting eligible requests through a thirty-minute carrier outage at peak, and this design cannot. Manual-only fallback is the second rejection, and the arithmetic does it: the manual queue already runs near 46 of its 50 daily cases from ordinary policy exceptions, so a peak outage would push it straight through the guardrail.

The spike is scoped to one question and four hours: measure carrier label latency and duplicate behavior under timeout in the sandbox, publish the numbers, throw away the harness. It returns p95 1.9 s, p99 6.4 s, and duplicate labels in 12% of naive retries. Note which decision that evidence actually changed. It did not choose the outbox—the availability scenario had already done that. It chose the idempotency key, which nobody had been arguing about.

Tomas dissents, and his objection is the best one in the room: the worker adds an on-call surface for a failure mode nobody has yet seen. The lead does not talk him out of it. She writes it into the ADR and converts it into the revisit trigger—if the queue misses its service objective twice, or the carrier ships a durable async API, the decision reopens. Dissent that survives in writing is what makes it safe to disagree the next time.

Week 12 supplies the consequence. The carrier goes down for twenty-two minutes during scheduled maintenance. Sixty-one requests are accepted, sixty-one labels are created after recovery, and no duplicates appear. The honest cost is on the same page: the pending state generated four support contacts from customers who did not understand what “label pending” meant—a comprehension problem the design created and the copy had to solve.

When this is the wrong move

Do not write an ADR for a choice that is cheap, local, and reversible in a pull request; the code and its history already record it, and a log full of trivia trains people to stop reading the log. Do not run a spike when the evidence cannot change the decision—if a hard constraint means you will do X regardless, buying a number is procrastination with a timebox. And when a constraint genuinely leaves one option, record the constraint rather than staging a comparison; a fabricated alternative in a decision table is a tell that the decision was made elsewhere.

Skill: spend evidence where it changes decisions

Practice: write one decision, not one design epic

Pick an initiative choice that would be expensive to reverse. Draft two meaningfully different options, compare them against named drivers, and identify the largest unknown. If evidence can change the choice, write a timeboxed spike. Then write the one-page ADR, including dissent and a measurable revisit trigger.

In the lab and the capstone. The lab's phase-4 checkpoint asks for an ADR covering one decision you actually make in the lab code—with its rejected option and a revisit trigger you could test. The worked artifact is the option comparison and ADR in the strong capstone packet, where the rejected options are the ones a reasonable team would have chosen. Compare with the weak version: one option, a decision stated as a conclusion, no forces, no dissent, and nothing that could ever reopen it.

Read and watch deeper

• A Philosophy of Software Design, Ousterhout — ch. 11: design it twice.
• Architecture Decision Record, Fowler — concise decision, context, ramifications, advice, and superseding records.
• Software Architecture: The Hard Parts, Ford et al. — trade-off analysis and architecture decision records.
• Documenting Architecture Decisions, Michael Nygard — the original ADR format: context, decision, status, consequences.
• Reference: Initiative Playbook · option, spike, and ADR templates.