milestone

name	milestone
description	Produce the next guided milestone build doc for dinotable (six-part format - Concept, ADR, Guided build, Challenges, Verify, Stretch). Use when Zoha asks to start a phase, begin a milestone, or requests the next build doc.

Writing a dinotable milestone doc

You are producing the build document that is the plan of record for this milestone. Respect the active mode (the **Active mode:** line in AGENTS.md; full definitions in docs/MODES.md):

• Guided core (apps/api, libs/**, the reservation engine, AI search, infra/**): write the doc only — annotated snippets Zoha types by hand. Never touch those paths. Challenges (part 4) stay required here.
• Frontend (apps/web, apps/back-office, apps/mobile): in autopilot you also write the code after the doc is laid out, narrating the why and ending each chunk with a 30-second review checklist; in guided you deliver snippets only. Challenges are optional in the frontend zone under autopilot — keep one only where implementing it yourself beats reading it.

Either way the six-part doc below is produced first.

Before writing

1. Read docs/design/system-design.md — at minimum §16 (roadmap) and the sections relevant to this milestone.
2. Check docs/adr/README.md and the ADR files: if a decision gating this milestone is still pending, STOP. Present the options and trade-offs in chat with a recommendation, and ask Zoha to write the ADR first.
3. Check docs/milestones/ for the previous doc — number sequentially (<phase>.<n>-<slug>.md) and open with a one-paragraph recap of where the last milestone left the repo, so docs read as a continuous course.
4. Scope check: a milestone should be finishable in roughly 4–10 hours of Zoha's time. If the phase chunk is bigger, split it into multiple docs and say so.

Structure (all six parts, in order)

1. Concept — the problem this milestone solves and how senior engineers think about it. Tie everything to the dinotable domain (reservations, slots, branches, Dhaka traffic patterns). Why before how.
2. ADR — if a real decision is embedded here, lay out options and trade-offs and assign the ADR write-up to Zoha as part of the milestone. If no decision, state which prior ADRs this milestone executes.
3. Guided build — small numbered steps. Every code block has its target file path above it. Annotate the why, not the what. No step should be more than ~15 minutes of typing before something is runnable or observable.
4. Challenges — 20–30% of the milestone's code, deliberately omitted. Each challenge gets: a goal, escalating hints (concept → approach → pseudocode), and its own verification. Good challenges are load-bearing (the milestone is incomplete without them), not busywork.
5. Verify — exact commands and the output Zoha should see. Include at least one "break it on purpose" check where instructive.
6. Stretch — optional depth: benchmarks, an alternative implementation, a reading pointer.

After writing

• Update the status/index where relevant (docs/adr/README.md, design doc §18 table) — docs only.
• If the milestone parks a deep dive to stay on scope (a tangent, a subtle concept), log it as a one-liner in docs/learning-debt.md and, when it fits, surface it as a future milestone or a Stretch item — defer depth, don't lose it. A skipped challenge is learning debt too.
• In chat, give a two-sentence summary: what the milestone covers and what "done" looks like. Remind Zoha to commit their own work as they go.
• Do not start the next milestone or solve this one's challenges unprompted.