@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/standards/use-case-format.md

@@ -0,0 +1,292 @@
+---
+tier: lite
+description: - Alistair Cockburn — Writing Effective Use Cases (2000).
+---
+
+## Sources read
+
+- Alistair Cockburn — *Writing Effective Use Cases* (2000). Bassclef source for fully-dressed format, goal levels, extension enumeration, preconditions + guarantees, stakeholders + interests.
+- Alistair Cockburn — *Unifying user stories, use cases, and story maps* (2024). Artifact non-overlap (use-case ≠ user-story ≠ task-scenario ≠ story-map); this standard respects the boundaries.
+- `.claude/skills/use-case/SKILL.md` — the skill that produces this artifact; this standard codifies the format the skill emits.
+- `standards/user-story-invest.md` — sibling standard; user-stories slice use-case lines with traceability back. INVEST validation there is orthogonal to Cockburn validation here.
+- `standards/persona-schema.md` — primary-actor field MUST reference a persona slug per this schema.
+
+## What I'm NOT reading (with reason)
+
+- RUP, Jacobson "Use Case 2.0," and other use-case notation variants — Cockburn is the bassclef shape in sunj-labs per this standard. Alternatives may be adopted later with an explicit ADR.
+
+# Use-Case Format Standard
+
+Bassclef format for use cases in sunj-labs repos. The contract the
+`/use-case` skill writes and every downstream consumer
+(`/user-stories`, `/interaction-design`, `/decompose`, `/verify`,
+`/spec`) composes against.
+
+Template: `templates/use-case-template.md`.
+Skill: `.claude/skills/use-case/SKILL.md`.
+
+## Why this standard exists
+
+Before /use-case, the user-centric chain had:
+
+- `/jtbd-tasks` — WHY (job the product is hired for)
+- `/task-scenarios` — CONTEXT (narrative day-in-the-life)
+- `/user-stories` — WHAT (backlog tokens, INVEST-shaped)
+- `/decompose` — HOW (responsibilities + patterns)
+
+Missing: **goal-level behavior spec**. `/user-stories` slices
+goals into INVEST-sized increments, but stories don't enumerate
+alternate flows systematically. `/interaction-design` renders
+flows as diagrams, but diagrams permit free-form omission —
+nothing forces the designer to list every extension.
+
+Use cases close the gap. Cockburn's format *requires* extension
+enumeration (1a, 1b, 2a, 2b...), *requires* preconditions and
+postconditions, *requires* stakeholders-and-interests. The
+skill can't emit a valid use case without those fields, so
+cross-cutting concerns (audit, compliance, rate limits) can't
+be silently dropped on the way to `/decompose`.
+
+## File convention
+
+### Preferred path
+
+`docs/use-cases/UC-NNN-{slug}.md` — one file per use case.
+
+`NNN` is a zero-padded 3-digit number assigned in creation order.
+`{slug}` is URL-safe: lowercase, hyphens, no spaces. Slug MUST
+match a form of the goal (e.g., `sign-in-with-email` not
+`login` — avoids ambiguity when multiple auth flows coexist).
+
+### Matrix
+
+`docs/use-cases/_matrix.md` — traceability table with one row
+per use case. See `/use-case` skill Step 7 for columns.
+
+## Required fields
+
+Every use case MUST include these fields. The skill validates
+presence and emits WARN/BLOCK per the validation matrix below.
+
+### Header
+
+```markdown
+# UC-NNN — [imperative goal title]
+```
+
+The title is the goal statement, imperative mood, no period.
+Examples: `UC-001 — Sign in with email and password`,
+`UC-014 — Submit an expense for approval`.
+
+### Metadata block
+
+```markdown
+- **Primary actor**: [persona-slug]
+- **Goal level**: ☁️ summary | 🎯 user-goal | 🐟 subfunction
+- **Scope**: [system-under-design]
+- **Status**: draft | accepted | deprecated
+- **Last validated**: YYYY-MM-DD
+```
+
+**Primary actor** MUST be a persona slug from `docs/personas/` or
+equivalent. "User," "actor," or role words like "admin" without a
+persona file are WARN.
+
+**Goal level** exactly one of the three icons. Default ☁️/🎯/🐟
+per `/use-case` Step 2. Summary only for multi-session goals;
+subfunction only for reused-by-2+ use cases.
+
+**Scope** names the system boundary: `POA web UI + auth service`,
+`bassclef-sync hook`, `POA backend`. Fuzzy scope ("the app") is
+WARN — split into distinct use cases.
+
+### Stakeholders + interests
+
+```markdown
+## Stakeholders + interests
+
+| Stakeholder | Interest |
+|-------------|----------|
+| [stakeholder] | [what they want to be true about this goal's execution] |
+```
+
+At least **2 non-actor** stakeholders required. Non-actor means:
+not the primary actor. Examples: Compliance, Ops, Support, Billing,
+Legal, Security, Partners, Regulators, Operator/Admin.
+
+This block is load-bearing — it's what feeds `/decompose`'s -ility
+audit. A use case with only the primary actor listed will pass
+validation with a WARN but will produce a decomposition missing
+cross-cutting concerns. The skill will flag the WARN explicitly.
+
+### Preconditions + guarantees + trigger
+
+```markdown
+## Preconditions
+- [state invariant 1]
+- [state invariant 2]
+
+## Minimal guarantees
+- [what's true after, regardless of success/failure]
+
+## Success guarantees
+- [what's true after a successful run]
+
+## Trigger
+- [event that starts the use case]
+```
+
+**Preconditions** are checkable state invariants the use case
+assumes on entry. "The system is running" is throat-clearing, not
+a precondition — reject as WARN. Valid preconditions: "account
+exists," "user is authenticated," "quota below limit."
+
+**Minimal guarantees** hold on ANY exit (success or extension):
+typically audit logging, state consistency, no secret leakage.
+This is where the "audit-trail written even on failure" invariant
+gets recorded.
+
+**Success guarantees** hold on successful completion only.
+
+**Trigger** is the specific event (actor action, scheduled event,
+external signal) that starts the flow.
+
+### Main success scenario
+
+```markdown
+## Main success scenario
+
+1. [Actor action OR system response]
+2. [Next step, actor↔system alternating]
+3. [...]
+```
+
+Numbered list, 3-9 steps. Each step is either actor action or
+system response; alternate between them. Steps >9 = split into
+subfunction use case.
+
+Implementation language prohibited: "System calls Postgres" ❌.
+Say "System retrieves account" — let `/decompose` pick storage.
+
+### Extensions
+
+```markdown
+## Extensions
+
+- **Na. [condition]**:
+  - Na1. [step 1 of recovery]
+  - Na2. [step 2 of recovery]
+  - Na3. Use case ends with [outcome].
+```
+
+`N` = the main-scenario step number where the branch originates.
+`a`, `b`, `c` = multiple extensions at the same step. Sub-steps
+within an extension are `Na1`, `Na2`, `Na3`...
+
+Nested extensions (`Na1a`) are allowed but nesting >2 levels
+signals a subfunction extraction is needed.
+
+**Every step in the main scenario MUST have at least one
+extension considered.** If a step has no realistic branch, state
+that explicitly: `*No extensions — [reason]*`. Silence is a
+failure signal, not confirmation of happy path.
+
+Extension enumeration prompts (Cockburn, per skill Step 4):
+
+1. What if actor input is invalid?
+2. What if system can't complete step (timeout, dependency, resource)?
+3. What if a precondition silently broke?
+4. What if actor abandons partway?
+5. What if concurrent actor changed state?
+
+### Technology/data variations (optional)
+
+```markdown
+## Technology / data variations
+
+- *Step 3*: password may also be verified via WebAuthn credential
+- *Step 4*: session cookie may be HttpOnly OR stored in SessionStorage per platform
+```
+
+Use when the same logical step has multiple implementation paths
+with different -ility characteristics. Feeds `/decompose` with
+variation points needing Strategy pattern.
+
+### Related information
+
+```markdown
+## Related information
+
+- Non-functional requirements: [rate limits, latency SLOs, etc.]
+- References: [specs, ADRs, canvases, external docs]
+- Sliced by stories: US-NNN, US-NNN, ...
+```
+
+Rate-limit, latency, and other cross-cutting NFRs live here when
+they don't map cleanly to a stakeholder+interests row.
+
+## Validation matrix
+
+| # | Check | Fail signal | Severity |
+|---|-------|-------------|----------|
+| 1 | Goal level stated | Missing ☁️/🎯/🐟 | BLOCK |
+| 2 | Primary actor is a persona slug | "user" / missing / role word without persona file | WARN |
+| 3 | ≥2 non-actor stakeholders | Only primary actor listed | WARN |
+| 4 | Preconditions are checkable state invariants | Throat-clearing ("system is running") | WARN |
+| 5 | Main scenario steps numbered | Bullets or prose | BLOCK |
+| 6 | Main scenario 3-9 steps | ≥10 steps | WARN (candidate for subfunction split) |
+| 7 | Every step has ≥1 extension OR explicit "*No extensions — [reason]*" | Silence | BLOCK |
+| 8 | Extensions use Na Nb format | Free-form bullets | BLOCK |
+| 9 | Success guarantees trace back to trigger | Guarantee unrelated to trigger outcome | WARN |
+| 10 | Scope names a specific system boundary | "The app" / missing | WARN |
+| 11 | No implementation language in steps | "System calls Postgres" / framework names | WARN |
+| 12 | Trigger is a specific event | Abstract ("when needed") | WARN |
+
+BLOCK = skill refuses to emit; operator must fix.
+WARN = skill emits with warnings recorded in `_matrix.md`.
+
+## Relationship to adjacent standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `persona-schema.md` | Primary actor MUST reference a persona slug per this schema |
+| `user-story-invest.md` | User stories slice use-case lines; stories cite UC-N step Xa in traceability |
+| `vpc-fit-validation.md` | VPC Pain-Relievers + Gain-Creators inform the stakeholders+interests "why this matters" framing |
+| `project-directory-layout.md` | `docs/use-cases/` is the bassclef path in app repos |
+
+## Relationship to adjacent skills
+
+| Skill | Role in use-case lifecycle |
+|-------|----------------------------|
+| `/use-case` | Produces use-case files per this standard |
+| `/user-stories` | Slices use-case lines into backlog tokens |
+| `/interaction-design` | Renders main scenario + extensions as diagrams |
+| `/decompose` | Reads use-case as alternative input to sequence diagrams; stakeholders+interests drive -ility audit |
+| `/verify` | Maps use-case lines to test assertions (1:1) |
+| `/spec` | Consumes use cases + stories as input |
+| `/shape` | `medium` + `full` tiers invoke /use-case as part of the chain |
+
+## Evolution
+
+- **v1.0 (2026-04-21)** — initial bassclef standard, Cockburn
+  fully-dressed format with goal levels, stakeholders+interests
+  discipline, and extension enumeration rules. Validation matrix
+  encodes BLOCK/WARN severities for skill-time gate.
+
+## Open questions for future iteration
+
+- **Concurrent-actor extensions**: Cockburn's rule 5 ("what if a
+  concurrent actor changed state?") is underspecified here. May
+  warrant a companion standard on optimistic-concurrency patterns
+  tied to use-case extensions.
+- **Use-case reuse (subfunction callouts)**: current format inlines
+  subfunction use cases; larger systems may need explicit "include"
+  references (UC-001 includes UC-042). Defer until observed pain.
+- **Use-case deprecation lifecycle**: `status: deprecated` is
+  noted but lifecycle (when to delete vs. archive) isn't codified.
+  Defer until first use-case is retired.
+
+## Closes
+
+- bassclef #213 (companion to `/use-case` skill)
+- Part of spec-lineage family epic #155

package/substrate/standards/user-story-invest.md

@@ -0,0 +1,268 @@
+---
+tier: lite
+description: Validation rules for user stories produced by /user-stories.
+---
+
+# User Story INVEST Standard
+
+Validation rules for user stories produced by `/user-stories`. INVEST
+(Bill Wake, 2003) is the bassclef heuristic for backlog-ready story
+quality. This standard codifies the rules + pass/warn/fail semantics.
+
+Skill: `.claude/skills/user-stories/SKILL.md`.
+Template: `templates/user-story-template.md`.
+
+## Why this standard exists
+
+User stories are conversation tokens, not specifications. Without
+quality gates, "story" devolves into "any sentence formatted with
+'As a / I want / So that.'" The result: bloated stories that take
+weeks, vague stories that can't be estimated, dependent stories that
+block release planning, technical-debt stories disguised as user
+value.
+
+INVEST is six load-bearing tests every story passes before it enters
+the backlog. Stories that fail multiple letters require rewrite.
+Stories that fail one letter get WARN with a path to resolution.
+
+## The six tests
+
+### I — Independent
+
+**Test**: Can this story ship to production without any other story
+shipping first?
+
+**Why**: dependent stories couple release planning. If A depends on
+B which depends on C, you can't ship A early or skip C. Independent
+stories let the team reorder, kill, or ship in any sequence.
+
+**Acceptable dependencies**:
+- Infrastructure that's already in place (no story dependency, just
+  platform reality)
+- Optional enhancement: "this story is BETTER if X is also shipped,
+  but ships valuable on its own"
+
+**Not acceptable**:
+- "Need US-002 before US-001 makes sense" — merge or resequence
+- Implicit dependencies hidden in acceptance criteria — surface them
+
+**Resolution if fail**:
+- Merge dependent stories into one
+- Resequence so the prerequisite ships as its own story first
+- Re-scope so this story doesn't NEED the prerequisite (deliver lesser
+  but standalone value)
+
+### N — Negotiable
+
+**Test**: Is this story a starting-point for conversation, or a
+contract that mandates exact wording?
+
+**Why**: stories are tokens for conversation between PO + dev + UX,
+not specs. A story that locks in "must be a left-side panel" loses
+the design negotiation that should happen at sprint planning. Stories
+say WHAT outcome the persona gets; teams negotiate HOW during
+implementation.
+
+**Acceptable**:
+- Constraints when they're load-bearing: "must be accessible per WCAG
+  AA" (this isn't negotiable for legal/ethical reasons, mark it
+  explicit)
+- Acceptance criteria that pin down outcomes (those ARE the contract)
+
+**Not acceptable**:
+- Implementation prescription in the story body (move to acceptance
+  criteria or out of story entirely)
+- "Must use [framework/library]" — that's an architecture decision,
+  not a story
+
+**Resolution if fail**:
+- Move prescriptive content to acceptance criteria
+- Move architecture/library mandates to ADRs
+- Rewrite story body in user-outcome terms
+
+### V — Valuable
+
+**Test**: Does the named persona get observable, demonstrable value
+when this story ships?
+
+**Why**: stories that exist for internal reasons (refactor, tech-debt,
+infrastructure) aren't user stories — they're technical tasks. They
+belong in a separate backlog or as enabler stories with explicit
+"this enables future user value" framing. Confusing tech-tasks with
+user-stories pollutes the backlog and obscures actual user work.
+
+**Acceptable**:
+- Direct value: persona uses the new behavior
+- Indirect value: persona experiences a quality improvement
+  (faster, more reliable, more secure)
+- Enabler value: explicit framing — "enables US-NNN which delivers
+  user value"
+
+**Not acceptable**:
+- "Refactor X" with no user-facing change
+- "Pay down tech debt in module Y" — this is a tech task
+- "Add observability" — unless persona is operator/SRE, this is
+  internal
+
+**Resolution if fail**:
+- Reclassify as tech-debt task; move to engineering backlog
+- Reframe as enabler story tied to a user-facing story
+- If genuinely user-valuable but value is hard to articulate, the
+  value isn't there — kill the story
+
+### E — Estimable
+
+**Test**: Can the team estimate this story (in story points,
+t-shirt size, or hours) within ~30 minutes of refinement?
+
+**Why**: unestimable stories indicate hidden complexity, missing
+context, or unfamiliar territory. Either the story needs more
+discovery (research spike), or it needs to be split until the parts
+are estimable.
+
+**Common reasons stories aren't estimable**:
+- Unknown technical territory (need spike)
+- Unclear acceptance criteria (need refinement)
+- Unknown user behavior (need research)
+- Too big to fit estimation in one head (split)
+
+**Resolution if fail**:
+- Schedule a research spike for unknowns (timeboxed, separate story)
+- Refine acceptance criteria
+- Split the story until parts are estimable
+
+### S — Small
+
+**Test**: Does this story fit in one iteration / sprint?
+
+**Why**: stories that span multiple sprints become epics. Epics are
+fine as containers but they're not stories. A story that takes 3
+weeks misses every benefit of incremental delivery — no early
+feedback, no early value, no early risk discovery.
+
+**Heuristic**: a story should be doable in 1-5 days by one or two
+developers with normal context. If 6+ days, split it.
+
+**Splitting strategies** (Patton, Cohn):
+- By workflow step (extract a single step into its own story)
+- By data type (one story per data variant)
+- By acceptance criterion (one criterion per story)
+- By user role (different personas as different stories)
+- By happy path vs. edge cases (ship happy path first, edges later)
+- By UI vs. backend (when independently shippable; risky if not)
+
+**Resolution if fail**: split. The most common letter to fail.
+
+### T — Testable
+
+**Test**: Are the acceptance criteria concrete enough to write
+automated tests against?
+
+**Why**: untestable stories ship as "looks done" — and "looks done"
+ships bugs. Acceptance criteria that read "works well" or "is
+intuitive" aren't testable. Criteria that read "loads in <2s on 4G"
+or "all form fields validate before submit" are.
+
+**Testable criteria**:
+- Pin specific observable behaviors
+- Include thresholds for non-functional concerns (performance, a11y)
+- Cover happy path + at least one edge case
+- Map to test types (unit / integration / e2e)
+
+**Not testable**:
+- "Looks good" / "feels fast" / "is intuitive"
+- "Standard behavior" without defining what standard means
+- Implementation assertions ("uses Redis cache") rather than behavior
+
+**Resolution if fail**: rewrite criteria. Each criterion = one test
+assertion. If you can't write the test, the criterion isn't done.
+
+## Pass / Warn / Fail semantics
+
+Per-story status is computed from the six tests:
+
+| INVEST score | Status | Meaning |
+|--------------|--------|---------|
+| 6 PASS | **PASS** | Backlog-ready |
+| 5 PASS / 1 WARN | **PASS-WARN** | Backlog-ready; resolve warning at refinement |
+| 4 PASS / 2 WARN | **WARN** | Refine before sprint planning |
+| ≤3 PASS or any FAIL | **FAIL** | Rewrite required |
+
+Aggregate iteration health:
+
+```markdown
+**INVEST aggregate**: N PASS / M PASS-WARN / K WARN / J FAIL
+**Backlog-ready ratio**: (PASS + PASS-WARN) / total
+```
+
+Target ratio: ≥85%. Below 70% = backlog-quality systemic issue
+(refinement discipline missing, scope confusion, persona inflation).
+
+## Validation procedure (`/user-stories validate`)
+
+`/user-stories validate` walks every story under `docs/user-stories/`
+(or `docs/user-stories/[iteration]/`) and reports per-story status.
+
+```markdown
+## Story validation — [iteration]
+
+| Story | I | N | V | E | S | T | Status | Notes |
+|-------|---|---|---|---|---|---|--------|-------|
+| US-001 | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | PASS-WARN | S: 5-day estimate at upper bound; consider split |
+| US-002 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | FAIL | I: depends on US-005 not yet in backlog |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+**Aggregate**: 8 PASS / 3 PASS-WARN / 2 WARN / 1 FAIL
+**Backlog-ready ratio**: 11/14 = 79%  (below 85% target — refine)
+```
+
+## Traceability rules
+
+Every story carries a traceability block linking to upstream artifacts:
+
+| Field | Required? | When absent |
+|-------|-----------|-------------|
+| Persona | MUST | FAIL — every story names a persona slug |
+| JTBD | MUST | FAIL — story without JTBD is solution-looking-for-problem |
+| VPC entry | SHOULD | WARN — benefit clause is weaker without VPC grounding |
+| Use-case line | SHOULD when /use-case exists | WARN — coverage gap on use-case |
+
+A story with no JTBD trace is a **red flag**: it's likely a feature
+request from operator intuition rather than user need. Either find
+the JTBD (which means /jtbd-tasks needs another pass) or kill the
+story.
+
+## What this standard does NOT cover
+
+- **Story estimation methodology** (story points vs. t-shirt vs. hours)
+  — team choice, not standard concern
+- **Sprint composition rules** — separate concern (`/sprint` skill)
+- **Acceptance test format** — Given/When/Then BDD or assertion-style
+  both fine; team picks
+- **Task breakdown within a story** — implementation detail, not
+  story-level
+
+## Relationship to other standards + rules
+
+| Related | Connection |
+|---------|-----------|
+| `standards/persona-schema.md` | Personas referenced in `<As a>` clause must validate against schema |
+| `.claude/rules/artifact-ingestion.md` | Stories trace to upstream artifacts; same "cite before claim" discipline |
+| `standards/vpc-fit-validation.md` | VPC Pain-Relievers + Gain-Creators ground story `<benefit>` clause |
+| `.claude/skills/user-stories/SKILL.md` | The skill that produces stories validated by this standard |
+| `.claude/skills/spec/SKILL.md` | Downstream — spec consumes stories as input scope |
+
+## When to revisit
+
+- Backlog-ready ratio drops below 70% repeatedly (refinement issue OR
+  the standard is too strict)
+- A team consistently fails one letter (might indicate a process gap
+  worth surfacing, e.g., "always failing E means we don't have
+  estimation rigor")
+- New bassclef artifact upstream of stories (e.g., when /use-case
+  lands, traceability rule adds use-case-line as MUST when present)
+
+## Closes
+
+- bassclef #208 (paired with skill)
+- Part of follow-up to iteration `2026-04-19e-persona-vpc-promotions`