The Engineering Notebook
Current goal, assumptions, unknowns, decisions, experiments, findings, next step. A notebook in your own words is where independent reasoning is built — and where you can see, at a glance, whether the tool has been doing yours.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
How do you keep your own reasoning about a problem in one place so that it accumulates, survives a day off, and can be checked against what the assistant produced?
Two weeks into the store, the reasoning lives in three chat sessions, a README the assistant wrote, and your memory. You cannot say why the cart is keyed by session rather than user — you remember there was a reason — and the assistant, asked, offers a plausible one that may not be the actual one.
Ask the assistant to summarise the project so far. It reads the code and the chat history and produces a tidy overview: goals, decisions, open questions. It is well organised and it is mostly right, and you adopt it as the record.
The summary is the tool's reconstruction of your reasoning from its artefacts. Where the reasoning was never written, it is invented — the plausible reason for the session-keyed cart is the tool's guess, and it is now the official one (The Assumption Register).
- The summary is the tool's reconstruction of your reasoning from its artefacts. Where the reasoning was never written, it is invented — the plausible reason for the session-keyed cart is the tool's guess, and it is now the official one (The Assumption Register).
- Nothing accumulates. The next two weeks go into more sessions, and the next summary is another reconstruction. The reasoning is regenerated each time instead of built.
- The unknowns list, if the summary has one, is the tool's idea of what you do not know. It cannot contain the thing you were uneasy about on Tuesday and never wrote down.
- You cannot tell which decisions were yours. A notebook written by the tool makes every decision look considered, including the ones that were defaults nobody chose.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Keep one document, in your words, with seven headings: current goal, assumptions, unknowns, decisions, experiments, findings, next step. Update it at the end of every working session, before the tool is closed, in the order the headings are listed. The document is not documentation for others; it is the state of your reasoning, externalised so that it can be re-read, corrected and continued.
- Write each entry as something checkable. A goal is one sentence with an observation attached (What Am I Actually Trying to Achieve?); an assumption says what is being taken as true and what would change if it were false; an unknown is a question with an experiment; a decision has the alternatives it beat and when to revisit it (The Decision Journal); an experiment has a prediction; a finding says which assumption or requirement it changed; the next step is one thing.
- Use the notebook as the input to the tool, not the output of it. When a session starts, the current goal, the open unknowns and the next step are what you bring; when it ends, what the session found goes under findings — in your words, including where the tool was wrong. The notebook is what makes the sequence in Good Tool Use possible across days.
- Read it back to find where the reasoning was not yours. A decision with no alternatives listed was a default; an unknown that has been open for a week with no experiment is being avoided; a finding with no assumption changed was not a finding. The notebook shows these because they are absences on a page, which are easier to see than absences in memory.
A page from the notebook
The notebook is plain text with seven headings. The page below is the store, two weeks in, after the honest reconstruction. Read the decisions section for the field that makes it a decision rather than a default, and the findings section for the crossing-out that makes it learning rather than a log.
1# Current goal2A guest can buy one product and receive a confirmation.3Observe: an order row with no customer id; a sent confirmation email.4 5# Assumptions6- One warehouse, one currency. (changes: stock model, prices)7- Provider confirms asynchronously. (changes: order states, handler)8- ~~Inventory is an application concern.~~ crossed out day 12, see findings9 10# Unknowns11- Why is the cart session-keyed? → read the commit + the chat where it was decided12- Cart when the session expires? → expire one; write what the customer sees13 14# Decisions15- Order created before payment. Beat: payment first (provider needs an order ref).16 Revisit if: provider supports pre-authorisation.17- Cart keyed by session. Beat: user-keyed (blocks guests). Revisit if: accounts + carts must follow the user.18 19# Experiments20- Two concurrent last-unit purchases. Predict: oversell without a constraint.21 22# Findings23- Day 12: it oversold. Constraint added. "Inventory is an app concern" — wrong.24- Day 14: session-keying was mine, reason found: guest checkout. Written above.25 26# Next step27Handle a provider confirmation that arrives after the order was cancelled.Every line is checkable: the goal has an observation, each assumption says what it would change, each unknown has an experiment, each decision has what it beat. The crossing-out is kept, not deleted — it is the evidence that a finding changed something.
The notebook in the session
The notebook is the input to a session and the last thing touched in it. The pipeline shows a working session with the notebook at both ends and the tool in the middle — the same shape as the tool-use sequence, extended across days.
- 1Read next step and open unknowns
The session's purpose, from yesterday's reasoning rather than from the chat history.
fails by Starting from "where was I?" asked of the tool.
- 2Bring goal, assumptions and the unknown to the tool
A question with your system in it, and a prediction.
fails by A fresh session with no context and a vague question.
- 3Work: experiment, implement, observe
The smallest thing that can be observed, against the prediction.
fails by A change too large to attribute.
- 4Findings, in your words
What was learned, including where the tool was wrong, and which assumption it changed.
fails by The tool's summary pasted in.
- 5Decisions, with alternatives
Anything chosen today, what it beat, when to revisit.
fails by Defaults recorded as decisions — or not recorded.
- 6Next step
One thing, specific enough to start tomorrow without thinking.
fails by A list of everything left.
The five minutes at the end are where the reasoning becomes yours. Everything before them can be done with heavy tool use; the findings entry cannot, because it is the check on the tool.
Which heading to fill first
When the notebook is started late — as it usually is — the headings cannot all be filled at once. The order below is one way to reconstruct honestly; the alternative is for a notebook started on day one.
- 1Current goal, with its observation
because Everything else is judged against it, and it is the entry most likely to have drifted while unwritten.
- 2Decisions you can explain, with what they beat
because These are the reasoning that exists; recording them first shows how much of the system was actually decided.
- 3Decisions you cannot explain → moved to unknowns with an experiment
because A decision without a reason is an unknown wearing a decision's clothes; the experiment is usually "read the commit".
- 4Assumptions, each with what it would change
because They surface while writing the decisions — "we chose this because there is one warehouse" — and are cheapest to capture then.
- 5Findings so far, with the assumptions they crossed out
because Most projects have already learned something that changed a requirement; if nothing can be crossed out, either nothing was learned or nothing was written down.
- 6Next step, one line
because The notebook is finished when tomorrow can start from it.
How to do it
Most important first.
- Create the seven headings today and fill them from what you can reconstruct honestly, marking anything reconstructed as such. A "decision" you cannot remember the reason for goes under unknowns as "why is the cart session-keyed?" with an experiment: read the commit.
- End every session with the notebook open: one line under findings, one under next step, and any assumption the session exposed. Five minutes; before the tool is closed, so that the session's claims are checked while they can be.
- Start every session by reading the next step and the open unknowns aloud. If the next step no longer makes sense, that is a finding, and it goes in before anything else.
- Give every decision three fields: what was chosen, what it beat, and what would make you revisit it (Reversible vs Irreversible Decisions). A decision without the second field is a default.
- Once a week, read the whole thing and cross out what is no longer true. The crossings-out are the record of learning; a notebook with none has not been used for thinking.
Worked on a concrete problem
The move has to produce something. This is what it produced.
- The store, two weeks in, reconstructed. Current goal: a guest can buy one product and get a confirmation; observation: an order row with no customer id and a sent email. Assumptions: one warehouse; prices in one currency; the provider confirms asynchronously. Unknowns: why the cart is session-keyed (experiment: read the commit and the chat where it was decided); what happens to a cart when the session expires (experiment: expire one). Decisions: order created before payment — beat "payment first" because the order id is needed for the provider's reference; revisit if the provider supports pre-authorisation. Experiments: two concurrent last-unit purchases — prediction: oversell without a constraint. Findings: it oversold; the constraint now exists; the "inventory is an application concern" assumption is crossed out. Next step: handle the late confirmation after cancel.
- The session-keyed cart, found. The commit message says nothing; the chat session shows the assistant proposed session-keying and you accepted it because guest checkout needed it. That is a real reason and it was never written. It goes under decisions with its alternative — user-keyed, which would have blocked guests — and its revisit trigger: if accounts are added and carts must follow the user.
- The chat app version, one session. Goal: a message sent from one device is seen as read on the other. Unknown: what "read" means with two devices. Experiment: two sessions, one message, read on one. Prediction: the other still shows unread. Finding: it does, and "read" is per user, not per device — the assumption "read is a flag on the message" is crossed out and the data model changes. Next step: a per-member last-read pointer. The whole session fits on a page and the tool was used for the code, not the reasoning.
How you know it worked
What now exists that did not before, and what question you can now ask.
- The notebook has entries in your words from every working day, and the findings section has crossings-out in the assumptions section to match.
- Every decision lists what it beat; the ones that do not have been moved to unknowns.
- A session starts from the notebook's next step, not from the chat history.
- Asked why any part of the system is the way it is, you open the notebook rather than the assistant.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?What is the current goal in one sentence, and what would I look at to see it reached?
- ?Which of my decisions has no alternative recorded — and was it therefore a default?
- ?Which unknown has been open longest, and what is the experiment I have been avoiding?
- ?What did today's session find, and which assumption does the finding cross out?
What can go wrong
- The notebook becomes documentation: tidy, complete, written for a reader, and therefore not updated at the end of a tired session. It is a working document; ugliness is fine, staleness is not.
- The headings are filled once and never crossed out. A notebook that only grows is a log, and a log does not show learning.
- The tool is asked to maintain it. A tool-maintained notebook is the summary reflex on a schedule; the entries stop being checkable because nobody checked them.
- Entries are feelings. "Worried about inventory" is not an unknown; "when two customers buy the last unit, which one wins and where is that decided?" is.
- Five minutes at the end of every session, every session, including the ones that went badly. The cost is small and constant; the reflex's cost is zero until the day the reasoning is needed.
- A notebook in your words is worse-organised than a generated summary, and if someone else has to read it you will have to tidy it. It is not for them.
- Writing decisions with alternatives makes it obvious how many were defaults, which is uncomfortable in proportion to how useful it is.
- "This is a project management tool." It is a reasoning tool. There are no tickets, no owners and no dates; there is what you believe, what you do not know, what you tried, and what you will do next.
- "The assistant can keep it for me." It can draft entries from a session, and that draft is useful — as input to the five minutes in which you check and rewrite it. The checking is where the reasoning becomes yours.
- "Seven headings is a template, and the guide says no rigid templates." The headings are the positions of the loop that survive between sessions; drop one if it is always empty, add one if something keeps not fitting. What is not negotiable is that the words are yours.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALThe seven headings are the loop's positions made persistent; they fit a store, a library or a research task, and the only thing that changes is how often the next step is a line of code versus a conversation.
- TEAM-SPECIFICSolo, the notebook is the only place reasoning lives and must be kept daily. On a team, decisions graduate from the notebook into shared records (ADRs, design notes) once they affect others; the notebook stays personal and the graduation is the moment to tidy.
- ILLUSTRATIVEThe two weeks, the three chat sessions and the reconstructed entries are invented to show the notebook being filled; no real project is described.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto's "review the LLM's answer" at /manifesto/review is what the findings entry does every evening: the session's claims, checked in your words before they become the record.