Lesson 5 · Failure mode #4: the ball of mud

Stop the code from turning into a mess

You know the feeling: the app works, but every small change touches ten files and breaks two of them. That is a "ball of mud." Agents write code fast, so they create this mess faster than ever. This lesson is one simple idea that keeps code easy to change, shown with a real example.

One example: "book an appointment"

Say your DuckyCutz booking flow needs to book an appointment. There are two ways the agent could build it. Watch what the caller (the code that uses it) has to do in each.

Way 1: the messy way

// the caller has to do everything,
// in the right order, knowing all the rules:

const free = checkAvailability(slot);
if (!free) return "taken";
const booking = createBooking(customer, slot);
writeToCalendar(booking);
sendConfirmationSMS(customer, booking);
markSlotTaken(slot);

Way 2: the clean way

// the caller says what it wants.
// all the steps and rules are hidden inside:

const result = bookAppointment(customer, slot);

Both do the same thing. The difference is who has to know the details.

In Way 1, every place that books an appointment has to repeat those six lines and get the order right. Ten booking spots means that logic is copied ten times. Change the rules (say, add a deposit step) and you edit ten places, and miss one.
In Way 2, there is one function. Ten callers just write bookAppointment(...). Add the deposit step? You edit one function and all ten are fixed.

The whole idea in one line A good piece of code does a lot inside but is simple to use from outside. Matt (borrowing from a book called A Philosophy of Software Design) calls this a deep module. Way 2 is deep. Way 1 is "shallow": it barely hides anything, so the caller does all the work.

So when the agent designs something, the question to ask is simple: "How much does the caller have to know to use this?" Less is better. Push the complexity inside, behind a simple way to call it.

The one test that tells you which you have

Matt's favourite check, and it takes ten seconds. Imagine deleting the piece of code.

If deleting it makes the mess vanish (nothing else got more complex), it was not doing much. It was shallow. Fine to delete or fold away.
If deleting it makes the same mess reappear, copied across many callers, then it was doing real work by holding that complexity in one place. It was deep. Keep it.

Delete bookAppointment and those six lines reappear in ten places. That is proof it was earning its keep.

One trap to avoid

Do not add "flexibility" nobody needs. Agents love to build in swappable options "in case you need them later." Matt's rule: only make something swappable when you actually have two different versions of it today. One version = do not build the swap. (You will recognise this as the same instinct as Ponytail: no speculative machinery.)

The habit that does the finding for you

Invest in the design of the system every day. Kent Beck, Extreme Programming Explained

You do not have to spot the shallow, messy code yourself. Run /improve-codebase-architecture on a real project every few days. It:

Reads the codebase and notices the messy, hard-to-change spots.
Shows you a visual report (opens in your browser, nothing saved into the repo) with before/after pictures, each marked Strong / Worth exploring / Speculative.
You pick one, and it grills you (Lesson 1) through the fix, updating your CONTEXT.md (Lesson 2) as it goes.

That is the payoff of the whole course: every earlier skill shows up in this one.

Check yourself

Which is the "deep" (good) version of booking an appointment?

You delete a function and the same six lines pop back up in ten other places. What does that tell you?

The agent wants to make the payment step "swappable for future providers". You use one provider today. What is the right call?

The whole course in four questions

Each one is a different failure mode from the course. Name the fix. This is the "which skill do I reach for" instinct, and it is the real skill you are walking away with.

The agent confidently built a feature you never asked for. What was missing?

Every session the agent re-explains your domain in long paragraphs and renames the same thing three ways. Fix?

A specific output is wrong and nobody knows why. Where do you start?

The app works, but every change touches ten files and breaks two. Which skill, run regularly?

Do this now (your one win)

Run /improve-codebase-architecture on a real project (projects/website-factory or projects/bobe-dashboard). Read the browser report.
For the first messy spot it flags, do the delete-it test in your head: if this vanished, would the mess disappear, or reappear copied everywhere?
Pick one "Strong" item and let it walk you through the fix.

Report back: what messy spot did it find, and did the delete-it test agree? That is your capstone.

If you meet Matt's exact words later

This lesson used plain language. Here are the technical terms it maps to, so the cheat sheet and Matt's docs make sense:

Plain	Matt's word
a piece of code with a way to call it	module
the way you call it / what you must know to use it	interface
does a lot inside, simple to use outside	deep
barely hides anything, caller does the work	shallow
a place you can swap one version for another	seam / adapter

You finished the arc Five lessons, four failure modes, one system. The cheat sheet is your router now: symptom in, skill out. Want it to stick? Ask me in a few days for a quick mixed quiz across all five, or to run a real project through the whole flow with you.