Task: Generate USECASES.md — Authoritative User-Perspective Capability Catalogue

Task: Generate USE_CASES.md — Authoritative User-Perspective Capability Catalogue

Objective

Produce a USE_CASES.md that enumerates every use case an actor can perform in the system, grouped by actor and priority, plus the cross-cutting end-to-end scenarios that weave multiple use cases together. The document answers five questions: who uses the system, what each actor needs to do, which stories span multiple capabilities, how use cases map to surfaces (web, CLI, mobile, TUI, voice), and which are in v1 versus deferred. Every downstream surface IA skill, /domain, /architecture, every per-unit /SPEC.md, and /system-verification reads this file to derive its own inventory — orphan use cases and undeclared surfaces cause cascading modelling errors later.

USE_CASES.md is produce-once and read-many. Stable UC-NN IDs assigned here are cited everywhere: entities and aggregates in DOMAIN.md trace back to use cases, per-surface IAs filter the surface matrix to generate their pages/commands/screens, and /system-verify derives its scenario list from § 3 Cross-Cutting Scenarios. Treat every UC-NN ID as permanent — never renumber, never silently drop.

Inputs

1. PROPOSAL.md (required) — § 6 Target Users / Actors seeds the actor catalogue; § 1–§ 2 problem and thesis seed use case discovery; § 3 Core Principles constrain what actors can and cannot do; § 4 Non-Goals bound the capability space; § 7 Scope Boundaries anchors the v1 / v2 / deferred split; § 9 Glossary Stub seeds the use-case vocabulary.
2. Reference material (optional) — user interviews, competitor features, existing product screenshots, internal memos. Use to ground flows in realistic actor behaviour; cite by short name when a use case is drawn from a specific source.
3. Existing USE_CASES.md (auto-discovered — only if refining) — if a USE_CASES.md already exists at the expected path, read it fully. Every assigned UC-NN is permanent. New use cases take the next unused number. Deleted use cases leave their ID marked (retired — superseded by UC-NN) or (retired — out of scope); never reassign a retired number.

Read set size: 1 required + up to 2 optional. The read count at this step is 1 prior ADD artifact (PROPOSAL.md). Read the proposal end-to-end — every actor, principle, non-goal, and scope boundary materially shapes the catalogue.

Workflow

Use case enumeration proceeds in seven phases: actor catalogue, per-actor use case enumeration, cross-cutting scenarios, priority assignment, surface mapping, glossary additions, and validation. Phases are sequential; revisit earlier phases if a later one reveals a missing actor, a missed capability, or a contradiction.

Phase 1: Actor Catalogue

Lift the actor list from PROPOSAL.md § 6. Every actor named in the proposal appears in § 1. Inspect the proposal's problem statement, thesis, and scope boundaries for implicit actors the enumeration missed — a system that "accepts authenticated pushes" implies at least Collaborator (the pusher) and likely Operator (who granted access) even if only one was listed explicitly. Add the missing actors with a note explaining why.

For each actor: assign a short stable name (Operator, Collaborator, Viewer, Anonymous) used consistently throughout the document. Write a 2–4 sentence role description in the actor's voice — what they care about, what problems they face, what authority they wield. State the scale expectation concretely (~1 per deployment, 10–1000 per server, unbounded public traffic). State authority at the capability level (can create and administer repositories), not the permission level (has write access to /api/repos).

If the actor list exceeds seven, consolidate — two "actor classes" with identical authority and scale are the same actor. If it is below three, re-examine whether you have modelled roles separately from scale (an administrative operator and a daily user of the same installation are usually two actors, not one).

Phase 2: Per-Actor Use Case Enumeration

For each actor in § 1, enumerate every capability they can perform. A use case is a discrete unit of value — one trigger, one actor, one postcondition. Prefer many small use cases to few large ones; atomic use cases compose better into cross-cutting scenarios and surface mappings.

For each use case write the full block: UC-NN ID, verb-phrase title, actor, priority placeholder (filled in Phase 4), precondition, trigger, main flow (3–10 numbered steps), alternative flows, postcondition, success criteria, surfaces (filled in Phase 5), notes.

Main flow rules: