02 — The Lab Notebook

Predict, then measure. Every time.

The single fastest way to become a better engineer is to write down what you expect to happen before you run the code, and then honestly compare it to what did happen. Do this for a year and your intuition about JVMs, garbage collectors, thread contention, database query planners, and API latencies will sharpen dramatically. Skip it and you will read about performance for a year and still not have good instincts.

This is not a productivity ritual. It is a calibration ritual. The point is to notice, over hundreds of tiny predictions, where your model of the world is wrong.

Why This Matters More For You Specifically

You have been using AI agents for two years. AI is very good at giving you answers. It is very bad at telling you when it is confidently wrong. If you accept AI answers without a prediction step, you never build the muscle to notice bad answers. You outsource not just the coding but the reasoning about whether the code is right.

The lab notebook is the antidote. Before you run a benchmark, before you refactor a class, before you accept an AI suggestion — write your prediction. Then measure. The delta is where learning lives.

The Notebook Template

Every notebook entry has six fields. Keep them short. This is a lab notebook, not an essay.

---
Date:       2026-07-14
Project:    phase01-fundamentals
Context:    ArrayList vs LinkedList get(i) benchmark

Hypothesis: LinkedList.get(i) is O(n); ArrayList.get(i) is O(1).
            Therefore for a random-access-heavy workload on 100k elements,
            ArrayList should be 100-1000x faster.

Prediction: ArrayList ~50 ns/op, LinkedList ~10-50 µs/op. Ratio ~500x.

Actual:     ArrayList 42 ns/op, LinkedList 180 µs/op. Ratio ~4300x.

Delta:      Ratio was 8x larger than I predicted. LinkedList was much worse
            than my mental model — probably cache misses on top of O(n) walks.

Lesson:     Big-O predicts asymptotic behavior. It does not predict constants.
            For 100k+ elements on modern CPUs, cache locality dominates.
            Update mental model: LinkedList.get is *dramatically* worse than
            "just O(n)" would suggest.
---

Six fields. Predictions are numeric where possible — “faster” is not a prediction; “~500x faster” is. Vague predictions cannot be falsified, which means they cannot teach.

When To Write A Notebook Entry

Not for every line of code. That would be exhausting and pointless. Write an entry when:

  • You are about to run a benchmark or a profiler

  • You are about to refactor code and expect a specific behavior change

  • You are debugging and have a theory about what is broken

  • You are learning a new API and predicting its behavior from docs

  • You are reading an AI or Stack Overflow answer and want to test whether it is actually right

Rough target: 3-5 notebook entries per sprint. Fewer than 3 and you are not testing your model enough. More than 10 and you are procrastinating on writing code by writing notes about writing code.

Where To Keep The Notebook

Two places, and this matters:

1. LAB.md inside each project repo. Local to the code. When you look at the project six months later and wonder why you chose ConcurrentHashMap over synchronizedMap, the notebook entry is right there next to the code. Commit it with the code.

2. A personal vault — Obsidian, Logseq, or a plain-text folder called lab/ in a private git repo. Cross-project. The place where you can search across months for patterns (“every time I predicted GC pauses I was wrong by a factor of 3”). This is where calibration happens over the long run.

Cross-post entries when they contain a lesson worth remembering. Most entries stay in the project LAB.md. Maybe 20-30% get pulled into the personal vault.

The Weekly Review Ritual

Every Sunday morning (before the sabbath day, or on the same day if you review over morning coffee), spend 15-20 minutes on this:

  1. Open your personal vault.

  2. Read the entries from the past week.

  3. Look for patterns in the delta field — are you consistently over- or under-predicting something?

  4. Write one line at the bottom of the week: “This week I was consistently wrong about ___.”

  5. Note it in the sprint retro.

After a quarter of doing this, you will start to catch yourself mid-prediction: “Wait, I always overestimate string concatenation performance. Let me be more careful.” That moment is worth more than any single technical fact you will learn this year.

Special Notebook Entries

Some entries are worth calling out with a heavier template.

“AI Was Wrong” entries

When an AI (Claude, Copilot, ChatGPT) gives you code or a claim, and your prediction + measurement shows it is wrong — tag it #ai-was-wrong in the notebook. Keep these. Over the year, they build your gut check for “can I trust this answer?” This is not about beating up on AI. It is about learning where AI confidence is uncorrelated with correctness.

“I Was Wrong” entries

When your prediction is off by a factor of 10 or more, or was qualitatively wrong (“I thought X, actually Y”), tag it #surprised. Review these at the end of each quarter. They are the highest-signal entries in your notebook.

The Anti-Pattern To Avoid

The notebook is not a diary. Not a todo list. Not a “learnings for the day” scratchpad. Those things are fine — keep them elsewhere. The notebook is specifically prediction-then-measurement. If an entry has no prediction, it is not a lab notebook entry, and it goes in a different file.

The temptation will be to skip the prediction field because you “don’t know yet.” Write it anyway. “I don’t know, but I’d guess ~10ms” is a valid prediction. Vague predictions are still testable. No prediction is not.

Concrete First Entries

Here are three concrete predictions you can make in your first week to prime the habit:

  1. String concatenation: predict how long += in a loop takes for 1M iterations vs StringBuilder. Then run both.

  2. HashMap resize: predict the throughput drop when a HashMap crosses its load factor threshold during a load test.

  3. Autoboxing: predict how much slower Integer addition is than int addition in a tight loop. Then measure.

All three are surprising. Do them in week 1. The results will hook you on the habit.

Next: 03_benchmark_hygiene.md Previous: 01_sprint_cadence.md