@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/.claude/skills/use-case/SKILL.md

@@ -1,417 +0,0 @@
----
-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` | Composer — /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.