Where we are
You have made seven decisions. Every one of them spent a meter to buy another. Tonight you write them down in a form that answers, two years from now, the only question anybody will ask about them: why did they do it that way?
★ What you walk out with tonight. A complete ADR set for Daybreak, five defects found in a broken architecture, a ship-or-not grade on your own document, and a way of answering "what happens when this fails" that does not require you to bluff.
LiveWhy the reasoning matters more than the diagram2 min▶
Diagrams age badly and are replaced without ceremony. Reasoning ages well and is almost never recorded. The result is the most common failure in this entire discipline: a team inherits a system, cannot see why any of it is the way it is, assumes the constraints no longer apply, and either rebuilds something that was already correct or removes the one thing that was holding it together.
An ADR is a defence against exactly that, and it costs one page. Not a design doc - a design doc argues a whole shape. An ADR records one decision, with its context and its consequences, and it is immutable: when it stops being right you write a new one that supersedes it, and you leave the old one where it is.
That immutability is the whole trick. An edited record tells you what someone currently believes. A superseded record tells you what changed and when, which is the thing you actually needed.
The four-part decision record, and what goes wrong in each part
6 min liveStatus, context, decision, consequences. Four headings, one page, and each one has a characteristic way of being written badly.
LiveOne-way doors and two-way doors4 min▶
The most useful triage question in design: how expensive is it to walk this back? Decisions are not all the same weight, and treating them as if they are is why some reviews take three weeks and some take three minutes - usually the wrong three each.
| Door | Examples | How to treat it |
|---|---|---|
| Two-way | The orchestrator, the BI tool, the load interval, a mart's shape | Decide fast, write one paragraph, move. Time spent arguing exceeds the cost of being wrong |
| One-way | The partition key, the identifier scheme, where PII is allowed to land, the tokenization boundary | Slow down. Write the full record. Get a second reader. These are the ones you live with |
The tell for a one-way door is usually data: anything that determines the shape of stored history is hard to reverse, because reversing it means rewriting the past. Anything that only determines how you process or present is usually cheap to change. Session 6's tokenization boundary is the most one-way decision in this whole course.
LiveThe four questions a good reviewer asks4 min▶
- "What is the requirement, in numbers?" If the answer is adjectives, the review stops here and that is a good outcome. Session 1.
- "What did you reject, and why?" They are testing whether you understand the option you did not pick. A strawman here costs you the room.
- "What happens when this fails?" The answer must name a failure class, a mechanism and a blast radius. "It retries" is not an answer if the failure is permanent. Session 5.
- "What gets worse?" If nothing gets worse, you have not finished analysing. Name it before they do - it is the single fastest way to be trusted in a design review.
And the one question you should ask them: "which of these is a one-way door in your view?" It surfaces disagreement about weight rather than about substance, which is where most stuck reviews actually are.
Review the broken Daybreak
★ 22 min · everyone buildsBelow is a real-looking proposal from a team that has read all the right blog posts. It has five defects. Find them, then write the decision records that fix them.
Self-studyThe five defects, once you have had your own go5 min▶
Try it yourself first - twelve minutes, list what you would raise. Then compare.
- Streaming with no requirement behind it. "Real-time insights" names no decision that changes inside the window and nobody who is awake to take it. On the session 5 board this configuration costs $900 a month extra and adds 12 points of blast radius, and it fails the morning-dashboard budget it was built for. Session 3.
- Retained indefinitely is a deletion design, made by accident. Keeping raw personal data forever in mixed immutable objects means a deletion request cannot be honoured without rewriting history. "Optionality" is the word doing the damage here. Session 6.
- Cron tuned so each stage starts after the previous "typically" finishes. That word is the whole defect. On the day the extract runs long, the transform reads stale input, exits zero and reports success. Session 4.
- The warehouse appends every run. Non-idempotent. One retry doubles revenue, and there is a retry in every system eventually. Session 4.
- No contract layer, and grants per table. 42 assets times 6 roles is 252 access decisions nobody can hold, and an upstream rename reaches 82 percent of everything. The cheapest fix on the board, missing entirely. Sessions 2 and 6.
The sixth thing, which is not a defect but is the one that sinks the proposal in the room: "budget to be confirmed" and "owner: the Data Platform team". No number and no name. A reviewer does not need to understand any of the technology to reject that.
Read the proposal and list what you would raise, in twelve minutes. Write them as questions rather than verdicts - "what decision changes if this is a minute fresher?" beats "streaming is wrong", and it is also how you find out you were the one who was wrong.
Sort your list into one-way and two-way doors. Retention and the identifier scheme are one-way. The orchestrator choice is two-way. Spend the room's time accordingly - this is the skill that separates a useful reviewer from an exhausting one.
Write ADR-001 for the one-way door you care about most. Four headings, one page, negative consequence first. If you cannot fit it on a page, split the decision.
Write the superseding record. Take one decision you made earlier in the course and write the ADR that replaces it, with a status line that names what it supersedes. Practising this once is what makes it a habit rather than an edit.
Rehearse the failure answer out loud. "When the upstream schema changes, N assets break, we find out in M minutes, and the mechanism is X." Say it. The gap between writing that and saying it is where bluffing lives.
Now grade your own document below. This is a ship-or-not gate, not a progress check. The five rows are the things that would embarrass you in a room.
If you take one thing from the whole course. Name what gets worse, out loud, before anybody asks. It is the cheapest credibility available to an architect and almost nobody spends it.
Where to go from here
ongoing- Write one real ADR this week. For a decision already made, retroactively. It will take twenty minutes and you will discover at least one consequence nobody had said out loud.
- Put a contract in one producer's CI. The cheapest lever in the course. One YAML file and one CI job, on the table that has broken you most often.
- Add one data SLA with a clock time and something watching it. Then wait for the first time it fires and note how much earlier you knew.
- Run the profile flip on a real design. Ask what would have to change if the freshness requirement moved by an order of magnitude. The answer tells you how much of your architecture rests on one sentence.
- Then go and build it. learn-data-engineering-with-phoebe for the pipeline, learn-data-warehouse-with-phoebe for the warehouse, learn-dataops-with-phoebe for running it. You now know why you are building what you are building, which is the part those courses assume.
Three questions
Clear all three and session 8 gets stamped in your passport - eight of eight.
1 · A decision recorded in an ADR turns out to be wrong two years later. What do you do to the record?
An ADR is immutable by design. An edited record tells you only what someone currently believes; a superseded one tells you what changed and when, which is the thing a future team actually needs in order not to repeat the reasoning from scratch.
2 · Which of these is most clearly a one-way door?
Anything that determines the shape of stored history is hard to reverse, because reversing it means rewriting the past. Orchestrators and BI tools are migrations, painful but bounded. Where PII was allowed to land is a decision you inherit permanently.
3 · A reviewer asks "what happens when this fails?" and you answer "we have retries and a dead-letter queue". Why might that lose the room?
The complete answer has three parts: which class of failure, which mechanism, and how many assets are affected for how long before anyone knows. Retries handle transient failures only, and a reviewer who has been on call will ask about the permanent ones next.
What this session teaches, and where it came from
Every fact on this page, and its verification tier, is recorded in the course's source map. Certificates, videos and assessments stay with the official providers.
Session 8 cheat sheet · pin this
Eight sessions, one platform, and a document that says why. The thing you can now do that you could not do in session 1 is not draw a better diagram - it is to say, in a room, exactly what you are spending and exactly what you are buying, with numbers, and to be right about the fact that the answer would change if the requirement did. Go and build it: learn-data-engineering-with-phoebe, learn-data-warehouse-with-phoebe, learn-dataops-with-phoebe.