@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/templates/use-case-template.md

@@ -0,0 +1,194 @@
+---
+tier: lite
+---
+
+# UC-NNN — [imperative goal title]
+
+<!--
+Template for a Cockburn fully-dressed use case.
+See standards/use-case-format.md for the schema + validation rules.
+See .claude/skills/use-case/SKILL.md for the procedure.
+
+Replace NNN with a zero-padded 3-digit number.
+Title is imperative, no period (e.g., "Sign in with email and password").
+Delete all <!-- comment -- > blocks before committing.
+-->
+
+- **Primary actor**: [persona-slug]
+- **Goal level**: 🎯 user-goal
+  <!-- ☁️ summary (multi-session) | 🎯 user-goal (single session, default) | 🐟 subfunction (reused by ≥2 use cases) -->
+- **Scope**: [system-under-design]
+- **Status**: draft
+- **Last validated**: YYYY-MM-DD
+
+## Stakeholders + interests
+
+<!-- At least 2 NON-ACTOR stakeholders required (beyond primary actor).
+     Examples: Compliance, Ops, Support, Billing, Legal, Security, Partners.
+     Each row feeds /decompose's -ility audit — cross-cutting concerns
+     that would otherwise get bolted into implementations later. -->
+
+| Stakeholder | Interest |
+|-------------|----------|
+| [stakeholder] | [what they want to be true about this goal's execution] |
+| [stakeholder] | [...] |
+
+## Preconditions
+
+<!-- Checkable state invariants the use case assumes on entry.
+     "The system is running" is throat-clearing, not a precondition.
+     Valid: "account exists," "user authenticated," "quota below limit." -->
+
+- [state invariant 1]
+- [state invariant 2]
+
+## Minimal guarantees
+
+<!-- What's true after ANY exit (success or extension).
+     Typically: audit logging, state consistency, no secret leakage. -->
+
+- [invariant that holds on any exit]
+
+## Success guarantees
+
+<!-- What's true on successful completion only. -->
+
+- [invariant that holds on success]
+
+## Trigger
+
+<!-- The specific event (actor action, scheduled event, external signal) that starts the flow. -->
+
+- [triggering event]
+
+## Main success scenario
+
+<!-- Numbered list, 3-9 steps, alternating actor↔system.
+     No implementation language ("system calls Postgres" ❌ — say "system retrieves X").
+     >9 steps = split into subfunction use case(s). -->
+
+1. [Actor does X]
+2. [System responds with Y]
+3. [Actor does Z]
+4. [System does W]
+5. [...]
+
+## Extensions
+
+<!-- EVERY step in main scenario MUST have at least one extension considered,
+     OR an explicit line: "*No extensions — [reason]*". Silence is failure.
+
+     Format: Na (step number + letter). Sub-steps: Na1, Na2, Na3.
+
+     Enumeration prompts (Cockburn):
+     1. What if actor input is invalid?
+     2. What if system can't complete step (timeout, dependency, resource)?
+     3. What if precondition silently broke?
+     4. What if actor abandons partway?
+     5. What if concurrent actor changed state?
+-->
+
+- **Na. [condition at step N]**:
+  - Na1. [recovery step 1]
+  - Na2. [recovery step 2]
+  - Na3. Use case ends with [outcome].
+
+- **Nb. [another condition at step N]**:
+  - Nb1. [...]
+  - Nb2. Use case ends with [outcome].
+
+- **Ma. [condition at step M]**:
+  - Ma1. [...]
+
+## Technology / data variations (optional)
+
+<!-- Use when the same logical step has multiple implementation paths
+     with different -ility characteristics. Feeds /decompose with variation
+     points needing Strategy pattern. Omit if not applicable. -->
+
+- *Step N*: [alternative mechanism] — [when used]
+
+## Related information
+
+- **Non-functional requirements**: [rate limits, latency SLOs, accessibility, etc.]
+- **References**: [specs, ADRs, canvases, external docs]
+- **Sliced by stories**: [US-NNN, US-NNN, ...]
+- **JTBD traceability**: [J-N — job-statement]
+- **VPC traceability** (if applicable): [PR-N or GC-N — item]
+
+---
+
+## Worked example — sign in with email and password
+
+<!-- Keep this worked example in the template for reference;
+     /use-case skill strips it when emitting a new file. -->
+
+# UC-001 — Sign in with email and password
+
+- **Primary actor**: cofounder-pair
+- **Goal level**: 🎯 user-goal
+- **Scope**: POA web UI + auth service
+- **Status**: accepted
+- **Last validated**: 2026-04-21
+
+## 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 (not actor) |
+| Billing | Successful auth increments MAU counter |
+
+## Preconditions
+
+- cofounder-pair account exists in the user table
+- Password has been set (not null)
+
+## Minimal guarantees
+
+- Audit log entry written with timestamp + outcome + user-ID (or null for failed lookup)
+- No password or hash value written to logs
+
+## Success guarantees
+
+- Valid session cookie issued with 24h TTL
+- MAU counter incremented for the actor's tenant
+
+## 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 (rate-limit exceeded)**:
+  - 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.
+
+## Related information
+
+- **Non-functional requirements**: p95 auth latency <500ms; rate-limit 5 attempts per email per 15min
+- **References**: ADR-003 session management, standards/security.md
+- **Sliced by stories**: US-001 (happy path), US-002 (rate limit UX), US-003 (audit log)
+- **JTBD traceability**: J1 — "Sign in quickly without re-typing credentials on every session"

package/substrate/templates/user-story-template.md

@@ -0,0 +1,107 @@
+---
+tier: lite
+---
+
+# US-NNN — [Imperative title — what the persona accomplishes]
+
+<!--
+  Bassclef user story template. INVEST-shaped per
+  standards/user-story-invest.md. Produced by /user-stories skill.
+
+  Save location:
+    Per-story: docs/user-stories/US-NNN-[slug].md (preferred —
+               granular Git history, easier review)
+    Batch:     docs/user-stories/[iteration-slug].md (acceptable
+               for small iterations or bulk import)
+
+  Filename basename MUST match the US-NNN ID.
+
+  Delete this comment block after copy-paste.
+-->
+
+**ID**: US-NNN
+**Iteration**: [iteration-bet path or slug]
+**Status**: new | refined | in-progress | done | killed
+**INVEST**: PASS | PASS-WARN | WARN | FAIL (computed by /user-stories validate)
+**Estimate**: [story points / t-shirt / hours — team convention]
+
+---
+
+## Story
+
+**As a** [persona slug — e.g., `couple-founders`, NOT "user"]
+**I want to** [observable, testable outcome — what the persona does or experiences, NOT internal mechanism]
+**So that** [benefit grounded in VPC entry or JTBD outcome]
+
+---
+
+## Traceability
+
+<!--
+  REQUIRED: Persona + JTBD. SHOULD: VPC + use-case (when present).
+  Stories without JTBD trace are red flags per
+  standards/user-story-invest.md.
+-->
+
+- **Persona**: [slug] — `docs/personas/[slug].md`
+- **JTBD**: [J-N: job statement] — `docs/design/personas/[persona]/jtbds.md#J-N`
+- **VPC entry** (when present): [PR-N or GC-N] — `docs/value-prop-canvas/[persona].md`
+- **Use-case line** (when /use-case exists): [UC-N step Xa] — `docs/use-cases/[uc-slug].md`
+
+---
+
+## Acceptance criteria
+
+<!--
+  Each criterion = one test assertion. Concrete, observable,
+  threshold-bearing where applicable. NOT "works well" / "is intuitive".
+  Cover happy path + at least one edge / non-functional concern.
+-->
+
+- [ ] [Observable behavior — written as a test assertion]
+- [ ] [Edge case from CTA decision points or use-case extension]
+- [ ] [Non-functional concern when applicable: performance threshold, accessibility, error handling]
+
+---
+
+## INVEST self-check
+
+<!--
+  Each letter answered briefly. Validate with /user-stories validate.
+  Failing one letter = WARN; failing multiple = FAIL.
+-->
+
+- **I** (Independent): [why this story can ship without other stories shipping first]
+- **N** (Negotiable): [what's flexible in implementation vs. what's fixed]
+- **V** (Valuable): [observable value to the named persona — not internal/refactor value]
+- **E** (Estimable): [team can estimate within ~30 min refinement]
+- **S** (Small): [fits in one iteration / sprint — typically 1-5 days]
+- **T** (Testable): [acceptance criteria are concrete, observable, automatable]
+
+---
+
+## Notes
+
+<!--
+  Optional. Conversation log, open questions, deferred decisions,
+  rejection criteria. Stories are conversation tokens — capture the
+  conversation here.
+-->
+
+- [Open question for refinement]
+- [Deferred decision]
+- [Constraint discovered during discussion]
+
+---
+
+## Splits / dependencies
+
+<!--
+  Optional. If this story was split from a larger one, name the parent.
+  If it has acceptable dependencies (infrastructure already in place),
+  surface them.
+-->
+
+- **Split from**: US-NNN (if applicable)
+- **Splits to**: [if this is the parent of others]
+- **Acceptable dependencies**: [infrastructure / platform reality — NOT story dependencies]