| name | cockburn-use-case |
| description | Promote a slice's brief use case (from requirements-intake) into a fully-dressed Cockburn system use case at docs/design/<slice>/use-case.md. Use at stage 2 of the planning pipeline, per slice, once the slice backlog exists — it is the definitive behavioral spec and the traceability source for component tests (each Extension → one failure mode → one error code). Do NOT use to elicit requirements from scratch (that is requirements-intake) or to design modules (program-design). Tier-agnostic: fixed fully-dressed template, a traceability rule, checklist, STOP rules. |
cockburn-use-case.skill — fully-dressed system use case for a slice
Purpose
In: one slice from .agent/planner/slices.md (stage 1) + its brief user-goal use case in the
FRD (requirements-intake Step 2) + the frozen contract. Out: a fully-dressed Cockburn
system use case at docs/design/<slice>/use-case.md.
requirements-intake writes use cases briefly, at user-goal level, across the whole service.
This skill expands one slice's use case to the fully-dressed level that downstream stages
need: it is the behavioral source of truth and drives the component tests (stage 5).
Scope
DO:
- Expand exactly one slice's use case to fully-dressed form.
- Keep every Extension consistent with the failure-mode map and the contract. The cross-artifact
traceability key is the
error.code (stable across FRD ↔ use-case ↔ contract), not the
Cockburn a/b/c label — the label is local step-numbering and MAY differ from the FRD's. Every
Extension MUST carry its error.code.
- Sit the use case next to
c4.md in docs/design/<slice>/.
DON'T:
- Elicit new requirements or invent actors/errors (that is
requirements-intake — go back).
- Design module trees, contracts, or tests (later stages).
- Add file paths or code.
Fully-dressed template → docs/design/<slice>/use-case.md
# UC-<NN>: <goal as an active verb phrase>
- **Primary actor**: <who initiates>
- **Scope**: <this service / context>
- **Level**: user-goal <!-- sea level; summary/subfunction only if justified -->
- **Stakeholders & interests**: <actor + each stakeholder and what they need from this UC>
- **Precondition**: <what must be true before>
- **Trigger**: <the external input — one endpoint / one consumed message>
- **Minimal guarantee**:
:
...
: →
: →
Rules (hard)
- One trigger. The use case has exactly one trigger = the slice's one external input
(1 slice = 1
Request). More than one → the slice is too coarse, go back to vertical-slices.
- A failure/framework/boot is NOT a use case — it is an Extension. One external request = ONE
use case; its error outcomes (4xx/5xx, store failure, bad input) are Extensions of it, never
separate use cases. Anti-examples (all WRONG as top-level UCs): "Bad request / invalid sort"
(input-validation → Extension), "Method not allowed (405)" / "Unknown route (404)" (HTTP framework,
not a user goal), "Internal error (500)" (generic Extension), "Startup with invalid config" (boot
precondition → Extension
0a, not a use case). Rule of thumb: #use cases ≈ #endpoints/user-goals,
NOT #outcomes. The deterministic gate validate-frd.mjs flags such pseudo-UCs.
- Level = user-goal. Write at sea level. Push implementation into no step; steps are
actor↔system intentions, not code.
- Glossary terms only. Every noun uses the canonical
CONTEXT.md term (no synonyms).
- Extensions are exhaustive over the contract. Every error the contract can return appears
as an Extension; no Extension lacks a defined outcome.
Traceability (the reason this artifact exists)
For the slice, these counts MUST match:
#Extensions == #rows in the failure-mode map == #error codes in the contract
- Each Extension that is visible to the consumer = one failure-mode-map row = one error code
(this is the same 1:1 rule as
requirements-intake Step 4 and program-design Step 8.6).
- The wording of each Extension is reused verbatim as the name of the matching component-test
scenario (stage 5) — so use case ↔ test ↔ error code read the same. (Component-test count is
governed by adapter branches, not by Extension count — see
component-tests.)
STOP
- Slice's brief use case absent from the FRD → STOP, run
requirements-intake for it first.
- Use case would need 2+ triggers → STOP, re-slice in
vertical-slices.
- An Extension has no outcome, or the contract has an error with no Extension → STOP, reconcile;
do not invent — surface as an open question to the operator.
Definition of Done
docs/design/<slice>/use-case.md exists, one fully-dressed UC, all template fields filled.- One trigger; user-goal level; glossary terms only.
#consumer-visible Extensions == #failure-mode rows == #error codes for the slice.
Foundations
Cockburn, Writing Effective Use Cases — fully-dressed format, goal levels, Main Success
Scenario + Extensions, stakeholders & interests, pre/postconditions. Example layout: the system
use case placed next to C4 in pinout-openapi (see docs/templates/README.md).
