Week 12 first capstone review

Why this matters

You have one working slice, a spec, and a backlog written before you knew anything. Today you find out how much of that plan survives contact with reality — and you correct the plan, not your memory of it. Teams that skip this step do not discover their scope was wrong; they discover it in the last week, when the only remaining option is to ship something broken.

By the end of the hour you have a demo result per criterion, a written debt list, and a backlog reordered so that the most valuable and riskiest work happens first.

Demo against the acceptance criteria

A demo here is not a performance. It is a measurement: you run the app and check each written acceptance criterion, one at a time, recording PASS or FAIL. The rules matter more than they look.

• Start from a clean state. npm run db:seed, fresh browser tab. A demo on data you nudged into shape yesterday proves nothing.
• Read each criterion aloud before you try it. You will be tempted to demonstrate what the app does rather than what the criterion says. Reading first stops that.
• Do not fix anything during the demo. Write the failure down and carry on. Fixing mid-demo destroys the measurement and eats the hour.
• Record what you saw, not your interpretation. "Shows Date is required under the field" is evidence. "Validation mostly works" is not.

Use a table you can commit:

STORY 1 — Record a calibration
  C1 valid submission appears at top of history      PASS
  C2 empty date shows "Date is required"             PASS
  C3 future date rejected                            FAIL — saved without complaint
  C4 unknown instrument returns 404                  FAIL — returns 500

Two failures out of four is a completely normal first-slice result. What is not normal, and what this format prevents, is not knowing.

Sorting what you found

Every failure and every observation now goes into exactly one of three buckets. The sort is the work; get it wrong and you will spend tomorrow building features while a defect sits in the core workflow.

• Bug — behaviour contradicts a written criterion. C3 and C4 above are bugs. Bugs in the core workflow are the highest priority in the project, ahead of every new feature.
• Missing requirement — the criterion was never written, but the app needs the behaviour. You discover these by using the app: "nothing tells me the save worked when the list is scrolled." Write the new criterion into the spec first, then treat it as work.
• Optional improvement — real, nice, and not required by any criterion. Better spacing, a keyboard shortcut, a nicer date picker. These go to the bottom of the backlog, and most will never be built. That is a success, not a loss.

Keeping these separate is what stops a review from becoming a wish list. A review that returns twenty undifferentiated items tells you nothing about what to do next.

The technical debt list

Technical debt is a shortcut you took knowingly, which will cost more to live with than to fix later. Debt is not the same as a bug: the app behaves correctly, but something about the code or setup will slow you down or bite you later.

Undocumented debt is the dangerous kind, because you will forget the shortcut and then be confused by its consequences. Write each item in four parts:

DEBT 1 — No index on calibrations.instrument_id
  Where:   db/migrations/003_calibrations.sql
  Cost:    history page will slow down past a few thousand rows
  Trigger: fix when seed data exceeds 1,000 calibrations
  Now:     accept — seed data is 20 rows

DEBT 2 — Date validation duplicated in form and route
  Where:   src/web/CalibrationForm.tsx, src/routes/calibrations.ts
  Cost:    the two can drift and disagree
  Trigger: fix before adding the third form
  Now:     accept — server copy is the authoritative one

The trigger is the part that turns a complaint into an engineering decision. "We should tidy this up" never happens. "Fix before the third form" is a condition you will actually notice.

Scope correction

Now the arithmetic, and it is the reason today exists. Cut scope when optional work threatens the core usable outcome — not when you feel behind, not never, but at the specific moment the remaining plan no longer fits the remaining time.

Work it out in numbers rather than feelings:

1. Measure your real rate. How many sessions did SLICE 1 take, honestly, including the parts that went badly? That is your rate. Not the rate you hoped for.
2. Count the sessions you have left, then subtract the ones already spoken for. The remaining days of this course include reviewing, documenting, and demonstrating — those are not building sessions.
3. Count the slices left in your backlog.
4. Compare. If slices remaining × sessions per slice is greater than your building sessions left, the plan does not fit. It will not start fitting by itself.

When it does not fit, cut in this order — and cut before you start the work, not halfway through:

• Optional improvements go first, all of them, without discussion.
• Then whole stories that are not the core workflow. Deleting a story is cheaper than half of three.
• Then depth within a story: no pagination, one sort order, no editing. A workflow that only goes forwards is still a workflow.
• Never cut the core workflow, the failure cases in it, or the checks. An app that half-works on the happy path and collapses on an empty field is not smaller — it is unfinished.

Write down what you cut and why. A recorded cut is a decision you can defend and reverse; a silent one is a feature you will half-build at 11pm.

Walkthrough: reordering the backlog

Take everything you now have — bugs, missing requirements, remaining slices, optional items — and give each one two marks.

Value: does the primary user's core workflow depend on it? High, medium, or low. Risk: how likely is it to take much longer than you think? High risk means unknown technology, an unclear design, or something you have never done.

Then order: high value first, and within equal value, high risk first. That last part is counter-intuitive and it is the important one — doing the scary thing early is what gives you time to change the plan if it goes wrong. Save it for last and it becomes the reason you miss the end.

REVISED BACKLOG (after Day 84 review)
1. BUG  C4 unknown instrument returns 500, must be 404   value high   risk low
2. BUG  C3 future date accepted                          value high   risk low
3. SLICE 2 overdue instruments (derived due date)        value high   risk high
4. REQ  confirmation message after save                  value med    risk low
5. SLICE 3 edit a calibration                            value med    risk med
--- cut line: everything below is optional ---
6. nicer date picker
7. keyboard shortcut for the form

That cut line is worth drawing literally. It converts "we'll see" into a visible decision, and it makes the next few sessions a matter of working down a list rather than choosing under pressure.

Your turn

1. Run the demo from a freshly seeded database. Record PASS or FAIL for every criterion in docs/review-week12.md. Fix nothing while demoing.
2. Sort every finding into bug, missing requirement, or optional improvement. Add any missing requirement to docs/spec.md as a proper criterion before treating it as work.
3. Write the technical debt list, three items minimum, each with where, cost, trigger, and your decision now.
4. Do the scope arithmetic: your real rate, building sessions left, slices remaining. Write the four numbers down.
5. Apply the cut test to every remaining item and cut in the order given. Record each cut and its reason.
6. Rewrite the backlog with value and risk marks, ordered high value first and high risk first within equal value, with a visible cut line.
7. Run the reviewer prompt, sort its findings yourself, then commit: docs: week 12 review and revised backlog.

Common pitfalls

• Fixing during the demo. You lose the measurement and the hour, and you usually find the second bug only after the first is patched.
• Demoing on hand-tuned data. The bugs you most need to see live in the states you avoided.
• Cutting the failure cases to save time. They are the difference between an app and a demonstration. Cut a whole story instead.
• A backlog ordered by what is fun. Fun work is usually low risk and low value. Order by the two marks, then work top-down.

Verify it yourself

Open today's reference, OpenAI's Codex CLI documentation.

1. Find what it says about giving the agent the context it needs for a task. Compare with your revised backlog — could you paste item 1 straight in, or does it still assume things only you know? Rewrite it until it stands alone.
2. Look for anything about reviewing or verifying the agent's output. Note one verification step you have not been doing, and add it to AGENTS.md under the definition of done.

A backlog item that can be handed over without explanation is the same artifact as a good agent task. Getting item 1 to that standard is what makes tomorrow start quickly.