@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/jtbd-tasks/SKILL.md

@@ -0,0 +1,203 @@
+---
+tier: lite
+name: jtbd-tasks
+description: "Translate Jobs-to-be-Done into task analysis \u2014 HTA trees plus CTA decision points. First step in the UX translation chain."
+problem: "Jobs-to-be-Done get named but not decomposed. Downstream UX work skips the task hierarchy."
+value: "Translates JTBDs into HTA trees and CTA decision points. First step in the UX translation chain."
+inputs: [A JTBD statement or persona ref]
+outputs: [Hierarchical task analysis tree, Critical decision points, Task inventory]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# JTBD → Task Analysis
+
+Translate job statements into concrete task flows. First layer in the
+JTBD → HTA → IA → State Diagram translation chain.
+
+## When to Use
+
+- During the **Design phase** of the SDLC, concurrent with design diagrams
+- A new feature or initiative enters the Design phase
+- The user describes what they want to accomplish (a "job")
+- Requirements feel vague — decompose into actionable tasks
+- Before writing user stories — stories trace to tasks, tasks trace to jobs
+- UX fitness review flags stale task analysis
+
+## Step 0: Bootstrap Personas
+
+Before decomposing jobs, establish WHO has them. If persona files already
+exist at `docs/design/personas/`, read them and skip to Method 1.
+
+If no personas exist, check for existing canvas definitions first:
+
+### Canvas-aware bootstrapping
+
+Search the repo for product canvases that already define users or personas:
+
+1. Glob for canvas files: `strategy/canvases/**/*.md`, `docs/strategy/canvases/**/*.md`
+2. In each canvas, look for persona tables, user lists, early adopter
+   sections, or "Users / Personas" headings
+3. Extract: name, role, tech level, and any other fields present
+
+If canvases exist with persona data, pre-populate the minimum viable
+persona and confirm with the operator:
+
+> "I found [Name] in [canvas file] — [Role], [tech level].
+> I'll create their persona file with what's here. Confirm or adjust."
+
+This avoids re-asking what the operator already defined during product
+shaping. The canvas is the source of "who and why." The persona file
+adds "how" (device, jargon, patience) for testing.
+
+If no canvases exist or canvases don't define personas, ask the operator
+to name the people who use (or will use) the product.
+
+### Minimum viable persona
+
+For each person, capture the **minimum viable persona**:
+
+```markdown
+# [Name]
+
+- **Age**: [age]
+- **Role**: [product role — Viewer, Operator, Admin, etc.]
+- **Device**: [primary device — mobile Safari, desktop Chrome, etc.]
+- **Goal**: [the one job they hire this product to do]
+- **Jargon comfort**: [knows domain terms / needs plain language]
+```
+
+Five fields. That's the floor — enough to set a Playwright viewport,
+filter jargon, and frame a JTBD statement.
+
+Write each persona to `docs/design/personas/[name].md`.
+
+### Deeper profiling (optional — run when persona-driven testing reveals gaps)
+
+If Tier 3 synthetic user tests produce shallow results, or if personas
+feel interchangeable, extend with these questions. Ask only what's needed
+— not all at once.
+
+**Psychographic (how they think):**
+
+| Field | Question | Drives |
+|-------|----------|--------|
+| Alternative | What do they use if this product doesn't exist? | Bar for "good enough" |
+| Trust signal | How do they know the data is right? | What "score: 73" means to them |
+| Density preference | Everything at once, or guided step by step? | Tables vs. progressive disclosure |
+| Patience | How many steps before they bail? | Friction threshold for journey tests |
+| Decision style | Gut feel or compare-the-numbers? | Whether they need charts or recommendations |
+| Comeback trigger | What would make them open this tomorrow? | Retention signal |
+| Never-word | A word they'd never use? | Jargon violation detector |
+
+**Relationship (who they interact with):**
+
+| Field | Question | Drives |
+|-------|----------|--------|
+| Linked personas | Who else uses this that they depend on? | Multi-persona journey tests |
+| Needs from others | What do they need from other users' actions? | Handoff point testing |
+| Cadence | Async (check when convenient) or sync (scheduled)? | When/how often they visit |
+
+Add extended fields to the existing persona file under a `## Profile`
+section. The minimum viable fields stay at the top — extended fields
+are additive, never replace the core five.
+
+```markdown
+# [Name]
+
+- **Age**: [age]
+- **Role**: [role]
+- **Device**: [device]
+- **Goal**: [goal]
+- **Jargon comfort**: [level]
+
+## Profile
+
+- **Alternative**: spreadsheet + phone calls
+- **Trust signal**: sees who entered the data and when
+- **Density**: wants everything visible — hates clicking to reveal
+- **Patience**: 10+ clicks if each is productive
+- **Decision style**: compare numbers side by side
+- **Comeback trigger**: new deals appeared since last visit
+- **Never-word**: "thingy"
+
+## Relationships
+
+- **Linked to**: Mom (curates deals for her), Family (shares shortlist)
+- **Needs from others**: family votes before Sunday dinner
+- **Cadence**: daily check, 5-10 minutes
+```
+
+## Method 1: Hierarchical Task Analysis (HTA)
+
+For **sequential, procedural work** — steps that follow a predictable order.
+
+Break each job into: **Goal → Plan → Subtasks → Operations**
+
+```
+JOB: [job statement]
+
+GOAL 1: [goal]
+  PLAN: [strategy for achieving goal]
+  1.1 [subtask]
+  1.2 [subtask]
+  1.3 [subtask]
+
+GOAL 2: [goal]
+  PLAN: [strategy]
+  2.1 [subtask]
+  ...
+```
+
+## Method 2: Cognitive Task Analysis (CTA)
+
+For **judgment-heavy work** — where expertise drives decisions, not just steps.
+
+Add to the HTA: **decision points, mental models, and expertise cues**
+
+```
+GOAL 2: [goal]
+  DECISION: [what judgment is needed?]
+    CUES: [what information triggers the decision?]
+    MENTAL MODEL: [what expertise is applied?]
+    EXPERTISE: [what do experienced users look at first?]
+```
+
+## Output Format
+
+For each JTBD, produce:
+
+```markdown
+## Job: [job statement]
+
+### HTA Tree
+- Goal 1: [goal]
+  - 1.1 [subtask]
+  - 1.2 [subtask] → DECISION: [what judgment?]
+    - Cues: [what triggers the decision?]
+    - Mental model: [what expertise?]
+  - 1.3 [subtask]
+- Goal 2: ...
+
+### Task Flow Diagram (Mermaid)
+[flowchart showing sequential + branching task flow]
+
+### Traceability
+| Task | JTBD | UI Implication |
+|------|------|----------------|
+| 1.1 ... | [job] | [screen or component implied] |
+```
+
+## Next Step
+
+Output feeds into `/task-scenarios` (user stories) or directly into `/ia-model` (entity-driven IA).
+
+## References
+
+- Alan Cooper, *About Face* — Goal-Directed Design
+- Don Norman, *The Design of Everyday Things* — task analysis foundations
+- Annett & Duncan (1967) — original HTA methodology
+
+## 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/objectory-decompose/SKILL.md

@@ -0,0 +1,256 @@
+---
+tier: lite
+name: objectory-decompose
+description: "Apply Jacobson's analysis method to an InputArtifact. Extracts entities (domain nouns), actors (verb subjects), verb-goal pairs (use case candidates). Classifies objects per BCE (Boundary / Control / Entity). Output at docs/decompositions/."
+problem: "Analysis phase skips systematic domain decomposition. Downstream classes miss real responsibilities."
+value: "Applies Jacobson's analysis method to an InputArtifact. Extracts entities and actors and use cases."
+inputs: [An InputArtifact from /interpret-input]
+outputs: [Entity list — domain nouns, Actor list — verb roles, Use case sketch]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /objectory-decompose — Jacobson Domain Decomposition (MVP)
+
+Second step of the cameo pipeline. Takes a normalized
+`InputArtifact` (output of `/interpret-input`) and applies Jacobson's
+analysis method to produce an entity inventory + actor list +
+verb-goal pairs + BCE classification matrix.
+
+This is the bassclef-side "extraction" step — `/value-prop` and
+`/riff-prototypes` downstream consume the decomposition to drive
+variant generation grounded in actual domain language, not generic UI.
+
+Per parent cameo pipeline goal's amendment 2026-04-26c — input
+shape lives in the `InputArtifact`, not in this skill's args. Adding
+new input modes (Phase C: URL, image, repo, transcript, napkin)
+becomes adapter work in `/interpret-input`, not core extraction
+changes here.
+
+## When to invoke
+
+- workflow: `/stage <tier>` calls this after `/interpret-input`
+- Standalone analysis: operator has an InputArtifact and wants the
+  Jacobson decomposition without running the full pipeline
+- Debugging: re-run decomposition against an existing InputArtifact
+  to compare extraction quality
+
+## What this skill is NOT
+
+| Skill | Altitude | Output |
+|-------|----------|--------|
+| `/objectory-decompose` | **Jacobson analysis** | Entity inventory + BCE matrix + verb-goal pairs |
+| `/use-case` | Cockburn formalization | Numbered scenarios + extensions (separate skill) |
+| `/decompose` | GRASP responsibility-assignment | Class responsibilities + patterns (Larman, design-time) |
+| `/personas` | WHO primitive | Persona definitions (separate primitive) |
+
+The three OOA/D thinkers compose linearly: Jacobson (this skill) →
+Cockburn (`/use-case`) → Larman (`/decompose`). MVP ships Jacobson;
+Cockburn formalization is deferred to follow-up goals.
+
+## Procedure
+
+### 1. Read InputArtifact via accessor
+
+```bash
+source lib/state.sh
+INPUT=$(state_reference_get input-artifact "<slug>")
+```
+
+Or via wrapper:
+
+```bash
+INPUT=$(bash scripts/state.sh get reference input-artifact "<slug>")
+```
+
+**Required fields** (extract via `jq`):
+- `extracted_text` — the load-bearing input for analysis
+- `type` — guides extraction (text vs. URL vs. image have different signals)
+- `structural_hints.entities_seen[]` — pre-extractor hints (may be empty)
+- `structural_hints.actor_candidates[]` — pre-extractor hints (may be empty)
+
+**Stub-mode handling**: if `extracted_text == "deferred to Phase C"`,
+the input is a stub (Phase B doesn't implement extractors for non-text
+modes). Surface a warning and produce a minimal decomposition with
+empty inventories — operator's signal that downstream consumers will
+have nothing meaningful to consume.
+
+### 2. Apply Jacobson method
+
+For each section, the agent (the LLM running this skill) reads
+`extracted_text` and identifies:
+
+#### Entity inventory (nouns)
+
+Domain nouns the system tracks. NOT generic technical concepts (like
+"user" or "session" — those are control/boundary, not entity).
+
+For the operator paragraph "deals that work for the family... close
+to Wilmington... CPA business... organic food business", entities
+might be: Deal, Business, Owner, Location, Cashflow, Family, Industry.
+
+Output as bullet list under `## Entities`.
+
+#### Actor list
+
+Roles that interact with the system. Subjects of verbs in
+`extracted_text`. Distinct from entities — an actor uses the system;
+an entity is in the system.
+
+For the operator paragraph: Operator (the searcher), Family (the
+beneficiary), GM (placeholder operator), Broker (implicit).
+
+Output as bullet list under `## Actors`.
+
+#### Verb-goal pairs (use case candidates)
+
+Each `<actor> <verb> <object>` triple from extracted_text. These
+become use-case candidates that Cockburn's `/use-case` skill
+formalizes later (deferred).
+
+For the operator paragraph: "Operator surfaces deals", "Operator
+filters by location", "GM is installed in business", "Family receives
+cashflow".
+
+Output as bullet list under `## Verb-goal pairs`.
+
+#### BCE matrix (Jacobson classification)
+
+For each identified noun in the extracted_text, classify per
+Jacobson:
+
+- **Boundary**: UI surface / form / API endpoint — what the actor sees
+- **Control**: workflow orchestration — what coordinates the actors
+- **Entity**: persistent domain state — the noun's data shape
+
+Output as a 3-column markdown table under `## BCE matrix`.
+
+For the operator paragraph: most identified nouns are Entity (Deal,
+Business, Owner). Boundary objects emerge during /stage (formerly /preview)'s variant
+generation (search bar, filter pills, deal card). Control objects
+emerge during /decompose later (DealRanker, FamilyFitScorer).
+
+### 3. Write decomposition
+
+Output: `docs/decompositions/<slug>-domain.md`
+
+Slug derivation: `<input-artifact-slug>` (from the InputArtifact's
+`id` field). Example: InputArtifact at
+`docs/input-artifacts/2026-04-27-your-app-rework.json` → output
+`docs/decompositions/2026-04-27-your-app-rework-domain.md`.
+
+**Shape B frontmatter** (schema-validated by state-validate.sh):
+
+```yaml
+---
+slug: <input-artifact-slug>-domain
+type: domain-decomposition
+input_artifact: <input-artifact-slug>
+created_at: <ISO timestamp>
+references:
+  - {type: input-artifact, id: <input-artifact-slug>}
+entity_count: <integer>
+actor_count: <integer>
+phase: jacobson  # marks Phase B MVP scope; cockburn is follow-up
+---
+```
+
+**Body sections** (markdown, operator-readable narrative):
+- `## Entities` (bullet list)
+- `## Actors` (bullet list)
+- `## Verb-goal pairs` (bullet list)
+- `## BCE matrix` (3-column table)
+- `## Notes` (any extraction caveats; stub-mode warnings; ambiguity flags)
+
+### 4. Validate output
+
+After writing, the state-validate.sh hook validates the frontmatter
+against `decomposition.schema.json`. If invalid, the write BLOCKs;
+fix frontmatter and retry.
+
+Or invoke explicitly:
+
+```bash
+bash scripts/state.sh validate docs/decompositions/<slug>-domain.md
+```
+
+Exit 0 = clean; exit 3 = schema violation (BLOCK message names the
+field).
+
+### 5. Surface to next step
+
+`/stage` workflow (WU-9) consumes the decomposition. Standalone
+operator can read the markdown directly. Either way, this skill
+returns the path to the decomposition file as its primary output.
+
+## Phase B MVP scope (what this skips)
+
+Per the goal's WU-7 amendment ("compressed"):
+
+| Element | Phase B (this skill) | Follow-up bet |
+|---|---|---|
+| Entity inventory | ✅ | (already done) |
+| Actor list | ✅ | (already done) |
+| Verb-goal pairs | ✅ | (already done) |
+| BCE matrix | ✅ | (already done) |
+| Cockburn use-case skeletons (precondition / main scenario / extensions / postcondition) | ❌ deferred | `/use-case` skill ships separately; consumes verb-goal pairs |
+| GRASP responsibility assignment | ❌ deferred | `/decompose` skill (Larman, design-time) — runs after this in the chain |
+| Domain model diagrams (entity-relationship) | ❌ deferred | Follow-up; mermaid renderer skill |
+
+The skill produces the load-bearing structure (entities + actors +
+verb-goals + BCE) so downstream variant generation has real domain
+language to work with. Cockburn formalization is an exercise in
+TIGHTENING what's here, not adding new content — defer until needed.
+
+## Rules
+
+- **InputArtifact path is the only input** — never accept raw text
+  as an arg. Per parent goal's amendment, raw input is upstream's
+  concern; this skill consumes the normalized payload.
+- **Schema validates frontmatter** — body is operator narrative;
+  state-validate.sh hook enforces frontmatter shape at write time.
+- **No fabrication** — if `extracted_text` is sparse (or stub),
+  produce empty inventories and note the limitation. Don't invent
+  entities not present in the input.
+- **References are typed** — `references: [{type, id}]` per spine
+  contract; raw paths or freeform strings are forbidden.
+
+## Skipping / Aborting
+
+- Missing InputArtifact: error with exit 1 (not found per accessor
+  return semantics)
+- Stub-mode InputArtifact: produce minimal decomposition, surface
+  warning, exit 0 (downstream consumers handle empty inventories)
+- Schema validation failure on write: BLOCKed by state-validate.sh;
+  surface BLOCK to operator
+- Existing decomposition for same slug: error; operator must
+  delete or re-slug
+
+## Reserved-names check
+
+`objectory-decompose` is NOT on `standards/reserved-skill-names.md`
+list. Verified during WU-7 goal shape and at branch creation time.
+
+## Relationship to other skills + standards
+
+- `standards/input-handler-interface.md` — defines what InputArtifact
+  this skill consumes
+- `standards/state-spine/schemas/decomposition.schema.json` — validates
+  output frontmatter
+- `.claude/skills/interpret-input/SKILL.md` — upstream producer
+- `.claude/skills/use-case/SKILL.md` — Cockburn formalization (consumes
+  verb-goal pairs from this skill's output; separate, deferred)
+- `.claude/skills/decompose/SKILL.md` — Larman/GRASP (design-time
+  responsibility assignment; runs after this skill in the chain)
+- `.claude/skills/preview/SKILL.md` — workflow that orchestrates the
+  full chain
+- `.claude/luminaries/jacobson.md` (if exists) — methodology source
+
+## Enforcement
+
+Methodology-level. State-validate.sh hook enforces output schema.
+Reserved-names check passes. No additional hook enforcement added.
+
+## 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/pick-luminaries/SKILL.md

@@ -0,0 +1,100 @@
+---
+tier: lite
+name: pick-luminaries
+description: "Pick N luminaries whose lens fits an intent. Runs in-turn. Reads the catalog helper. Writes JSON output. Drives variants in /launch, /stage, and /riff-prototypes."
+problem: "Picking luminaries for a goal takes reading the whole catalog. Manual matching gets biased."
+value: "Picks N luminaries whose lens fits an intent. Runs in-turn. Writes JSON output."
+inputs: [Intent paragraph, Optional N count]
+outputs: [JSON list of picked luminaries with fit scores, Rationale per pick]
+user_invocable: true
+disable_model_invocation: false
+requires:
+  cli: [jq]
+authoring_luminaries:
+  primary: john-ousterhout
+  supporting: [alan-cooper, michael-feathers]
+---
+
+# /pick-luminaries — Match operator intent to the luminary catalog
+
+Runs inside the Claude Code turn. Reads the catalog helper. Picks N slugs. Writes the JSON output. No separate LLM call. No provider key required.
+
+Replaces the earlier picker that shelled out to an API. Adopters running the optional two-repo pattern can load their own `/extract-intent` skill. That skill overrides this one. Bassclef core stays oblivious to the override.
+
+## When to invoke
+
+- Inside `/launch` Phase 3.5 — variants pre-grounded in matched luminaries
+- Inside `/stage` Phase 3.5 — same
+- Inside `/riff-prototypes` when invoked standalone
+- Standalone — operator wants a preview of the picks
+
+## Procedure
+
+### Step 1 — Source the catalog helper
+
+```bash
+source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+CATALOG=$(luminary_pick_catalog)
+```
+
+`CATALOG` holds one line per luminary. Format is `<slug> (<domain>) — <name>`. Sorted by slug.
+
+### Step 2 — Pick N slugs in-turn
+
+You (Claude, in this turn) read the intent above. You enumerate `$CATALOG`. You pick N slugs whose lens fits the intent best. Prefer diversity across design planes.
+
+`N` is the variant count from the caller. Default is 2 for standalone. `/launch` and `/stage` pass 3.
+
+### Step 3 — Write the JSON output
+
+Write to the output path (default `/tmp/luminary-pick.json`):
+
+```json
+{
+  "matched_luminaries": ["slug1", "slug2", "slug3"],
+  "rationale": "One short sentence per pick",
+  "picker_version": "bassclef-harness-pick-2.0",
+  "provider": "claude-code-harness"
+}
+```
+
+Every slug in `matched_luminaries` must appear in `$CATALOG`. The rationale carries one sentence per pick.
+
+### Output
+
+Writes JSON to the output path. Downstream caller reads the JSON. Matched slugs drive variant generation.
+
+## What this skill is NOT
+
+- Not an embedding model. Claude reads the catalog inline.
+- Not a vendor adapter. No provider key required.
+- Not a substitute for `/extract-intent`. That layer adds richer signal when loaded.
+
+## Composes with
+
+- `lib/luminary-pick.sh` — provides `luminary_pick_catalog()`
+- `/launch` Phase 3.5 — primary consumer
+- `/stage` Phase 3.5 — primary consumer
+- `/riff-prototypes` — standalone consumer
+- `/luminary recommend` — signal-scoring alternative
+
+## Distinct from
+
+- `/luminary recommend` — signal scoring by keyword and design plane
+- `/extract-intent` — operator-private upgrade layer
+
+## Sources read
+
+- `state/luminary-implementations/*.json` — catalog manifest
+- `docs/iteration-bets/2026-09-03a-web-193-picker-harness-llm.md` — Option-A parent goal
+- `docs/decompositions/2026-09-03-picker-harness-llm.md` — GRASP + Interface Registry
+- bassclef#944 — Voyage matcher excision
+- bassclef-web#193 — audit that drove the Option-A rewrite
+
+## Closes
+
+Option-A caller update per sunj-labs/bassclef-web#193.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.