01 · Knowledge crunching

When you finish this lesson you should be able to:

Explain why “just tell me the requirements” fails in a complex domain
Run a crunch: scenarios, a small model, correction from experts, code that uses the names
Distinguish a shallow model (more fields) from a deep one (fewer concepts that predict)
Notice when the team has stopped learning and started accumulating flags

Why this is chapter one

Evans does not start with entities. He starts with how you get knowledge into the software at all. The heart of complexity is the domain itself—the human enterprise you are automating. Frameworks do not dissolve that. If you cannot think with the people who live in that enterprise, you will automate their worst workaround.

He contrasts three kinds of project (preface, then this chapter’s spirit):

Fast first version, no model. A simple trading site ships. There is no shared language. Version two cannot move. The business logic, not the stack, is what ossifies.
Model as a living thing. A modest first app is followed by acceleration. Each iteration opens options. Communication between developers and experts gets better. The design gets easier to change, not harder.
The implied third: ambition without crunching—diagrams that never bind to code (you will meet this in lesson 03).

The lesson for a strong engineer: your value is not typing screens. It is being the person who can sit with an expert for an hour and leave with a model that explains their worst case.

You will not become the domain

Evans’s PCB story is the template. He did not know printed-circuit-board design. The experts could not specify software; they asked for “read a file, sort it, write a report.” That would not produce the leap they wanted.

Hope showed up in repeated words on the reports: net—a conductor that connects any number of components and carries a signal. That was the first model element. He drew informal interaction diagrams, walked scenarios, and got constantly corrected. Collisions in their terminology got ironed out because someone was trying to make a model precise enough to code.

Translate that to work you actually do:

You will not become a fraud analyst, a lender, or a growth scientist in a month.
You will become fluent in a handful of concepts that make their sentences composable.
The first meetings will feel like your head is spinning. That is data. The words that keep coming back are the candidates.

What failed: asking experts to design the software. What worked: asking them to walk scenarios, while you proposed names and relationships, and they said “no, that’s not a component, that’s a component instance.”

Ingredients of effective modeling

You need all of these, not a ceremony with three of them:

Binding to implementation. The model is for building software. If it cannot be expressed in the running system, it is a different artifact (an explanatory sketch, a slide).
A language based on the model. Speech, tests, code. Lesson 02.
A model that is knowledge-rich. Rules live in the model, not only in a senior person’s head or a Confluence page.
Distillation. Throwing away. A model that contains everything the experts ever said is a transcript, not a model.
Brainstorming and experiment. You try a shape, use it on a scenario, keep or kill it. This is not waterfall analysis.

If you skip (1), you get pretty boards. If you skip (4), you get a god object named User. If you skip (5), you freeze the first noun list and call it architecture.

What crunching looks like in a week

Session 1 (45 min). Expert talks. You write only their nouns and verbs. You do not invent Manager classes. You pick one scenario: “card fails at 2am, user is in quiet hours, we already emailed yesterday.”

Session 2 (same week). You bring back three boxes and one invariant. They correct the words. You delete a box. This is success.

In the repo. A type or a function with those names exists by Friday, even if it is behind a fake store. The next conversation uses yesterday’s names. If the names only live in your notebook, you did not crunch; you journaled.

After an incident. The postmortem sentence “we should have known X” is a missing concept. Either X becomes a named thing in the model, or you will pay the same bill.

Shallow vs deep

A shallow model maps the current UI and tables. Onboarding is four screens and twelve nullable columns. Every new business rule is a column or a boolean named after a ticket.

A deep model is small and slightly surprising. “OnboardingSession is not the last URL they hit; it is a state machine whose allowed moves depend on Identity.” After that sentence, three features share one invariant instead of three flags.

You cannot schedule a deep model for Thursday. You can schedule the conditions: experts in the room, code that can change, a team that is allowed to rename.

Knowledge-rich means: session.assertCanSelectPlan() fails for a reason you can say to product. It does not mean every policy is a rules engine.

Continuous learning means the model is expected to be wrong. The failure mode of “we already designed it in Q1” is a high-maintenance legacy that looks like a success in the demo.

Example (consumer product, not PCB)

Product wants first-session activation to “just work.”

Uncrunched: users.email_verified, users.onboarding_step, users.plan_id, users.seen_paywall, users.experiment_bucket, plus a frontend switchboard.

After two crunches with someone who owns activation:

Identity: anonymous | claimed | verified. Verified means “email click or trusted provider,” not a single boolean forever.
OnboardingSession: allowed moves, not page paths. Plan selection requires verified identity.
Eligibility: a question the session asks (experiments, geography, already-a-customer). Not CSS.

You threw away seen_paywall as a source of truth (it is a UI fact). You kept a rule experts actually argue about.

A week later they say “verified via provider still needs a billing country.” That is not verified_via_oauth. That is Eligibility absorbing a new fact, or Identity splitting from Profile. You change the model in the open.

Failure modes (strong engineers watch for these)

The transcript model. Every noun the expert uttered became a class. Cognitive load went up.
The report model. You automated their ASCII dump. They still cannot think new thoughts in the software.
The silent genius. One developer “gets it” and writes 4,000 lines. The language never spread. Bus factor is one.
The frozen glossary. A wiki from kickoff. Code drifted. People speak wiki at the standup and code in the PR.

Drill (20 minutes)

Out loud, paper only.

Pick a domain you are not already fluent in (payments, ads, clinical, logistics—whatever you can fake a conversation for).
Invent five messy expert sentences, including two that contradict.
Circle the words that appear more than once. Those are crunch candidates.
Propose three concepts and one invariant that would make the contradiction discussable.
Cross out one concept as “transcript, not model.”
Write the Friday artifact: one function signature the next meeting will use.

If you still have twelve concepts, you have not distilled. Crunch again.