@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/synthetic-user/SKILL.md

@@ -0,0 +1,381 @@
+---
+tier: lite
+name: synthetic-user
+description: "Run persona-aware Playwright tests that simulate real user journeys, verify feature parity, and auto-file JTBD proposals as GitHub issues. Requires Playwright MCP and persona definitions."
+problem: "Feature parity across releases needs real user journey coverage. Manual test walks take hours."
+value: "Persona-aware Playwright tests that simulate real user journeys. Verify feature parity per persona."
+inputs: [Persona ref, Optional flow or tier level]
+outputs: [Playwright test run, Feature parity report, Screenshot diffs]
+user_invocable: true
+disable_model_invocation: false
+requires:
+  cli: [npx, gh]
+  mcp: [playwright]
+  files: [docs/design/personas/]
+---
+
+# Synthetic User Testing
+
+Simulate real users interacting with the application. Synthetic users
+don't just find bugs — they propose features and fixes that auto-populate
+the backlog using the JTBD construct.
+
+This skill runs at three tiers. Each tier builds on the previous one.
+See `standards/synthetic-user-testing.md` for the full framework.
+
+## When to run
+
+- **After any UI migration or redesign** — verify nothing was silently dropped
+- **After adding a new surface** — smoke test it immediately
+- **Before a release** — run Tier 2+ on all critical surfaces
+- **On a schedule** — Tier 1 in CI on every PR, Tier 2 weekly, Tier 3 monthly
+- **When lead volume ramps** — stress-test flows before real users hit pain points
+
+## When to skip
+
+- No rendered UI exists yet (pure API work, schema changes)
+- The change is documentation-only
+
+## Prerequisites
+
+### Infrastructure check
+
+Check if Playwright MCP is available by looking for the
+`mcp__playwright__browser_navigate` tool. If it's NOT available:
+
+1. Tell the user:
+   > Synthetic user testing requires Playwright MCP but it's not available.
+   > Add to .claude/settings.json:
+   > ```json
+   > { "mcpServers": { "playwright": {
+   >     "command": "npx",
+   >     "args": ["@anthropic-ai/mcp-server-playwright"]
+   > }}}
+   > ```
+   > Then restart the session.
+
+2. If Playwright is unavailable, Tier 1 can run in degraded mode
+   (code-level checks only). Tiers 2-3 require Playwright — do not
+   attempt them without it.
+
+### Persona definitions
+
+Personas must exist at `docs/design/personas/` in the app repo.
+Run `/jtbd-tasks` Step 0 to bootstrap them — five fields minimum
+(name, age, role, device, goal, jargon comfort), extended profiling
+optional.
+
+If no persona files exist, the skill will prompt you to run
+`/jtbd-tasks` Step 0 before proceeding to Tier 3. Tiers 1-2 can
+run without personas.
+
+### Task scenarios
+
+For Tier 3, task scenarios from `/jtbd-tasks` + `/task-scenarios` provide
+the user flows to test. If these don't exist, the skill derives flows
+from persona goals — but explicit scenarios produce better coverage.
+
+## Procedure
+
+### Step 0: Select Tier
+
+Ask the operator which tier to run (or run all three sequentially):
+
+| Tier | What it tests | Time | Requires |
+|------|--------------|------|----------|
+| 1 — Smoke | Pages load, key elements render, no crashes | ~5 min | Playwright |
+| 2 — Feature parity | Capabilities survive across rewrites | ~15 min | Playwright + surface inventory |
+| 3 — User journeys | Multi-page persona flows + JTBD proposals | ~30 min | Playwright + personas + scenarios |
+
+---
+
+### Tier 1: Smoke Tests
+
+One test per page: loads, renders key elements, responds to basic interaction.
+
+#### Step 1.1: Inventory pages
+
+List every route in the application:
+
+```markdown
+## Page Inventory
+
+| Route | Page name | Auth required | Key elements |
+|-------|-----------|---------------|--------------|
+| / | Home/Dashboard | Yes | Nav, summary cards, recent activity |
+| /pipeline | Pipeline | Yes | Table, filters, sort headers, search |
+| /deals/[id] | Deal detail | Yes | Deal header, scores, financials, actions |
+```
+
+#### Step 1.2: Run smoke checks
+
+For each page:
+
+1. Navigate via `mcp__playwright__browser_navigate`
+2. Wait for load via `mcp__playwright__browser_wait_for`
+3. Take screenshot via `mcp__playwright__browser_take_screenshot`
+4. Capture accessibility snapshot via `mcp__playwright__browser_snapshot`
+5. Verify key elements exist in the snapshot
+
+```markdown
+## Smoke Results
+
+| Route | Loads | Key elements present | Errors in console | Screenshot | Result |
+|-------|-------|---------------------|-------------------|------------|--------|
+| / | Yes | Nav, cards, activity | None | [link] | PASS |
+| /pipeline | Yes | Table, filters | 1 warning (React key) | [link] | PASS |
+| /deals/123 | Yes | Header, scores | TypeError: undefined | [link] | FAIL |
+```
+
+#### Step 1.3: Check console errors
+
+Use `mcp__playwright__browser_console_messages` to capture errors.
+Any `error`-level console message is a FAIL. Warnings are noted but pass.
+
+---
+
+### Tier 2: Feature Parity Tests
+
+For each surface, test that capabilities survive any rewrite.
+
+#### Step 2.1: Build the capabilities inventory
+
+Before testing, inventory what each surface DOES (not just how it looks).
+This is the same capabilities diff from `/ux-migration` Step 1b:
+
+```markdown
+## Capabilities Inventory: [Surface]
+
+| # | Capability | How to verify | Expected behavior |
+|---|-----------|---------------|-------------------|
+| 1 | Text search | Type in search input, verify results filter | Table shows only matching rows |
+| 2 | Column sort | Click column header, verify order changes | Rows reorder by clicked column |
+| 3 | Track filter | Click "1031" filter, verify results narrow | Only 1031-exchange deals shown |
+| 4 | Pagination | Click next page, verify new results load | Different rows appear |
+| 5 | Deal link | Click deal row, verify navigation | Navigates to /deals/[id] |
+| 6 | Financial display | Inspect financial columns | Numbers formatted with $ and commas |
+```
+
+#### Step 2.2: Execute capability tests
+
+For each capability:
+
+1. Navigate to the surface
+2. Perform the interaction via Playwright MCP tools
+   (`browser_click`, `browser_fill_form`, `browser_press_key`, etc.)
+3. Verify the expected behavior via snapshot or screenshot
+4. Record pass/fail
+
+```markdown
+## Feature Parity Results: [Surface]
+
+| # | Capability | Status | Notes |
+|---|-----------|--------|-------|
+| 1 | Text search | PASS | Filters correctly |
+| 2 | Column sort | FAIL | Header exists but click does nothing |
+| 3 | Track filter | MISSING | Filter UI not present on new page |
+| 4 | Pagination | PASS | |
+| 5 | Deal link | PASS | |
+| 6 | Financial display | PASS | |
+
+**Parity score**: 4/6 (67%) — FAIL threshold is <100%
+```
+
+#### Step 2.3: File issues for failures
+
+For each FAIL or MISSING capability:
+- File a GitHub issue with label `feature-parity`
+- Reference the migration PR/issue
+- Include the capability description and expected behavior
+
+---
+
+### Tier 3: User Journey Tests + Synthetic Proposals
+
+Multi-page flows framed as persona tasks. This is where synthetic users
+propose features, not just report bugs.
+
+#### Step 3.1: Load personas and scenarios
+
+Read persona definitions from `docs/design/personas/`.
+Read task scenarios from `/task-scenarios` output. When `/task-scenarios` has not yet run for this scope, the skill BLOCKs with `INSTEAD: run /task-scenarios first; this skill consumes its output`.
+
+Map each persona to their primary flows:
+
+```markdown
+## Persona → Flow Mapping
+
+| Persona | Primary flow | Pages involved | Scenario source |
+|---------|-------------|----------------|-----------------|
+| Mom (76, Viewer, mobile Safari) | Find recommended deals → read scores | /, /deals/[id] | JTBD-003 |
+| Operator (power user, desktop) | Pipeline → sort → detail → outreach | /pipeline, /deals/[id], /outreach | JTBD-001 |
+| Family member (mobile) | Vote on deal → see consensus | /deals/[id], /votes | JTBD-005 |
+```
+
+#### Step 3.2: Execute persona journeys
+
+For each persona:
+
+1. **Set viewport** to match their device
+   - Mobile Safari: 375x812
+   - Desktop Chrome: 1280x800
+   - Tablet: 768x1024
+
+2. **Walk the flow** step by step via Playwright MCP:
+   - Navigate to starting page
+   - Perform each action in the flow
+   - At each step, evaluate: can the persona accomplish their goal?
+   - Screenshot at each decision point
+
+3. **Evaluate through persona lens**:
+   - **Comprehension**: Would this persona understand what they're seeing?
+     (Mom shouldn't see "BIZBUYSELL" or "CAP_RATE_PCT")
+   - **Navigation**: Can they find the next step without instructions?
+   - **Completion**: Can they finish their task end-to-end?
+   - **Friction**: What slowed them down or confused them?
+
+```markdown
+## Journey Report: [Persona Name]
+
+**Device**: [viewport]
+**Flow**: [description]
+**Result**: COMPLETE / BLOCKED at step N / DEGRADED
+
+| Step | Action | Expected | Actual | Screenshot | Status |
+|------|--------|----------|--------|------------|--------|
+| 1 | Navigate to / | See dashboard | Dashboard loads | [link] | PASS |
+| 2 | Find recommended deals | Clear section for recommendations | No "recommended" section visible | [link] | FAIL |
+| 3 | Click a deal | See deal detail | — (blocked by step 2) | — | BLOCKED |
+
+**Friction points**:
+- Step 2: No clear path from dashboard to "deals for me"
+- Financial jargon visible (CAP_RATE) — Mom wouldn't understand
+
+**Comprehension issues**:
+- "Pipeline" label means nothing to a Viewer role
+- Score of "73" has no context — 73 out of what?
+```
+
+#### Step 3.3: Generate JTBD proposals
+
+This is the distinctive step. For each friction point or gap discovered,
+generate a feature proposal in JTBD format:
+
+```markdown
+> As [Persona], it would be great if I could [capability]
+> so I could [outcome].
+```
+
+Proposals must be:
+- **Grounded** — tied to a specific friction point observed in the journey
+- **Persona-specific** — framed from their perspective, not the developer's
+- **Actionable** — specific enough to become an issue
+
+Examples:
+> As Mom, it would be great if I could see which deals the family voted
+> on so I could know what to research before Sunday dinner.
+>
+> As Operator, it would be great if I could filter pipeline by outreach
+> status so I could focus on deals that haven't been contacted yet.
+>
+> As Family Member, it would be great if I could vote from the deal
+> card without opening the detail page so I could review faster on mobile.
+
+#### Step 3.4: Auto-file proposals as GitHub issues
+
+For each JTBD proposal, create a GitHub issue:
+
+```bash
+gh issue create \
+  --title "feat: [capability from proposal]" \
+  --label "synthetic-user,enhancement" \
+  --body "$(cat <<'EOF'
+## Source
+Synthetic user test — [Persona Name] journey
+Date: [today]
+
+## JTBD Proposal
+> As [Persona], it would be great if I could [capability]
+> so I could [outcome].
+
+## Context
+- Observed during: [flow description]
+- Friction point: [what went wrong or was missing]
+- Screenshot: [link if available]
+
+## Acceptance Criteria
+- [ ] [Persona] can [capability] from [surface]
+- [ ] Verified via synthetic user re-test
+EOF
+)"
+```
+
+Label all synthetic user issues with `synthetic-user` so they can be
+filtered and prioritized separately from operator-filed issues.
+
+---
+
+### Step 4: Output the Report
+
+Write the full report to `docs/synthetic-user-reports/YYYY-MM-DD.md`:
+
+```markdown
+# Synthetic User Report — [Date]
+
+## Summary
+
+| Tier | Surfaces tested | Pass | Fail | Missing |
+|------|----------------|------|------|---------|
+| 1 — Smoke | 8 | 7 | 1 | 0 |
+| 2 — Parity | 3 surfaces, 18 capabilities | 15 | 2 | 1 |
+| 3 — Journeys | 3 personas, 3 flows | 1 complete | 1 blocked | 1 degraded |
+
+## Issues Filed
+
+| # | Title | Persona | Type | Priority |
+|---|-------|---------|------|----------|
+| 201 | feat: recommended deals section on dashboard | Mom | proposal | medium |
+| 202 | fix: column sort not functional on pipeline | — | parity | high |
+| 203 | fix: track filter missing from new pipeline | — | parity | critical |
+| 204 | feat: vote from deal card on mobile | Family Member | proposal | low |
+
+## Tier 1: Smoke Results
+[from Step 1.2]
+
+## Tier 2: Feature Parity Results
+[from Step 2.2, per surface]
+
+## Tier 3: Journey Reports
+[from Step 3.2, per persona]
+
+## JTBD Proposals
+[from Step 3.3, all proposals listed]
+
+## Recommendations
+- **Critical** (blocks release): [list]
+- **High** (fix this iteration): [list]
+- **Medium** (backlog): [list]
+- **Low** (nice-to-have): [list]
+```
+
+## Degraded Mode (no Playwright)
+
+If Playwright MCP is unavailable:
+
+- **Tier 1**: Can run in code-analysis mode — check routes exist, components
+  render, no TypeScript errors. Note "degraded — no browser" in report.
+- **Tier 2**: Can verify capabilities exist in code (grep for search inputs,
+  sort handlers, filter components). Cannot verify they work. Note gaps.
+- **Tier 3**: Cannot run. Persona journeys require a browser.
+
+## What this skill does NOT do
+
+- Write Playwright test files for CI (that's app-level test authoring)
+- Fix the issues it finds (it files them)
+- Replace manual user testing (it supplements it)
+- Generate personas (use `/jtbd-tasks` to derive them from research)
+- Run in CI automatically (see #79 for headless/CI visual review)
+
+## 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/task-scenarios/SKILL.md

@@ -0,0 +1,105 @@
+---
+tier: lite
+name: task-scenarios
+description: "Convert task analysis into user stories and scenarios with JTBD traceability. Second step in the UX translation chain."
+problem: "Task analysis outputs stay abstract. Downstream user stories skip JTBD traceability."
+value: "Converts task analysis into user stories or scenarios with JTBD traceability."
+inputs: [Task analysis output from /jtbd-tasks]
+outputs: [User stories with JTBD refs, Scenario narratives, Trace matrix]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Task Analysis → Scenarios + Stories
+
+Convert HTA/CTA task flows into narrative scenarios and (currently)
+user stories that trace back to JTBDs.
+
+> **Boundary note** (added 2026-04-19 with the bassclef promotion of
+> `/user-stories`): user stories and task scenarios are *distinct
+> artifacts* per Nielsen Norman Group + Cockburn. The current version
+> of this skill produces both — that conflation is being disentangled.
+>
+> **For backlog-intake stories** (formulaic As-a-I-want-So-that, INVEST-
+> shaped, for sprint planning): use `/user-stories`.
+>
+> **For UX research narrative scenarios** ("Sam is stuck in traffic,
+> running late…" with mental state, obstacles, environment — for
+> usability testing and `/synthetic-user`): use this skill.
+>
+> A follow-up bassclef-evolution ticket tracks refocusing this skill
+> on the NN/G narrative-scenario surface only (stripping the stories
+> output that now belongs to `/user-stories`). Until that lands, this
+> skill remains usable for both — but new work SHOULD prefer the
+> dedicated skills for clarity.
+
+## When to Use
+
+- After running `/jtbd-tasks` — task flows exist but not yet stories
+- When writing stories and need to verify they connect to real jobs
+- When reviewing a backlog and stories feel disconnected from user intent
+- **The discipline**: every story must trace to a JTBD. If it can't, question whether it belongs.
+
+## Method
+
+### 1. Map Tasks to Stories
+
+```markdown
+### Story: [imperative title]
+
+**As a** [persona],
+**I want to** [task from HTA],
+**So that** [goal from JTBD].
+
+**Job trace**: JTBD #N → Goal M → Task M.X
+**CTA decisions**: [what judgment does the user make? what cues do they need?]
+
+**Acceptance criteria**:
+- [ ] [observable behavior]
+- [ ] [edge case from CTA decision points]
+```
+
+### 2. Scenario Writing
+
+For judgment-heavy tasks (CTA), write scenarios that capture the decision context:
+
+```markdown
+### Scenario: [descriptive name]
+
+**Given** [context — what state is the user in?],
+**When** [trigger — what do they do?],
+**Then** [outcome — what should happen?].
+
+**Variant**: [what if the decision goes the other way?]
+```
+
+### 3. Traceability Matrix
+
+```markdown
+| Story | JTBD | HTA Task | CTA Decision | Priority |
+|-------|------|----------|-------------|----------|
+| ... | ... | ... | ... | ... |
+```
+
+**Red flag**: A story with no JTBD trace is a solution looking for a problem.
+**Red flag**: A JTBD with no stories is an unserved user need.
+
+## Anti-Patterns
+
+- Writing stories from features instead of jobs ("add a sidebar" — why?)
+- Skipping task analysis and jumping from JTBD to stories (loses the "how")
+- Stories that describe implementation, not behavior
+- Acceptance criteria that test code, not user outcomes
+
+## Next Step
+
+Stories feed into `/ia-model` (entity inventory + navigation structure).
+
+## References
+
+- Mike Cohn, *User Stories Applied*
+- Jim Kalbach, *The Jobs to Be Done Playbook*
+
+## 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/tier-dependency-audit/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: tier-dependency-audit
+description: "Audit tier coverage. Sort every file into 4 buckets \u2014 tagged, missing tag, leak, missing from release. Works across lite, standard, standard-pro, ultra, upstream. Run before release to catch drift."
+problem: "Tier coverage drifts across releases. Some files carry no tag; some tags mismatch the release manifest."
+value: "Audits tier coverage. Sorts every file into 4 buckets \u2014 tagged or missing tag or leak or missing from release."
+inputs: [Optional bucket filter]
+outputs: [Bucket count per class, Findings per file, Cure suggestions]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+composes_with: []
+---
+
+# tier-dependency-audit
+
+## What you get
+
+A manifest with four buckets. Bucket 1 is tagged files that ship right. Bucket 2 is real deps that need a tag. Bucket 3 is leaks that need removal. Bucket 4 is real deps missing from the release. The file lands at `docs/dependency-audits/<date>-<tier>.md`.
+
+## When to use it
+
+Run it before a release when the tier has drifted. Run it after you add a new adopter-runtime dep. Run it per tier as a periodic check. Run it when a new tier ships to build its first manifest.
+
+## Usage
+
+```bash
+/tier-dependency-audit lite
+```
+
+Or call the script:
+
+```bash
+scripts/analyze-tier-dependencies.sh lite
+```
+
+Both write to the same file. Re-running overwrites it.
+
+<!-- FKGL-EXEMPT: technical arg + override enumeration -->
+## Args
+
+| Arg | Values | Default |
+|---|---|---|
+| `<tier>` | one of lite / standard / standard-pro / ultra / upstream | required |
+
+## Overrides
+
+For advanced use or Tier 0 tests:
+
+- `OUTPUT_DIR` — where to write the manifest
+- `INTENDED_FIXTURE` — pre-computed INTENDED set file (test only)
+- `ACTUAL_FIXTURE` — pre-computed ACTUAL set file (test only)
+- `TAGS_FIXTURE` — pre-computed tag file (test only)
+- `RUNTIME_DEPS_FILE` — override the tier-runtime-deps file location
+- `SKIP_TIER_DEPENDENCY_AUDIT=1` — bypass; exits 0
+<!-- /FKGL-EXEMPT -->
+
+## The four buckets
+
+**Bucket 1 — Tagged.** File has the tier tag. It ships right. Nothing to do.
+
+**Bucket 2 — Missing tag.** File is a real dep per the graph walk. Currently ships via a bypass branch. Add the tier tag.
+
+**Bucket 3 — Accidental leak.** File ships now but is not in the graph. Remove it from the repo. Extend `.gitignore`.
+
+**Bucket 4 — Missing from release.** File is in the graph but not in the release list. Extend the release script or fix a filter.
+
+## Recommended fix order
+
+The manifest lists a fix order. Follow it top to bottom:
+
+1. Fix Bucket 4 first. A release script gap may hide real ships.
+2. Fix Bucket 2 next. Add tags to real deps.
+3. Fix Bucket 3 last. Remove leaks and extend `.gitignore`.
+
+## Details below the fold
+
+### What it does under the hood
+
+The script sources `lib/tier-dependency-audit.sh`. That lib holds eight named functions per the decomposition. One function per Larman GRASP job.
+
+<!-- FKGL-EXEMPT: technical data-source enumeration -->
+The 4 data sources:
+
+- **Source 1** — files carrying `tier: <tier>` frontmatter or header (the root set)
+- **Source 2** — files reachable from the root set via reference walk (composes_with, source lib, @luminary, etc.)
+- **Source 3** — adopter-runtime deps from `standards/tier-runtime-deps/<tier>.md`
+- **Source 4** — release script `--dry-run` include list
+<!-- /FKGL-EXEMPT -->
+
+Union Sources 1+2+3 to get INTENDED. Source 4 is ACTUAL. Classify each file into a bucket.
+
+### Reuse across tiers
+
+One script serves all tiers. The tier arg picks the root set and adopter-runtime dep list. The walk is the same. Build the lite manifest first. Add tier-runtime dep lists for standard, standard-pro, ultra, upstream as those tiers mature.
+
+<!-- FKGL-EXEMPT: technical exit code table -->
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Manifest written |
+| 2 | Missing or invalid tier arg |
+| 3 | Missing runtime-deps or intended fixture file |
+| 4 | Release script dry-run failed |
+| 5 | Output directory not writable |
+<!-- /FKGL-EXEMPT -->
+
+<!-- FKGL-EXEMPT: technical composes-with bullet list -->
+### Composes with
+
+- `standards/tier-dependency-analysis.md` — walk algorithm
+- `standards/tier-tag-schema.md` — per-file tier tag rules
+- `standards/tier-runtime-deps/<tier>.md` — Source 3 adopter-runtime deps per tier
+- `scripts/release-to-bassclef.sh` — Source 4 comes from `--dry-run`
+- `lib/tier-dependency-audit.sh` — sourced lib with the 8 named functions
+- `.claude/hooks/tests/lib-tier-dependency-audit.test.sh` — 32 per-function tests
+- `.claude/hooks/tests/tier-dependency-audit.test.sh` — 15 end-to-end tests
+- `.claude/rules/mechanism-fidelity.md` — the audit is the mechanism paired with tier-tag-schema
+<!-- /FKGL-EXEMPT -->
+
+### Rules
+
+Do not edit the manifest by hand. INSTEAD: re-run the audit and let it overwrite the file. Do not commit the manifest long-term. INSTEAD: treat it as regenerable and gitignore the output dir. Bucket 4 may hide a release script bug. Look at the file first before adding a tag.
+
+<!-- FKGL-EXEMPT: refs section with technical citations -->
+### Refs
+
+- `standards/tier-dependency-analysis.md`
+- `standards/tier-tag-schema.md`
+- `standards/tier-runtime-deps/lite.md`
+- Goal doc `docs/iteration-bets/2026-08-17a-tier-dependency-audit-subsystem.md`
+- Use case `docs/use-cases/UC-script-tier-dependency-audit.md`
+- Decompositions `docs/decompositions/2026-08-17a-tier-dependency-audit-domain.md` + `.md`
+- ADR-029 release pipeline
+- ADR-031 we-dont-break-adopters
+- @luminary john-ousterhout — deep modules (information hiding via narrow interfaces)
+- @luminary michael-nygard — fail-safe default
+- @luminary michael-feathers — characterization tests
+<!-- /FKGL-EXEMPT -->