The Week Generator

Weeks 1–12 are written out session by session. Weeks 13–130 are not, and deliberately so: pre-writing 118 weeks two years in advance produces fiction, and fiction you then feel obliged to follow.

What you need instead is the procedure that produced weeks 1–12, so you can run it yourself at the start of every project. That is this page: an algorithm, the invariants a valid decomposition must satisfy, three fully worked examples, and the re-planning procedure for when a week goes wrong.

Time cost: 45 minutes per project, in the last session before it starts. Fourteen times over the journey.

Table of Contents

• Why This Is a Generator and Not a Schedule
• The Algorithm
• The Eight Invariants
• Worked Example 1 — P02, a Medium Project
• Worked Example 2 — P04, With a Mid-Project Pivot
• Worked Example 3 — P05, a Large Project With a Kill Switch
• Decomposition Smells
• Re-Planning Mid-Project
• The Week-Zero Ritual
• References

Why This Is a Generator and Not a Schedule

Three reasons, and the third is the one that matters.

1. Estimates decay. By the time you reach P12 in month 27 you will know your own throughput on this kind of work far better than I do now. A schedule written today encodes my guess; a generator run then encodes your measurement.

2. Projects reshape themselves. P02's milestone 7 (the neighbour-selection heuristic) might take four hours or twelve depending on what milestone 5 taught you. A decomposition made after milestone 5 is strictly better than one made before it.

3. Producing the decomposition is itself the planning skill. Deciding what constitutes a week's worth of work, what can be verified at the end of it, and what depends on what — that is project management at the scale where you actually control the variables. Handing you 118 pre-baked weeks would remove the one form of estimation practice this journey naturally provides. You will be estimating for the rest of your career; here you get fourteen calibrated repetitions with recorded predictions and recorded actuals.

This is the same argument as step 3 of the loop. Write your own design before reading the canonical one. Write your own weeks before reading someone else's.

The Algorithm

Inputs: the project page's milestone table (numbered, with hours), experiments table, readings table, and exit criteria. Output: one row per week with the six weekly outputs.

Step 1 — Check the budget reconciles

Sum the milestone hours. It must equal the project's stated budget.

Σ milestone hours  ==  project budget  ==  weeks × your pace

If it does not, one of them is wrong and you must fix it now, not discover it in week 6. When I first wrote these fifteen project pages, six of them over-allocated their milestone tables by 4–10 hours against their own budgets; a thirty-second script found all six. Run the check.

Step 2 — Normalise milestone sizes

• Any milestone > 12 h is split. It will not fit in a week alongside the week's other obligations, and a milestone spanning three weeks gives you no completion signal for a fortnight.
• Any milestone < 3 h is merged into an adjacent one. Sub-3-hour items are tasks, not milestones, and tracking them adds ceremony without information.

Step 3 — Reserve the non-implementation hours

Your pace is 11 h/week, but implementation is only 45% of it (allocation). The milestone hours are the implementation. So:

\[ \text{weeks} = \frac{\Sigma\,\text{milestone hours}}{11} \quad\text{and each week has}\quad \begin{cases} \sim 5.0\ \text{h implementation (milestones)}\ \sim 1.7\ \text{h reading}\ \sim 2.2\ \text{h experiment}\ \sim 1.1\ \text{h writing}\ \sim 1.1\ \text{h debug/review} \end{cases} \]

This is the step everyone gets wrong, and it is why self-made plans overrun by ~2×. The milestone hours are ~45% of your week, not 100% of it. A 77-hour project is 7 weeks at 11 h/week — not 77/11 = 7 weeks of pure milestone work crammed into 7 weeks.

The project pages already do this arithmetic for you: P02's 77 milestone hours are budgeted as 7 weeks precisely because 77 h ÷ 11 h/wk = 7, with the milestone hours counted as the whole week rather than 45% of it. That is a deliberate simplification — the milestone estimates are generous enough to absorb the reading and experimentation attached to them. If your actuals say otherwise after two projects, re-derive with the 45% rule and lengthen everything.

Step 4 — Pack milestones into weeks

Greedy, in dependency order, filling to ~11 hours per week:

week = 1; budget = 11
for each milestone m in order:
    if hours(m) <= budget:
        assign m to week; budget -= hours(m)
    else if budget >= 3:
        split m: put `budget` hours in this week, remainder in the next
    else:
        week += 1; budget = 11; assign m to week; budget -= hours(m)

Then adjust by hand for the invariants. The greedy pass gets you 80% there in five minutes; the hand adjustment is the other 40 minutes and is where the judgement lives.

Step 5 — Attach reading

Take the project's readings table and attach each item to the milestone that needs it, scheduled for the week before or during that milestone — never front-loaded.

Front-loading reading is the single most common self-planning error in this kind of work. It feels responsible and it destroys step 3 of the loop: read HNSW in week 1 and your own graph design in week 3 is a half-remembered copy.

Step 6 — Attach one experiment per week

Every week gets exactly one, from the project's experiments table, or — early on, before there is anything to measure — a correctness property test.

Order them so that each week's experiment is possible given what exists. Do not save all experiments for the end: the whole point of the 20% experimentation budget is that measurement runs alongside building, so that a wrong design is caught in week 3 rather than week 8.

Step 7 — Name the deliverable and the reflection prompt

For each week: what will exist on disk on Sunday that does not exist on Monday? If you cannot name it in a noun phrase, the week is not well formed.

The reflection prompt should be specific to the week, not "what did I learn". Good prompts: "which of my three predictions about block size was furthest off, and was I wrong about the mechanism or the magnitude?"

Step 8 — Run the invariant check, then commit it

Write the table into notebook/weekly/PLAN-<project>.md and commit it before the project starts. It is a prediction, and like every other prediction in this journey it is worth more with a timestamp on it. At the end of the project, diff planned against actual — that diff is your estimation calibration data.

The Eight Invariants

A decomposition that violates any of these is malformed. Check before committing.

I1 and I7 together mean a Medium project has ~6 weeks of real mechanism, not 8. Plan for that and the schedule holds; plan for 8 and it does not.

Worked Example 1 — P02, a Medium Project

Input: P02, 77 hours, 7 weeks (W9–W15), 12 milestones.

Step 1 — reconcile

4+5+4+6+9+10+8+8+5+4+8+6 = 77 ✓ equals the stated budget.

Step 2 — normalise

Largest is m6 at 10 h — under 12, no split needed. Smallest is m1/m3/m10 at 4 h — above 3, no merge. No changes.

Step 3–4 — greedy pack

Week 14 overflows. Hand adjustment: move m9 (persistence, 5 h) to week 15 and pair it with m10 (deletion, 4 h), pushing m11 (sweeps, 8 h) and m12 (report, 6 h) — which is now 14 h in one week and violates I7.

The greedy pass has told us something real: 77 hours over 7 weeks leaves no room for a slack week. Resolution — merge m9 and m10 (both small persistence-adjacent work, 9 h together) into week 14, and let week 15 be sweeps + report with sweeps largely running unattended.

Step 5–7 — the finished plan

Invariant check

I7 is knowingly violated, and that is recorded rather than hidden. The mitigation: w15's sweeps run unattended, so the wall-clock cost is low even though the hours are allocated. If w13's Algorithm 4 work overruns — likely, since it is the subtlest milestone — the declared cut is m10 deletion, which no downstream project needs. Deciding the cut now, while calm, is worth more than deciding it in week 14 under pressure.

Worked Example 2 — P04, With a Mid-Project Pivot

Input: P04, 99 hours, 9 weeks (W35–W43), 13 milestones: 6,8,6,8,8,6,5,8,10,12,8,8,6 = 99 ✓

This project has a structural feature P02 does not: two compaction strategies (m9 size-tiered, 10 h; m10 leveled, 12 h) where the second is the most likely thing to be cut. The decomposition must make that cut cheap.

The pivot, planned in advance

Decision point: end of week 40. If leveled compaction is not running by then:

Naming the cut, its trigger week, its cost and its wording in advance is the entire technique. A cut decided at week 42 under pressure is an abandonment; a cut decided at week 35 and executed at week 40 is a plan.

Worked Example 3 — P05, a Large Project With a Kill Switch

Input: P05, 143 hours, 13 weeks (W55–W67), 14 milestones: 10+12+8+12+12+14+14+8+8+8+10+10+12+5 = 143 ✓

Two structural features shape everything: the fault injector is built first (m2, before any distributed feature), and this is the project most likely to overrun in the whole journey.

The kill switch

Hard decision point: end of week 65 (week 11 of 13).

If the linearizability checker is not clean across ≥1,000 seeded runs by then:

CUT   m11 membership, m12 snapshots, m13 sharding   (32 h ≈ 3 weeks)
SHIP  single-shard Raft, correct, with the injector and the checker
WRITE "Multi-shard routing, membership changes and snapshots are not implemented.
       The system is a correct single-shard replicated log."

Why this is the right cut and not a failure. P05's exit criteria are about correctness under fault injection, not about feature count. A single-shard Raft with zero linearizability violations across 1,000 seeded fault runs, a replayable injector, and a documented real bug fully satisfies every exit criterion except the rebalancing one. A three-shard system that fails the checker satisfies none of them.

And the two artifacts with independent portfolio value — faultinjector/ and linchecker/ — are both delivered by week 59, four weeks before the decision point. The plan front-loads the things that survive a cut. That is the design principle for decomposing any Large project.

Note the reading pattern

Raft §5.4.2 appears in weeks 61 and 62, deliberately twice, and the extended paper is spread across weeks 57–62 rather than read up front. The one subtle safety property in the paper is read immediately before the milestone that implements it and again immediately after — because that is the point at which you can actually tell whether you understood it.

Decomposition Smells

Six patterns that mean the plan is wrong. Each is a real failure I have seen in the examples above or built into these pages on purpose.

The experiment clump is the most damaging and the most common, because building feels like progress and measuring feels like a detour. It is also the smell that converts this journey back into an ordinary build log.

Re-Planning Mid-Project

Weeks go wrong. The response is a procedure, not an improvisation.

One week behind

Absorb it. Shift everything right by one week and take it out of the project's slack week (I7). Do not compress a milestone to catch up — compression removes the experiment and the reflection first, which are the two things that make the week worth having done.

Two weeks behind

Cut, do not compress. Go to the project page's three scope tiers and drop from standard toward MVI. Record it in EXIT-CRITERIA.md's scope-cuts table the day you decide, with the trigger and the cost.

Then re-run steps 4–8 of the algorithm on the remaining milestones. It takes fifteen minutes and it produces a plan you believe, which a silently-slipping plan is not.

Three or more weeks behind, or a milestone stalled

This is the two-week stall rule, and it is a written decision among four options: reduce scope, change approach, ask for help, or cut the milestone.

At the project level, one additional question: is the pace wrong rather than the plan? If two consecutive projects have run 30% over, your actual pace is ~8.5 h/week, not 11. Re-derive the whole journey from the duration table and move the end date. A 40-month journey completed beats a 34-month journey abandoned in month nine.

The calibration you get for free

At the end of each project, put planned against actual in the report:

After three projects you will know your personal estimation bias — most people are consistently 20–40% optimistic, and knowing your own multiplier turns every subsequent estimate into a good one. This table is the single most valuable by-product of running the generator, and it does not exist if the weeks were handed to you.

The Week-Zero Ritual

45 minutes, in the last session before a project starts. Fourteen times.

1. Reconcile the budget (step 1). 2 min.
2. Run the greedy pack (steps 2–4). 10 min.
3. Hand-adjust for the invariants (step 8 check). 20 min — this is the real work.
4. Attach reading and experiments (steps 5–6). 8 min.
5. Name the cut: for any Medium or Large project, which milestone goes first, at which trigger week, and the sentence you will write in the report. 5 min.
6. Commit notebook/weekly/PLAN-<project>.md.

Then, and only then, run scaffold/new-project.sh and start week one of that project.

Do not skip step 5. A cut named while calm costs five minutes; the same cut decided under pressure in week 11 costs a weekend of rationalising and usually takes the wrong thing.

References

• Brooks, F. P. The Mythical Man-Month, anniversary ed. Addison-Wesley, 1995. Chapter 2 on why projects slip one day at a time, and why adding effort to a late project makes it later — the reason the re-planning procedure cuts scope rather than adding hours.
• Boehm, B. W. Software Engineering Economics. Prentice-Hall, 1981. The cone of uncertainty: estimates made at the start of a project are reliably off by a large factor, and the correct response is re-estimation at checkpoints rather than better initial guessing.
• DeMarco, T. Controlling Software Projects. Yourdon Press, 1982. "You cannot control what you cannot measure" — the argument for the planned-vs-actual table.
• Cohn, M. Agile Estimating and Planning. Prentice Hall, 2005. On relative estimation and on why estimates improve with recorded feedback, which is what the calibration table provides.
• Tetlock, P., Gardner, D. Superforecasting. Crown, 2015. Calibration improves only when predictions are recorded and scored — the same reason notebook sections 1–8 are committed before the run.
• Kahneman, D., Tversky, A. Intuitive Prediction: Biases and Corrective Procedures. 1977. The planning fallacy, and the outside view as its correction — which is exactly what your own planned-vs-actual multiplier becomes after three projects.