rota-vision — Project Vision & Milestones

Milestones are optional structure; nothing else in rota requires one. On the issue backend a milestone is a native tracker milestone MNN — <title> plus a tracking issue (references/issue-mode.md), and the list you write mirrors that. .rota/MILESTONES.md holds a short vision paragraph and the Active list; each milestone's plan is its tracking-issue body (file backend: .rota/milestones/MNN.md).

Copy this checklist and track your progress:

- [ ] Step 1 — Mode
- [ ] Step 2 — Load context
- [ ] Step 3 — Frame and discover
- [ ] Step 4 — Research (opt-in)
- [ ] Step 5 — Challenge
- [ ] Step 6 — Propose, once
- [ ] Step 7 — Write
- [ ] Step 8 — Report

Step 1 — Mode

rota milestone list --json: data.milestones empty → Create; non-empty → Edit (extend, refine, retire, re-prioritize). Don't announce it.

Step 2 — Load context

Follow references/context-load-protocol.md (parallel, silent), plus .rota/MILESTONES.md, rota milestone show <MNN> for each existing milestone, the root stack file (README.md, package.json, …) and rota glossary read <term> for the user's terms. Definitional signals ("by X I mean…") trigger rota glossary write. Issue mode: never read .rota/milestones/*.md. DECISIONS matches constrain what milestones can promise; surface conflicts before proposing.

Step 3 — Frame and discover

Open with 3-4 sentences on what you see: the project's shape, existing milestones, obvious gaps. Then one batched AskUserQuestion (see references/design-exploration.md):

• Create — 2-3 questions: Scope (new product / strategic refactor / research / other), Audience, Constraint (time or scope limit).
• Edit — one question, Action: add a milestone (Recommended if the vision feels incomplete), refine one, retire/activate, re-prioritize, or explore a new direction.

On ambiguity default to the Recommended option and name it.

Step 4 — Research (opt-in)

Skip unless the user asks or the framing leans on outside context (prior art, pitfalls, an unfamiliar space). When it applies, read `research.md`.

Step 5 — Challenge

Push back on the framing; a polite review wastes the cycle. Run the rounds, recommended answers, code-first lookups, edge-case scenarios, term handling and stop condition of references/grilling.md, with these tactics as the lens:

• Scope check — "M02 has 12 acceptance criteria. What's the smaller version that ships in two weeks?"
• Risk frontloading — "M01 assumes auth is straightforward; session storage is the bigger risk. Frontload it?"
• Overlap detection — "M02 and M03 touch the same code 60%. One milestone in two phases?"
• Cut tradeoff — "What would you cut to ship in half the time?"
• Dependency surfacing — "You said M03 is independent, but it needs M01's auth. Mark it, or change M03's scope?"
• Assumption naming — name implicit assumptions ("this assumes single-tenant") and force a stance.
• Why this order — for each adjacent pair, why the earlier comes first.

Batch each round into one AskUserQuestion (max 3 questions; multiSelect: true for choosing trade-offs). Move on when the frontier is empty and the framing has survived honest pushback.

Step 6 — Propose, once

Show the milestone list as plain markdown, not yet saved, one block per milestone:

### M01 — <title>   [ready · no deps]
**Goal:** <one sentence>
**Acceptance:**
- <checkable bullet>
- <checkable bullet>
**Rationale:** <why this one, why now>
**Open risks:** <at least one; if you can't name one it isn't thought through>

The tag is [ready · no deps] or [blocked · depends M01]. No cap on count. Order by dependency layer and make parallel-able milestones visible. Apply the user's redlines (merge, cut, retire, add, re-order) and ask for one explicit confirmation before writing; silence is not confirmation.

Step 7 — Write

Batch the writes, then refresh the index once.

MID=$(rota milestone add --json --title "<title>" --summary "<one line>" [--depends M01,M02] | jq -r .data.id)

Issue mode: creates the native milestone and tracking issue (status planned). Draft the full plan (frontmatter id: <MNN> required) in a scratch file and publish with rota milestone put <MNN> --body-file <file>|-. File mode: mints MNN, a stub .rota/milestones/MNN.md and an overview block; Edit the stub's sections (keep the frontmatter).

• Status: rota milestone status <MNN> --to <planned|active|shipped|archived> per changed milestone. Several can be active when independent. archived retires one without deleting it, but an archived dependency does not unblock dependents; shipped does.
• Vision paragraph (Create only): rota milestone overview --body-file <file>|- (file mode: replace the placeholder under # Milestones), 2-4 sentences on the why. In Edit mode leave it unless the framing changed.
• Index: rota milestone index regenerates the Active list and the managed instructions block. Never hand-edit the Active list.

Step 8 — Report

Vision updated.
- M01 — Auth foundation   [active · ready]
- M02 — Multi-tenant      [planned · blocked by M01]
Active: M01. Run /rota-capture to fill items, or /rota-work to pick from the backlog.

If a newly active milestone has no items, offer (default Capture): /rota-capture to file items, /rota-plan in slice mode for a first slice plan, or skip. Don't recap discovery, research or the challenge.

Key principles

• Challenge, don't transcribe. Surface assumptions, frontload risks, force tradeoffs before anything lands.
• Research is grounding. A finding that doesn't change a milestone's shape doesn't belong.
• Dependencies are explicit. ready vs blocked is computed.
• Thin by design. The tracker's milestone is the source of truth; don't duplicate it in prose.

References

• `research.md`: opt-in web research; read from Step 4.
• `references/context-load-protocol.md`: shared parallel context load.
• `references/knowledge-consult.md`: the K+D query pattern the load uses.
• `references/grilling.md`: the Step 5 challenge rounds.
• `references/subagent-dispatch.md`: the light subagent that grilling sends for broad reads.
• `references/design-exploration.md`: shared spine with /rota-brainstorm.