Retrospective
Retrospective
Goal: Close Capstone with an honest retrospective, a teach plan for a friend, and a personal roadmap (next nixpkgs release, nixpkgs contribution, optional Capstone B)—without starting a new rewrite today.
This chapter is reflection and direction, not another feature. Protect the freeze tag, keys, and runbook—they outrank any blog post.
Why this chapter exists
Expertise compounds when you teach and schedule the next loop. Without a retrospective, months of labs become a blur. Without a roadmap, Capstone B starts as thrash. Without a teach plan, you never test whether your mental model transfers.
Theory 1 — What you should now be able to do
By Capstone A completion you can:
| Skill | Book roots |
|---|---|
| Explain store, generations, rollback | Concepts, host, internals, DR/rollback |
| Own a flake NixOS host | NixOS host + layout |
| Compose modules with types/assertions | Host + internals modules |
| Manage user or service identity | Host + HM |
| Keep secrets out of the store | Services + Capstone implement |
| Front door proxy pattern | Services + Capstone |
| Deploy remotely (deploy-rs/Colmena) | Ops + Capstone harden |
| Test with nixosTest | Ops + test mastery + Capstone |
| CI + cache discipline | Packaging/ops + Capstone |
| GC/store hygiene | Ops |
| Backup/restore state | Ops backups |
| Read release notes / plan upgrades | Internals |
| Rebuild from zero | Capstone DR |
| Debug with a playbook | Internals troubleshoot + Capstone |
| Steelman alternatives | Comparative landscape |
Mark each: solid / shaky / missing. Shaky items feed the roadmap.
Theory 2 — Retrospective structure (blameless)
| Section | Prompt |
|---|---|
| Goals | What Capstone A required |
| Done | What you actually shipped (with tag SHA) |
| Waived | What you consciously skipped |
| Surprises | What docs/tests/DR revealed |
| Pain | Top 3 time sinks |
| Pride | Top 3 artifacts |
| Would change | Process, not fantasy rewrites |
| Thanks | Upstream/docs/people |
Tone: operator journal, not marketing.
Theory 3 — Teach plan (1 session)
Design a half-day or 1-day session for a friend who knows Linux but not Nix:
| Block | Minutes | Activity |
|---|---|---|
| Why Nix exists | 20 | Store path demo |
| Rebuild + rollback | 40 | Live lab guest |
| Flake tour | 30 | Your Capstone tree |
| Secrets story | 20 | Paths not strings |
| Q&A | 30 | Their context |
Deliverable: docs/TEACH-PLAN.md with commands that work on your freeze tag.
Theory 4 — Roadmap options (pick few)
| Option | When it makes sense |
|---|---|
| Track 26.11 upgrade with your runbook | After notes ship; lab first |
| nixpkgs PR (package or module fix) | You hit a real bug/gap |
| Capstone B multi-node | Hardware + freeze honesty |
| devenv/Snowfall adopt | Only if COMPARE said yes |
| Secure Boot / Lanzaboote | Hardware allows |
| Write public post | After teach plan works once |
Time-bound items (“by date X”) beat eternal backlogs.
Theory 5 — What not to do today
| Do not | Why |
|---|---|
| Rewrite flake layout | Freeze protection |
| Enable CA on Capstone | Internals decision |
| Add five services | Scope creep |
| Delete DR logs | Evidence |
| Un-tick Capstone for aesthetics | Honesty |
Lab 0 — Workspace
mkdir -p ~/lab/nixos/capstone/retro
cd /path/to/capstone-flakeLab 1 — Skills matrix
Fill docs/RETRO.md skills table (solid/shaky/missing) from Theory 1.
Lab 2 — Full retrospective writeup
Write sections from Theory 2. Include:
- Freeze tag SHA
- DR total minutes
- Rollback proof one-liner
- Top waiver
Acceptance: ≥1 page honest prose + tables.
Lab 3 — Teach plan
Write docs/TEACH-PLAN.md. Dry-run the commands yourself once more on lab.
Lab 4 — Roadmap
docs/ROADMAP.md: 3–7 items max, each with trigger date or criterion. Link POST-FREEZE.md ideas selectively.
Lab 5 — Capstone A final sign-off
## Sign-off
- Capstone A: complete / complete-with-waivers
- Tag: capstone-a-freeze @ <sha>
- Date:
- Operator:Paste into CAPSTONE-A.md.
Lab 6 — Celebrate without thrash
Optional: export PDF of docs, or demo for a friend. Do not open a refactor branch “while it’s fresh.”
Common gotchas
| Mistake | Fix |
|---|---|
| Retro as victory lap only | Include waivers and pain |
| Teach plan with broken commands | Dry-run |
| Infinite roadmap | Cap at 7 items |
| Starting Capstone B tonight | Schedule |
| Deleting evidence logs | Keep ~/lab/nixos/capstone/** |
Checkpoint
docs/RETRO.mdcomplete
- Teach plan dry-runnable
- Roadmap time-bounded
- Capstone A sign-off
- Freeze/docs/keys protected
- Three personal gotchas
Commit
git add docs/
git commit -m "capstone: retrospective teach plan and roadmap"Write three personal gotchas—and stop building for a day.
Next
Return to earlier parts as reference, or explore Projects for packaging and distro-branding depth. Capstone A, once signed off, is a stable base—not a perpetual construction site.