Day 82 — Capstone design doc

Updated

July 30, 2026

Day 82 — Capstone design doc

Stage VIII · ~3h
Goal: Choose one capstone option (A agent / B microservice / C CLI), write a design doc with scope, architecture, milestones (Days 83–88), risks, and demo criteria—before building.

Important

Pick exactly one option. Syllabus rule: avoid A+B+C. Depth beats breadth.

Why this day exists

Days 83–88 are six build days. Without a design doc you will:

  • Start three products
  • Skip tests until Day 89 panic
  • Demo vapor

Writing forces trade-offs while Stage I–VII skills are still loadable into one system. Design day is not optional ceremony—it is the cheapest bug you will prevent.

Theory 1 — Capstone options

Option A — Control / observability agent

Session-2 flavored. A long-running agent that:

  • Watches processes, containers, or host metrics
  • Exposes a small control API (HTTP)
  • Emits slog + Prometheus metrics
  • Runs containerized
  • Optional: light actions (restart policy stub, label-based filters)—keep safe

Success looks like: agent runs, scrapes metrics, API authenticates, container ships, demo scripted.

Risks: host permissions, docker socket exposure, accidental dangerous actions. Prefer read-mostly + dry-run.

Option B — Domain microservice

Deepen/rebuild a coherent domain service:

  • REST (optional gRPC)
  • DB + migrations
  • Auth
  • Tests (unit + integration)
  • Metrics + graceful shutdown
  • Container

Success looks like: end-to-end user story on API, data persists, Stage VII quality retained.

Risks: domain sprawl (CRM, payments, multi-tenant). Keep one noun graph small.

Option C — Serious CLI product

Multi-command tool with:

  • Polished help/exit codes
  • Tests for core logic
  • Release artifacts (multi-OS/arch)
  • Optional: config files, plugins-lite, Nix packaging note
  • Optional: works as kubectl-style plugin

Success looks like: demo.sh walks main flows; binaries installable; README excellent.

Risks: endless flag surface. Prefer three commands done well.

Theory 2 — Design doc template

Create CAPSTONE.md (or docs/capstone.md):

# Capstone design

## 1. Choice
Option: A | B | C
One-sentence pitch:

## 2. Problem & user
Who uses it?
What job does it do in 60 seconds?

## 3. Non-goals
- ...
- ...

## 4. Architecture
### Packages
### Diagram (ASCII)
### Data stores / external systems

## 5. Public surface
### API routes or CLI commands
### Auth model
### Config surface (env/flags)

## 6. Quality bar
- [ ] go test ./...
- [ ] vet + staticcheck
- [ ] govulncheck
- [ ] metrics / profiles (as applicable)
- [ ] container or release binaries
- [ ] graceful shutdown (services)

## 7. Milestones (map to days)
| Day | Goal | Done when |
|-----|------|-----------|
| 83 | Skeleton + modules + CI script | ... |
| 84 | Core domain path | ... |
| 85 | Persistence / adapters | ... |
| 86 | API or CLI UX complete | ... |
| 87 | Observability + hardening hooks | ... |
| 88 | Integration polish + demo script | ... |
| 89 | Evidence pack | ... |
| 90 | Retro | ... |

## 8. Risks
| Risk | Mitigation |
|------|------------|
| Scope creep | Non-goals list |
| New dependency rabbit hole | Prefer stdlib |

## 9. Demo script outline
1.
2.
3.

## 10. Open questions
-

ASCII architecture examples

Option B:

[cli/main] → [adapter/http] → [app/service] → [port interfaces]
                                  ↓
                            [adapter/sqlite]

Option A:

[loop ticker] → [collector] → [store snapshot]
       ↓
[http control API] ← auth → [actions (optional dry-run)]
       ↓
[/metrics]

Option C:

main → cli router → domain packages
                 → config file
                 → testdata fixtures

Theory 3 — Scope budgeting

Six build days ≈ 18 focused hours. Budget:

Bucket Share
Vertical slice happy path 40%
Tests 20%
Operability (metrics, config, shutdown) 20%
Polish / demo / docs 20%

If a feature is not on the demo script, it is a non-goal.

Vertical slice definition

A vertical slice is one user job that touches the real stack:

Option Example slice
A Snapshot once + serve /metrics + /healthz
B Create resource + persist + GET by id
C init + apply --dry-run + status

Horizontal “all packages empty” is not a slice.

Theory 4 — Reuse vs rewrite

Prefer reuse of Stage VI–VII service as option B core. Option A/C may start fresh modules but steal packages (config, flags, http middleware).

# good
capstone/ reuses internal/auth patterns from earlier labs

# bad
greenfield everything including custom JSON stack

Inventory in the design doc:

## Reuse inventory
- config.Load pattern from day77
- middleware from day54
- Dockerfile from day68

Theory 5 — Demo criteria are acceptance tests

Write demo steps that a stranger could run:

## Demo (must work Day 90)
1. `go test ./...`
2. `./demo.sh` exits 0
3. Shows: create book, loan, return (B example)
4. `curl /metrics` has http_requests
5. SIGTERM drains without error spam

If a step needs a cloud account, redesign for local Docker/SQLite.

Worked example — Option B pitch (sample)

## Choice
Option B — “Shelf” small library loan API

Pitch: Track books and loans for a single library branch via REST + SQLite.

Non-goals: payments, multi-tenant SaaS, mobile apps, gRPC.

Commands demo:
1. migrate + run
2. create book, create member, loan, return
3. metrics scrape, kill -TERM drain

Worked example — Option A pitch (sample)

## Choice
Option A — “Pulse” process snapshot agent

Pitch: Periodically samples local process list + exposes Prometheus metrics and a read-only HTTP API.

Non-goals: remote shell, auto-kill without dry-run, multi-cluster.

Demo:
1. run agent
2. curl /v1/snapshot
3. curl /metrics
4. docker run + SIGTERM

Worked example — Option C pitch (sample)

## Choice
Option C — “shipctl” release checklist CLI

Pitch: Validate a directory of deploy manifests and produce a go/no-go report.

Non-goals: full CD platform, cluster apply by default.

Demo:
1. shipctl init
2. shipctl check ./testdata/ok
3. shipctl check ./testdata/bad (exit 1)
4. multi-arch build-release.sh

Lab

Suggested workspace: new or existing capstone module root.

  1. Choose A, B, or C; write it at the top of CAPSTONE.md.
  2. Fill all template sections—especially non-goals and milestones.
  3. List concrete demo steps (must be executable on Day 90).
  4. Inventory reusable code from earlier days.
  5. Optional: open issues/TODO comments matching milestones—no feature coding required today beyond spikes ≤30 min if blocked on feasibility.
  6. Commit the design doc even if empty module.

Decision timer

If stuck >20 minutes between two options: pick B if you have a Stage VI service; else C if you prefer local tools; A if you care about agents/ops.

Spike rules (optional ≤30 min)

Allowed: verify a library compiles, open a SQLite file, list processes once.
Forbidden: building Day 86 features “just to see.”

Common gotchas

Gotcha Fix
Design doc as essay without milestones Table Days 83–88
Building during design day Stop; capture spike notes only
Optional everything One auth story, one data story
Ignoring quality bar Copy Stage VII gate into §6
Demo requires cloud accounts Prefer local Docker/SQLite
Three options “slightly started” Delete two; one CAPSTONE.md choice
Unmeasurable done-when Binary checks: “curl returns 200”

Checkpoint

  • Single option chosen
  • CAPSTONE.md complete
  • Non-goals explicit
  • Day-by-day milestone table
  • Demo outline written
  • Reuse inventory listed

Commit

git add .
git commit -m "day82: capstone design doc"

Write three personal gotchas before continuing.

Tomorrow

Day 83 — Capstone build 1: repository skeleton, tooling, and the first runnable vertical spike per your design.