@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/pre-mortem/SKILL.md

@@ -0,0 +1,180 @@
+---
+tier: lite
+name: pre-mortem
+description: "Draft a Klein pre-mortem risk ledger for a scope (goal, feature, PR). Two modes: light (3 luminary lenses, 30 min) and full (5-8 lenses, 90 min). Always fires on auth, schema, payments, or compliance work."
+problem: "Goal docs ship without risk consideration. Teams find failures late instead of before code."
+value: "Drafts a Klein pre-mortem risk ledger for a scope. Two modes \u2014 light (3 lenses) or full (5+ lenses)."
+inputs: [A goal or feature or PR ref, Optional mode — light or full]
+outputs: [Risk ledger at docs/risk-ledgers/, Risks per lens with cures, Disposition]
+user_invocable: true
+disable_model_invocation: false
+modes: [light, full]
+composes_baseline: [gary-klein, daniel-kahneman]
+---
+
+# /pre-mortem — Klein-style risk enumeration
+
+Draft a pre-mortem risk ledger for a scope before commit. Klein's method: assume the ship failed spectacularly; silently write every reason for the failure; collate without argument; incorporate the strongest concerns into the plan as mitigations, monitoring signals, or scope cuts.
+
+Bassclef adapts the workshop shape into a written artifact — the solo operator + Claude walk multiple luminary lenses in sequence, each surfacing a distinct failure class. Output lives at `docs/risk-ledgers/<slug>.md` and feeds goal doc `## Risk ledger (pre-mortem)` sections.
+
+Two modes.
+
+- **light** (default): 30 minutes, 3 rotating luminary lenses, 5-8 risks per lens. Good for a standalone feature or a single-WU decision. Produces a short risk ledger operator can absorb in one read.
+- **full**: 90 minutes, 5-8 rotating lenses, 10-15 risks per lens. Good for an iteration goal, a security-sensitive change, or any always-fire domain (see below). Produces a research-grade risk ledger with per-risk owner + mitigation trigger + monitoring signal.
+
+## Always-fire domains
+
+The skill fires automatically at scope-commit time on:
+
+1. **Authentication and authorization** — session, MFA, SSO, RBAC, OAuth flows
+2. **Schema migrations** — especially with data backfills
+3. **Payments, billing, invoicing** — money flows in either direction
+4. **PII data handling** — export, delete, retention, cross-border transfer
+5. **Multi-tenant isolation** — RBAC boundaries between tenants
+6. **Public marketing claims** — brand promises that create legal exposure
+7. **User-lifecycle-critical flows** — account creation, deletion, password reset
+8. **Deploy pipeline changes** — CI/CD edits that touch release safety
+9. **Third-party integrations** — new external dependency in the customer path
+10. **Compliance-scoped work** — GDPR, HIPAA, SOC 2, PCI DSS
+
+Operator can extend the list per adopter via `.claude/bassclef-configs.jsonc` `pre_mortem.always_fire_domains` (V2 field; not yet wired — until then, the list above is the default).
+
+When a scope touches an always-fire domain, `/pre-mortem full` runs before scope commit unless operator explicitly defers per `.claude/rules/blocked-items.md` deferral syntax. Silence is not deferral.
+
+## Sources read
+
+- `.claude/luminaries/gary-klein.md` — full luminary with HBR 2007 method + 4-step procedure + 4 operator-URL adaptations
+- Operator direction 2026-07-07 evening — always-fire domain list + LLM-driven lens rotation for solo operator + Claude shape
+- Bet 30b risk ledger `docs/risk-ledgers/2026-06-30b-substrate-anchoring-cure.md` — reference exemplar of the multi-lens written pre-mortem shape
+
+## Sources used
+
+### Gary Klein — 4-step pre-mortem
+
+Per `.claude/luminaries/gary-klein.md` §Core methods [ref: HBR 2007]:
+
+1. **Assume failure vividly** — "Imagine the project has failed spectacularly. It is a year from now. The project shipped and it is a disaster."
+2. **Silent write-down** — each participant independently writes every reason for the failure. Silent, not shared, no debate.
+3. **Round-robin readout** — collect reasons one at a time from each source until every reason is on the list. No argument, no ranking during collection.
+4. **Strengthen the plan** — review the list post-meeting; incorporate strongest concerns into the plan as mitigations, monitoring signals, or scope cuts.
+
+### Bassclef adaptation for solo operator + Claude
+
+The "participants" in a bassclef pre-mortem are luminary lenses summoned in sequence. Each lens brings a distinct failure class:
+
+| Lens | Failure class it surfaces |
+|---|---|
+| `@luminary michael-feathers` | Cure ships without characterization test; ship-then-hope pattern |
+| `@luminary john-ousterhout` | Interface complexity; shared lib duplicates existing helper |
+| `@luminary kent-beck` | Test discipline drift; Tier 0 test written after source |
+| `@luminary tony-hoare` | Precondition or postcondition violated silently |
+| `@luminary saltzer-schroeder` | Complete mediation gap; every path not verified |
+| `@luminary michael-nygard` | Stability pattern missing; circuit breaker or bulkhead absent |
+| `@luminary daniel-kahneman` | Planning fallacy; optimism bias in time budget estimate |
+| `@luminary ash-maurya` | User perspective missing; feature solves the wrong problem |
+| `@luminary linus-torvalds` | Adopter contract broken; observable behavior changes silently |
+
+Claude prompts each lens in turn; operator writes concerns for that lens; Claude collates without ranking during the pass. Follow-up pass names owners and mitigations.
+
+## Domain → default lens map
+
+For always-fire domains, `/pre-mortem full` selects lenses matched to the failure class most likely at that domain:
+
+| Domain | Primary lens | Supporting lenses |
+|---|---|---|
+| Authentication and authorization | saltzer-schroeder | tony-hoare, michael-feathers |
+| Schema migrations | tony-hoare | michael-nygard, michael-feathers |
+| Payments and billing | michael-nygard | saltzer-schroeder, tony-hoare |
+| PII data handling | saltzer-schroeder | linus-torvalds, michael-nygard |
+| Multi-tenant isolation | saltzer-schroeder | tony-hoare, john-ousterhout |
+| Public marketing claims | ash-maurya | linus-torvalds, april-dunford |
+| User-lifecycle flows | michael-feathers | saltzer-schroeder, ash-maurya |
+| Deploy pipeline changes | michael-nygard | linus-torvalds, kent-beck |
+| Third-party integrations | vaughn-vernon (anticorruption layer) | michael-nygard, saltzer-schroeder |
+| Compliance-scoped work | saltzer-schroeder | linus-torvalds, michael-nygard |
+
+For non-always-fire scope, `/pre-mortem light` picks 3 lenses appropriate to the scope shape (operator can override).
+
+## Procedure
+
+### Common to both modes
+
+1. **Ask for the scope** — one paragraph: what's shipping, why now, what's the target outcome, what's the time budget (turns or time)
+2. **Detect always-fire signal** — grep scope description for auth, schema, payment, PII, tenant, marketing, lifecycle, deploy, integration, compliance terms; if matched, escalate to `full` mode unless operator explicitly stays in `light`
+3. **Pick lenses** — per the domain map (always-fire) or per operator preference (non-always-fire)
+4. **Walk lenses in sequence** — each lens gets its own section in the ledger; Klein's 4-step method applies within each section
+
+### Light mode (30 min)
+
+- 3 rotating lenses selected by scope shape
+- Per lens: 5-8 imagined failures written by operator; Claude collates without ranking during the pass
+- Follow-up pass: pick top 5 risks total (across all lenses); name owner + mitigation per risk
+- Output at `docs/risk-ledgers/<slug>.md` — short-form ledger
+
+### Full mode (90 min)
+
+- 5-8 rotating lenses per domain map
+- Per lens: 10-15 imagined failures; per-risk severity (high/medium/low); per-risk trigger signal (what would tell operator the risk materialized); per-risk mitigation
+- Follow-up pass: rank all risks by severity × probability; name owner + mitigation trigger + monitoring signal per top-10 risks
+- Output at `docs/risk-ledgers/<slug>.md` — research-grade ledger
+
+## Output
+
+Structured markdown artifact saved at `docs/risk-ledgers/<slug>.md`:
+
+```markdown
+---
+slug: 2026-07-07a-skills-authoring
+scope: "Bet 2026-07-07a — author 4 discovery-phase skills + audit composes_with + prototype configs UI"
+mode: full
+lenses: [michael-feathers, john-ousterhout, kent-beck, ash-maurya, gary-klein]
+date: 2026-07-07
+always_fire_matched: false
+---
+
+# Pre-mortem risk ledger — bet 2026-07-07a
+
+## Lens: Michael Feathers (characterization tests)
+
+Assume failure: "The skills shipped but adopter sessions surface bugs in the empathy-map fill order because we never characterized the actual conversational flow with a real transcript."
+
+Risks:
+1. Skill body describes the flow but no test pins the actual per-mode question count [severity: medium; owner: WU-2 test file; mitigation: characterization test that walks light mode with a fixture persona]
+2. ...
+
+## Lens: John Ousterhout (deep modules)
+...
+```
+
+## Called by
+
+`/pre-mortem` is a foundational discipline skill. Larger skills call it:
+
+- `/longrun prep` — Step 1.7 (fires at scope-commit boundary; produces bet-doc risk ledger)
+- `/build` — before Construction phase; produces feature-scope risk ledger
+- `/security-review` — always fires as part of the review chain
+- `/architect-review` — one of the two methods per `.claude/rules/architect-review-discipline.md`
+
+## Anti-patterns it prevents
+
+Per `.claude/luminaries/gary-klein.md` §Anti-patterns:
+
+- **Retrospective blame** — skill refuses to run after failure with names attached. INSTEAD: run BEFORE the failure so concerns are gifts about a hypothetical future.
+- **Generic risk lists** — skill prompts operator to write imagined failures vividly ("the migration ran during holiday freeze and locked payments for 3 hours") not generic ("the team might be busy"). INSTEAD of accepting generic entries: skill asks a follow-up probe until the risk carries a specific scenario.
+- **Skipping silent write-down** — skill enforces one-lens-at-a-time discipline; operator writes for the current lens before Claude collates. INSTEAD of a free-form brainstorm: silent per-lens pass mirrors Klein's silent-write-down step.
+- **Meeting-then-forget** — skill enforces owner + mitigation per risk; a risk without owner does not close the pass. INSTEAD of a bare risk list: the ledger has an accountable next-step per row.
+
+## Refs
+
+- Ticket #655 — this skill's filing
+- Bet 2026-07-07a — this skill's ship vehicle
+- Luminary file `.claude/luminaries/gary-klein.md` — full-depth anchor
+- Klein, G. (2007). "Performing a Project Premortem." HBR
+- Bet 30b risk ledger — reference exemplar of the multi-lens written pre-mortem shape
+- Rule `.claude/rules/loop-discipline.md` — per-PR discipline that consumes pre-mortem output
+- Rule `.claude/rules/architect-review-discipline.md` — two-method requirement composes this skill
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/prototype-gallery/SKILL.md

@@ -0,0 +1,264 @@
+---
+tier: lite
+name: prototype-gallery
+description: "Generate a variant index page for a repo's prototypes \u2014 DEPRECATED 2026-05-12 per ADR-020. Use /stage instead. Skill retained during 3-month deprecation grace before retirement."
+problem: "DEPRECATED 2026-05-12 per ADR-020. Use /stage instead."
+value: "Deprecated skill kept for backward compat. Points to /stage."
+inputs: [Redirects to /stage]
+outputs: [Deprecation notice, Redirect to /stage]
+deprecated: true
+deprecated_in_favor_of: /stage
+deprecated_decision: architecture/decisions/ADR-020-prototype-skill-family-consolidation.md
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /prototype-gallery — DEPRECATED
+
+> **Deprecation notice (2026-05-12 per ADR-020):** This skill is deprecated in favor of `/stage` (any size). `/stage` already produces a shareable gallery URL per ADR-016. New work should invoke `/stage` instead. This skill remains invocable during the deprecation grace period (≥3 months) before retirement.
+
+# /prototype-gallery — Variant Index Page
+
+Scaffold a single gallery page that lists all variants in a repo's
+`prototypes/` directory with scannable context (title + 2-line value
+prop + luminary attribution + "Open" CTA). Operator shares ONE URL;
+collaborators see every variant without tab-switching or hunting for
+per-variant URLs.
+
+First consumer wired (variant gallery with synthesis variants).
+
+## When to invoke
+
+- A repo has ≥3 variants in `prototypes/` that the operator wants to
+  share or compare side-by-side
+- After `/riff-prototypes` produces new variants in an existing
+  gallery-enabled repo (regenerate cards + copies)
+- First time wiring gallery on a repo that already has variants
+
+## When NOT to invoke
+
+- Repo has 0–2 variants — direct variant URLs are sufficient; gallery
+  adds scaffolding without value
+- Variants are still in-flight (no `gallery.yml` or README frontmatter
+  yet) — run `/riff-prototypes` to metadata-complete them first
+- Repo has hand-built index page at the target route that is NOT a
+  bassclef gallery scaffold — skill surfaces diff + asks rather than
+  overwriting
+
+## Sources read
+
+- `standards/prototype-gallery.md` — the standard this skill
+  operationalizes (directory convention, `gallery.yml` schema, route
+  rules, card shape, regeneration discipline)
+- `standards/project-directory-layout.md` — `prototypes/` is bassclef
+- `templates/gallery-yml.md` — metadata template
+- Bassclef #252 — the ticket this skill closes
+- `.claude/skills/prototype-variants/SKILL.md` — upstream producer
+
+## Prerequisites
+
+1. Consumer repo has `prototypes/<slug>/` directories with at least
+   an `index.html` per variant (skill tolerates additional assets:
+   `styles.css`, images, etc.)
+2. Each variant has either:
+   - `prototypes/<slug>/gallery.yml` (preferred), OR
+   - `prototypes/<slug>/README.md` with frontmatter matching the
+     gallery schema
+   Variants with neither block the skill — see Rules below.
+3. Consumer repo is a Next.js app (App Router) per `standards/frontend-stack.md`
+
+## Procedure
+
+### Step 1 — Scan
+
+```bash
+# List candidate variants (any directory under prototypes/ with an index.html)
+find prototypes -mindepth 2 -maxdepth 2 -name index.html -exec dirname {} \;
+```
+
+Filter out directories matching `.gitignore`d patterns. Sort alphabetically.
+
+### Step 2 — Read metadata per variant
+
+For each variant, read in priority order:
+
+1. `prototypes/<slug>/gallery.yml` — parse YAML
+2. `prototypes/<slug>/README.md` — parse frontmatter (if `.yml` missing)
+3. If neither exists: record the variant as METADATA-MISSING
+
+Produce a list of variant metadata records:
+
+```json
+{
+  "slug": "variant-a-ive-hig",
+  "title": "Variant A — Ive + HIG",
+  "value_prop": "Restrained surfaces. Operator reads the deal in under 3 seconds.\nStrong typographic hierarchy; no decorative affordances.",
+  "luminaries": ["Jony Ive", "Apple HIG"],
+  "date": "2026-04-20",
+  "status": "active"
+}
+```
+
+### Step 3 — Validate
+
+- `value_prop` ≤ 2 lines (split on `\n`, reject if >2): surface as warning,
+  truncate to 2 lines for the card
+- `status` in `{active, archived, superseded}`: default to `active`
+- `superseded` status requires `superseded_by: <slug>` — if missing, downgrade
+  to `archived` and surface warning
+- METADATA-MISSING variants: list them to the operator, STOP. Do not
+  scaffold a gallery with silent gaps.
+
+Operator confirms whether to proceed (skipping METADATA-MISSING
+variants) or abort (and backfill metadata first).
+
+### Step 4 — Detect route
+
+- If `src/app/page.tsx` exists AND differs materially from a gallery
+  scaffold (heuristic: > 50 lines OR contains imports the scaffold
+  wouldn't): route = `/prototypes` (create `src/app/prototypes/page.tsx`)
+- Else: route = `/` (create or regenerate `src/app/page.tsx`)
+
+Surface the chosen route to the operator before Step 5.
+
+### Step 5 — Copy variant HTML to `public/`
+
+For each `active` + `superseded` variant:
+
+```bash
+mkdir -p public/prototypes/<slug>
+cp -r prototypes/<slug>/* public/prototypes/<slug>/
+```
+
+Remove `public/prototypes/<slug>/README.md` and `gallery.yml` from the
+public copy (they're source-of-truth, not served artifacts).
+
+`archived` variants are NOT copied. Their `public/` copies from prior
+runs persist (old URLs still resolve).
+
+### Step 6 — Scaffold or regenerate `page.tsx`
+
+**First-time scaffold**: write the bassclef gallery scaffold (plain
+CSS-only cards, semantic markup, no framework deps beyond Next.js
+App Router).
+
+**Regenerate**: compute hash of existing `page.tsx`; compare to the
+scaffold template + current metadata:
+- If matches scaffold-with-metadata hash: regenerate (just an update)
+- If differs (hand-edited): surface diff, ask operator whether to
+  merge new variants into existing hand-edited page OR leave alone
+
+Active variants sort by `date` descending (newest first) unless the
+operator overrides via `gallery.yml`'s optional `sort_order: N` field.
+
+Superseded variants render in a collapsed "archived" section at the
+bottom, with link to `superseded_by` successor.
+
+### Anthropic baseline variant — visibly flagged (per step-11b)
+
+When `/riff-prototypes` runs (post-WU-11b), it ALWAYS emits an
+Anthropic `/frontend-design` baseline variant alongside the N
+luminary-driven variants. The baseline lives at
+`docs/prototypes/<sprint-slug>/variant-baseline-anthropic/` (the
+directory name is the marker).
+
+`/prototype-gallery` MUST render baseline cards distinctively so
+operators can tell at-a-glance which variants are luminary-driven
+(champions) vs. the Anthropic baseline (challenger). Choose ONE
+treatment per repo (consistency across sprints):
+
+- **Border**: 2px dashed (vs. solid for luminary variants), or
+- **Badge**: render "Baseline" pill above card title, or
+- **Annotation**: small italic line in card body — "Anthropic /frontend-design baseline (no luminary contamination)"
+
+The marker convention: any variant whose directory name CONTAINS
+`baseline-anthropic` (case-insensitive) renders with the chosen
+distinguishing treatment.
+
+**Why this matters**: the baseline is bassclef's champion-challenger
+measurement. If operators consistently pick baseline variants over
+luminary-driven ones, the luminary system isn't doing real work and
+needs review. Visibility in the gallery is what makes the comparison
+honest — operators must KNOW which is the baseline when picking.
+
+**Out of scope here**: the comparison signal capture (writing
+`is_baseline: <bool>` to `preview-state.yml`) lives in `/riff-prototypes`
+WU-11b output AND `/stage` workflow (WU-9). This skill just renders
+distinctively.
+
+### Step 7 — Output summary
+
+Write a short summary to stdout:
+
+```
+/prototype-gallery
+  Variants scanned: 23
+  Active: 19 (cards rendered)
+  Superseded: 4 (collapsed section)
+  Archived: 0
+  METADATA-MISSING: 0
+  Route: /
+  public/prototypes/ copies: 19 updated
+  src/app/page.tsx: scaffold written (initial)
+```
+
+## Output format
+
+Skill produces three side-effects, enumerated in the summary:
+
+1. Updated `public/prototypes/<slug>/` copies (N of them)
+2. Updated `src/app/[page].tsx` (route detected per Step 4)
+3. stdout summary + any warnings (METADATA-MISSING, value-prop truncation, route conflicts)
+
+No artifacts in `docs/` (this skill is runtime scaffolding, not
+methodology documentation — the standard already covers that).
+
+## Rules
+
+- **Read-only on variant HTML.** Never modify files under `prototypes/`
+  during scaffold/regenerate. The skill is downstream; operator edits
+  flow upstream only.
+- **Never overwrite a hand-edited `page.tsx` silently.** Hash-check
+  against scaffold template; on mismatch, surface diff + ask.
+- **Never synthesize metadata defaults.** A variant without `gallery.yml`
+  or README frontmatter blocks the skill. A gallery card without a
+  value prop is worse than no card.
+- **Additive regeneration for archived/superseded.** Don't delete
+  `public/prototypes/<archived-slug>/`. Old URLs keep resolving for
+  operators who bookmarked them.
+- **Respect the route-detection heuristic.** If operator wants to force
+  a specific route, they edit `src/app/` directly and re-run; skill
+  detects hand-edit and pauses per Rule 2.
+
+## Mode dispatch
+
+| Invocation | Behavior |
+|-----------|----------|
+| `/prototype-gallery` (no args) | Full scan + regenerate; prompt before overwriting hand-edited `page.tsx` |
+| `/prototype-gallery --dry-run` | Scan + validate + emit summary; no file writes |
+| `/prototype-gallery --force` | Overwrite `page.tsx` without prompting (use when operator has confirmed in-session) |
+
+## Relationship to other skills
+
+- `/riff-prototypes` — upstream producer of the variants this skill indexes
+- `/visual-review` — evaluates a single variant; gallery doesn't replace the review, just surfaces the variants for sharing + decision
+- `/frontend-design` — if the consumer app's scaffold needs the gallery styled to match brand direction, run after this skill to refine card aesthetics
+- `/substrate-check` — validates the consumer repo has the skill wired after bassclef-sync
+
+## Open-source propagation
+
+This skill lives in bassclef's `.claude/skills/` and propagates to
+consumer repos via `bassclef-sync.sh` (per ADR-014). Consumer repos
+inherit it automatically on next session-start. No per-repo install.
+
+## Retirement condition
+
+Retires alongside `standards/prototype-gallery.md` if operators stop
+running multi-variant bets. The skill file is removable without data
+loss — variant HTML and metadata stay on disk at `prototypes/`.
+
+Closes bassclef #252.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.