@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/skills/use-case/SKILL.md

@@ -0,0 +1,417 @@
+---
+tier: lite
+name: use-case
+description: "Produce Cockburn-style use cases \u2014 main success scenario, numbered extensions, preconditions, postconditions, and stakeholders. Closes the gap between /user-stories and /spec. Distinct from /task-scenarios (UX narrative)."
+problem: "Requirements go straight to code without a main success scenario. Extension paths get invented per PR."
+value: "Cockburn-style use cases with numbered extensions and pre/postcondition contracts."
+inputs: [A feature or persona-scoped scope]
+outputs: [Fully-dressed use case, Main success scenario plus extensions, Pre/postconditions]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /use-case — Cockburn Behavior Spec
+
+Produce goal-level behavior specs in the fully-dressed format per @luminary alistair-cockburn (*Writing Effective Use Cases*, 2000). Forces systematic extension enumeration (1a, 1b, 2a), surfaces preconditions + postconditions as first-class fields, captures stakeholders + interests so non-actor concerns (compliance, audit, -ilities) reach `/decompose`.
+
+## When to invoke
+
+- After `/personas`, `/jtbd-tasks`, and ideally `/value-prop-canvas`
+  have produced upstream artifacts
+- Before `/user-stories` — write the goal-level spec first, then
+  slice into INVEST stories with traceability back to use-case lines
+- Before `/interaction-design` + `/decompose` — use-case lines map
+  directly to state diagrams and responsibilities
+- Whenever a feature spans multiple actor steps with alternate flows
+  (anything with "if X, otherwise Y" logic is a candidate)
+
+**Do NOT invoke for**:
+- Single-step CRUD (no extensions, no goals beyond the step — story is enough)
+- UX research (that's `/task-scenarios`)
+- Positioning (that's `/value-prop` or `/value-prop-canvas`)
+- System architecture (that's ADRs + `/architect-review`)
+
+## Distinction from adjacent artifacts
+
+Cockburn (2024) and NN/G both emphasize that these four are
+**distinct artifacts** — not competing framings. `/use-case`
+occupies the SPEC seat:
+
+| Artifact | Purpose | Format | Primary consumer |
+|----------|---------|--------|------------------|
+| **JTBDs** | WHY (job being hired) | Outcome statement | PM, strategist |
+| **Task scenarios** (NN/G) | CONTEXT (day-in-the-life narrative) | Story prose | UX researcher, `/synthetic-user` |
+| **User stories** (Cohn/Wake) | WHAT (backlog tokens for incremental delivery) | As-a-I-want-So-that + INVEST | Developer, sprint planner |
+| **Use cases** (Cockburn) | SPEC (system behavior for complete goal) | Structured: goal + main scenario + extensions + pre/post + stakeholders | Architect, `/decompose`, `/verify` |
+
+A use case answers: *"What must the system do for this actor to
+achieve this goal, including every branch, failure, and exit?"*
+Not "how" (implementation) and not "why" (value prop) — **what
+behavior the system exhibits, exhaustively**.
+
+## Sources read
+
+- @luminary alistair-cockburn — *Writing Effective Use Cases* (2000). Origin of the fully-dressed format, extension enumeration rules, goal levels (user-goal / subfunction / summary), precondition + guarantees discipline, stakeholders+interests practice. Every rule in this skill's procedure traces back to this text.
+- @luminary alistair-cockburn — *Unifying user stories, use cases, and story maps* (2024). Establishes the use-case↔user-story↔story-map distinction; this skill respects the boundaries.
+- `.claude/skills/personas/SKILL.md`, `.claude/skills/jtbd-tasks/SKILL.md`,
+  `.claude/skills/value-prop-canvas/SKILL.md` — upstream artifacts
+- `.claude/skills/user-stories/SKILL.md` — downstream consumer;
+  stories slice use-case lines with traceability (UC-N step Xa)
+- `.claude/skills/interaction-design/SKILL.md` — renders use-case
+  main scenario + extensions as state + sequence diagrams
+- `.claude/skills/decompose/SKILL.md` — consumes use-case as
+  alternative input to sequence diagrams; stakeholders+interests
+  drive the -ility audit
+- `.claude/skills/verify/SKILL.md` — use-case lines → test
+  assertions (every step + every extension = at least one assertion)
+- `standards/use-case-format.md` — companion standard (this skill's
+  standard; codifies Cockburn schema + extension rules +
+  stakeholders+interests discipline)
+- `templates/use-case-template.md` — fully-dressed template
+
+## What I'm NOT reading (with reason)
+
+- Full Cockburn 2000 book — the rules needed are well-established
+  (main scenario / extensions / pre/post / stakeholders) and
+  captured in the companion standard. Cited, not reconstructed.
+- Other use-case notation styles (RUP, "Use Case 2.0" Jacobson
+  variants) — Cockburn is the bassclef shape for this skill.
+  Alternative styles can be adopted later with explicit ADR.
+- `.claude/skills/spec/SKILL.md` full body — /spec consumes
+  use-cases downstream; this skill's output shape is defined by
+  the Cockburn format, not by /spec's input expectations.
+
+## Usage
+
+```
+/use-case                              → produce use case(s) from current iteration goal scope
+/use-case [ticket-ref]                 → produce from a specific ticket / spec / canvas
+/use-case from-jtbd [JTBD slug]        → derive use case for one JTBD (primary goal)
+/use-case from-user-story [US-NNN]     → reverse-engineer: a story that's grown complex enough to need a use-case backing
+/use-case validate [path]              → audit existing use case against Cockburn schema + extension enumeration
+```
+
+## Procedure
+
+### Step 1: Resolve inputs
+
+Read upstream artifacts in this order. Halt with a useful warning
+if a required input is missing:
+
+1. **Personas** — `docs/personas/*.md` (preferred) or
+   `docs/design/personas/*.md` (legacy). Use-case's **primary
+   actor** MUST be a persona slug, not "user."
+2. **JTBDs** — `docs/design/personas/[persona]/jtbds.md` or
+   equivalent. Each use case has a single **goal** that traces to
+   a JTBD outcome. Halt if no JTBDs for the scope in question
+   (warn the operator; offer to run `/jtbd-tasks` first).
+3. **Value Prop Canvas** (optional) — `docs/value-prop-canvas/*.md`.
+   When present, Pain-Relievers + Gain-Creators ground the "why
+   this goal matters" framing in the stakeholders+interests block.
+4. **Iteration bet or canvas scope** — if invoked without a ticket,
+   read the active iteration goal's scope statement.
+
+### Step 2: Choose goal level
+
+Per Cockburn, every use case has a **goal level**. Picking the
+right one prevents the "use case that tries to do everything"
+failure mode.
+
+| Level | Symbol | Description | Example |
+|-------|--------|-------------|---------|
+| **Summary** | ☁️ (cloud) | Multi-session, multi-actor, strategic outcome | "Onboard a new tenant" |
+| **User goal** | 🎯 (sea level) | Single actor, single session, observable completion | "Submit an expense report" |
+| **Subfunction** | 🐟 (underwater) | Component of a user-goal; not worth standalone use-case unless reused | "Validate expense receipt" |
+
+**Default to user-goal** (🎯). Summary-level only when the work
+genuinely spans sessions. Subfunction only when the same behavior
+is reused by 2+ user-goal use cases.
+
+### Step 3: Draft the fully-dressed use case
+
+Use the template at `templates/use-case-template.md`.
+Required fields:
+
+- **Use case ID + title** — `UC-NNN — [imperative goal]`
+- **Primary actor** — persona slug
+- **Goal level** — ☁️ / 🎯 / 🐟
+- **Scope** — system under design (e.g., "POA backend + web UI")
+- **Stakeholders + interests** — table: who cares, what they want
+- **Preconditions** — what's true before the use case fires
+- **Minimal guarantees** — what's true after, regardless of outcome
+- **Success guarantees** — what's true after success
+- **Trigger** — event that starts the use case
+- **Main success scenario** — numbered steps, actor↔system alternating
+- **Extensions** — Na Nb format, mapped to step N
+- **Technology/data variations** (optional) — alternate mechanisms at a step
+- **Related information** — non-functional requirements, references
+
+Every step numbered. Every extension numbered per Cockburn's Na Nb
+convention (1a = first extension at step 1, 1b = second extension
+at step 1, 2a = first extension at step 2, etc.).
+
+### Step 4: Extension enumeration discipline
+
+This is the step most often skipped. Cockburn's rule: **enumerate
+every way the main scenario can branch, fail, or exit early**.
+
+For each step N in the main scenario, ask:
+
+1. What if the actor's input is invalid?
+2. What if the system can't complete the step (timeout, dependency, resource limit)?
+3. What if a precondition silently broke?
+4. What if the actor abandons partway?
+5. What if a concurrent actor changed state?
+
+Each yes → an extension line. Name the extension with the
+triggering condition + the recovery path:
+
+```
+3a. Email already registered:
+    3a1. System displays error + offers password reset
+    3a2. Use case ends with actor unauthenticated
+```
+
+Extension paths can themselves have sub-extensions (3a1a, 3a1b).
+Keep nesting to 2 levels max; deeper usually means the extension
+should be its own subfunction use case.
+
+### Step 5: Stakeholders + interests — drive the -ility audit
+
+The stakeholders+interests block is what makes a use case feed
+`/decompose`'s -ility audit correctly. For each **non-actor** party
+with a stake in this goal, record:
+
+| Stakeholder | Interest |
+|-------------|----------|
+| Compliance | Audit trail of every auth attempt |
+| Ops | No secret leakage into logs |
+| Support | Failed-auth reason visible in support tool |
+| Billing | Auth event triggers usage counter |
+
+Every row becomes a non-functional requirement `/decompose` must
+account for. Without this block, cross-cutting concerns (audit,
+observability, compliance, rate-limiting) get bolted onto
+implementations later — the exact Langfuse-inside-HaikuImputer
+class of failure the `/decompose` skill exists to prevent.
+
+### Step 6: Validation
+
+Walk the drafted use case through the Cockburn validation
+checklist from `standards/use-case-format.md`:
+
+| Check | Fail signal |
+|-------|-------------|
+| Goal level stated | No ☁️/🎯/🐟 |
+| Primary actor is a persona slug | "user" or missing |
+| Stakeholders include at least 2 non-actor parties | Only primary actor listed |
+| Every main step numbered | Bullet list or prose |
+| Every step has at least one extension considered | Happy path only |
+| Preconditions are checkable | Vague ("everything's OK") |
+| Success guarantees match trigger outcome | Guarantee doesn't trace back to trigger |
+| Main scenario completes within 3-9 steps | >9 = split into subfunction(s) |
+| Extensions use Na Nb format | Free-form bullets |
+
+Fails become WARN or BLOCK per the standard.
+
+### Step 7: Emit + traceability
+
+Write each use case to `docs/use-cases/UC-NNN-[slug].md`.
+
+Update `docs/use-cases/_matrix.md` with a traceability row:
+
+```markdown
+| Use case | Primary actor | Goal level | JTBD | Stories sliced from | Stakeholders (count) | Status |
+|----------|---------------|------------|------|---------------------|---------------------|--------|
+| UC-001 | couple-founders | 🎯 | J1 | US-001, US-002, US-005 | 4 | PASS |
+```
+
+The matrix surfaces:
+- **Orphan use cases** — no JTBD trace = solution without a problem
+- **JTBD gaps** — JTBDs with no use case = unserved goals
+- **Story coverage** — use cases with no downstream stories = spec that didn't reach the backlog
+- **Stakeholder thinness** — use cases with ≤1 non-actor stakeholder = likely missing cross-cutting concerns
+
+### Step 8: Output summary
+
+```markdown
+## Use cases produced
+
+**Iteration**: [iteration goal slug]
+**Use cases written**: N
+**Goal levels**: N summary / N user-goal / N subfunction
+**Extensions total**: N (avg N per use case)
+**Stakeholders/interests rows**: N total
+**Downstream stories traced**: N
+
+**Gaps**:
+- JTBDs without use cases: [list]
+- Use cases without downstream stories: [list]
+- Use cases with <2 non-actor stakeholders: [list — rewrite recommended]
+```
+
+## Worked example — the /decompose-feeding shape
+
+Here's a fully-dressed use case that demonstrates why the
+stakeholders+interests block matters.
+
+### UC-001 — Sign in with email + password
+
+- **Primary actor**: cofounder-pair (persona slug)
+- **Goal level**: 🎯 user-goal
+- **Scope**: POA web UI + auth service
+- **Stakeholders + interests**:
+
+| Stakeholder | Interest |
+|-------------|----------|
+| Compliance | Every attempt logged with IP + user-agent |
+| Ops | No password or partial hash leaks into logs |
+| Support | Failed-auth reason visible in support tool (but not to actor) |
+| Billing | Successful auth increments MAU counter |
+
+- **Preconditions**: cofounder-pair account exists; password is set
+- **Minimal guarantees**: audit log written with actor ID (or null for failed lookup) + timestamp + outcome
+- **Success guarantees**: valid session cookie issued; MAU incremented
+- **Trigger**: actor submits email + password form
+
+**Main success scenario**:
+
+1. Actor submits email + password.
+2. System looks up account by email.
+3. System verifies password against stored hash.
+4. System issues session cookie with 24h TTL.
+5. System redirects to post-auth landing page.
+
+**Extensions**:
+
+- **2a. Email not found**:
+  - 2a1. System displays generic "Invalid credentials" (no user enumeration).
+  - 2a2. Audit log entry written with null user-ID.
+  - 2a3. Use case ends with actor unauthenticated.
+- **3a. Password mismatch**:
+  - 3a1. System displays generic "Invalid credentials."
+  - 3a2. Audit log entry written with user-ID + "pw-mismatch" reason.
+  - 3a3. Use case ends with actor unauthenticated.
+- **3b. Account locked (per rate-limit policy)**:
+  - 3b1. System displays "Account temporarily locked — try again in N minutes."
+  - 3b2. Audit log entry written with "lockout" reason.
+  - 3b3. Use case ends with actor unauthenticated.
+- **4a. Session issue fails (transient)**:
+  - 4a1. System displays "Try again" error.
+  - 4a2. Audit log written with "session-issue-failure" + error code.
+  - 4a3. Use case ends with actor unauthenticated.
+
+### Why the stakeholders block matters
+
+Without rows for Compliance, Ops, and Support, the audit-trail
+requirement doesn't reach `/decompose`. `/decompose` then picks an
+implementation without an AuditLogger decorator; logs get bolted
+into the route handler; compliance files an incident three months
+later.
+
+With the block, `/decompose` reads: *"4 stakeholders, 3 non-actor
+concerns — route handler needs an audit-log decorator wrapping
+the password-verify interface, and logging must scrub secrets
+at the boundary."* The responsibility assignment shows up in the
+decomposition artifact before any code is written.
+
+Every extension is also a test assertion for `/verify`:
+
+- 2a1 → test: `sign_in_with_unknown_email_returns_generic_error`
+- 3a1 → test: `sign_in_with_wrong_password_returns_generic_error`
+- 3b1 → test: `sign_in_after_rate_limit_returns_lockout_message`
+- 4a1 → test: `sign_in_when_session_issue_fails_returns_retry_error`
+
+Use-case-line → test mapping is 1:1. Extensions that aren't
+tested are gaps; tests without use-case-line traceability are
+orphan coverage.
+
+## Common pitfalls
+
+- **Happy-path only** — the main scenario is just the "yes path";
+  real behavior is in the extensions. Skipping extensions = no
+  spec, just a hope.
+- **"User" as primary actor** — use the persona slug. If there's
+  no persona yet, run `/personas` first.
+- **Implementation leak** — "System calls Postgres to look up
+  account" is implementation. Use case says "System looks up
+  account"; decomposition decides the storage.
+- **Stakeholders block listed only actors** — the whole point of
+  the block is non-actor concerns (compliance, ops, audit,
+  billing, support). If it's only the primary actor, you've
+  missed the -ility audit input.
+- **Goal level drift** — "Onboard and sign in and explore the app"
+  is summary-level but written like user-goal. Pick the level
+  consciously; if it's summary, split into user-goal use cases.
+- **Extension prose that's really a story** — if an extension has
+  its own multi-step success path, it's probably a subfunction
+  use case, not an extension. Extract it.
+- **Preconditions as throat-clearing** — "The system is running"
+  is not a precondition. Preconditions are state invariants the
+  use case assumes (account exists, user is authenticated,
+  quota is below limit).
+
+## Relationship to other skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/personas` | Upstream — provides the primary actor slug |
+| `/jtbd-tasks` | Upstream — goal traces to JTBD outcome |
+| `/value-prop-canvas` | Upstream (optional) — informs "why this goal matters" framing in stakeholders block |
+| `/user-stories` | Downstream — stories slice use-case main scenario + extensions into INVEST tokens (US-N cites UC-N step Xa) |
+| `/interaction-design` | Downstream — renders use-case flow as state + sequence diagrams |
+| `/decompose` | Downstream — consumes use-case as alternative input alongside sequence diagrams; stakeholders+interests drive -ility audit |
+| `/verify` | Downstream — use-case-line → test-assertion mapping (every step + extension = at least one test) |
+| `/spec` | Downstream — spec consumes use cases + stories as input |
+| `/task-scenarios` | Sibling, NOT replacement — task-scenarios are narrative day-in-the-life for UX research; use cases are behavior specs. Both coexist. |
+| `/synthetic-user` | Indirect — use cases are too granular for journey testing; use `/task-scenarios` for that |
+| `/shape` | Workflow — /shape's `medium` and `full` tiers invoke /use-case as part of the chain |
+
+## Chain position
+
+```
+/personas (WHO)
+    ↓
+/jtbd-tasks (WHY)
+    ↓
+/value-prop-canvas (FIT)
+    ↓
+/use-case (SPEC)  ← THIS SKILL
+    ↓
+/user-stories (BACKLOG)  [slices use-case lines]
+    ↓
+/interaction-design (RENDERS) + /decompose (RESPONSIBILITIES)
+    ↓
+/spec (BUILD)
+```
+
+Parallel branch for UX research narrative:
+
+```
+/jtbd-tasks
+    ↓
+/task-scenarios (CONTEXT)
+    ↓
+/synthetic-user (PERSONA TESTING)
+```
+
+## Provenance & evolution
+
+- Drafted during user-centric chain shaping (2026-04-19e session)
+  after reading Cockburn 2024 — *Unifying user stories, use cases,
+  and story maps*. That paper established the 4-artifact
+  non-overlap that made adding /use-case to the chain defensible.
+- Promoted to bassclef via issue #213 (part of spec-lineage family
+  epic #155).
+- Cockburn-aligned: fully-dressed format with extension enumeration
+  discipline, goal levels, and stakeholders+interests as first-class.
+
+## Closes
+
+- bassclef #213
+- Part of spec-lineage family epic #155
+- WS-1 of iteration goal 2026-04-21b-shaping-chain-plus-slack
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.