@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/skills/diagnose/SKILL.md

@@ -0,0 +1,297 @@
+---
+tier: lite
+name: diagnose
+description: "Diagnose a defect before fixing. Reproduce the failure first (Step 0), then Is/Is Not, then Five Whys, then a Hypothesis. Run before writing any fix code. Lazy diagnosis ships brittle fixes."
+problem: "Bugs get fixed on guesses. The wrong cause gets patched. The class comes back a week later."
+value: "A short trace from failure to root cause. You fix the class once instead of the instance three times."
+inputs: [A failing test or error log, A bug ticket or screenshot]
+outputs: [Reproduce step, Is/Is Not table, Five Whys chain, Hypothesis with a read-only test]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /diagnose
+
+## What you get
+
+Structured defect diagnosis. Run `/diagnose` before writing any fix code. I walk you through 7 steps:
+
+- Step 0 — reproduce the failure (RED anchor)
+- Step 1 — gather evidence
+- Step 2 — Is/Is Not table
+- Step 3 — resolution chain across stack layers
+- Step 4 — Five Whys to root cause
+- Step 5 — hypothesis with a read-only test
+- Step 6 — significance check
+- Step 7 — gate marker, then the fix
+
+The output separates "I fixed it" from a real cure. Without a repro, "I fixed it" has no counterpart. The repro is the surface every next step operates on.
+
+Every diagnosis writes a marker at `state/markers/diagnose/<branch>.marker`. The pre-build-gate hook reads it. Lazy diagnosis ships weak fixes.
+
+## When to use it
+
+Any time something is wrong, broken, failing, or behaving unexpectedly. Trigger words:
+
+- **Defects**: bug, defect, regression, flaky, intermittent
+- **Failures**: error, fail, crash, panic, exception, abort, SIGKILL, OOM
+- **State**: broken, wrong, corrupt, stale, stuck, hung, hanging, frozen, deadlock
+- **HTTP**: 404, 500, 502, 503, 504, redirect loop, CORS
+- **Performance**: timeout, timed out, slow, degraded, memory leak, high CPU
+- **Availability**: down, dead, unreachable, not responding, connection refused
+- **Behavior**: not working, does not work, will not start, stopped working, blank page, spinner
+- **Data semantic renames** (bassclef#601): before renaming a label / column / enum / UI copy that reflects data, verify the data semantic matches the new name
+
+Skip diagnosis only for the three trivial cases in the FAQ — typo, missing env var, off-by-one. Everything else earns the ceremony.
+
+## FAQ
+
+### Why is Step 0 (Reproduce) load-bearing?
+
+Without a repro, "I fixed it" has no counterpart "here's the thing it does not do anymore." The repro is the surface every subsequent step operates on. Step 0 writes a Reproduction block with the exact command / URL / action that triggers the failure, observed vs expected, environment, and reproducibility (every time / intermittent / unable).
+
+If you cannot reproduce, STOP. You may not be looking at a real defect — you may be looking at operator expectation mismatch, environment drift, or stale cache. Escalate before continuing.
+
+### When can I skip Step 0?
+
+Three localized cases: typo (obvious misspelling visible in diff), missing env var (error message names the var), off-by-one (index / boundary, one-character fix). In these cases the repro is implicit in the code change itself. State "Step 0 skipped — [reason]" in your output. Silence is not skip.
+
+For all other failures, Step 0 is mandatory.
+
+### What's the Step 0 identifier check?
+
+Before naming any external identifier in the Reproduction block — hook filename, npm scope, ticket ID, GitHub org, file path, ADR number — verify the identifier resolves against reality. Hook filenames: `find .claude/hooks -name "<name>.sh"` returns non-empty. Ticket IDs: `gh issue view <N>` returns a title. File paths: `test -f <path>`. ADR numbers: `ls architecture/decisions/ADR-<NNN>-*.md`.
+
+Bet 2026-07-04b caught three R8 misses in one session — invented hook name, invented npm scope, invented Chain B shape. All three came from authoring text against a mental model without a read against reality. Tier 0 tests used the invented names as fixture data — self-referential pass. Reading the source once at Step 0 falsifies the class before the ticket ships.
+
+Sister to `.claude/rules/assert-only-after-verify.md`.
+
+### What's the Resolution Chain step?
+
+If the defect involves behavior that could be produced at multiple layers of a stack, draw the resolution chain BEFORE forming hypotheses. This is the spatial complement to Five Whys (which traces causation over time).
+
+Pre-configured chains cover CSS / Layout / Scroll, Auth / Middleware, State Management (React), Config / Environment, Database / ORM, Network / API, Build Pipeline, Module / Import Resolution, Cross-Repo CI Write-Path. Pick the domain chain that matches your defect. Details below the fold.
+
+### What's the significance check?
+
+Before fixing, classify the finding — trivial (< 30 min + no new objects + no UI change), moderate, or significant. Trivial goes straight to fix with a note in the commit message. Moderate or significant requires a GitHub issue BEFORE writing fix code, so the scope is tracked.
+
+### When do I run /promote after diagnosis?
+
+If the diagnosis reveals a reusable pattern (new resolution chain, diagnostic technique, anti-pattern, trap) that would help in a different repo, run `/promote` with the pattern. Agents don't self-recognize promotable patterns; the pre-commit hook catches file-level changes to `.claude/` but not workflow insights. Step 7 is the self-catch mechanism.
+
+Skip promotion for trivial fixes.
+
+## Details below the fold
+
+### Procedure
+
+**Step 0 — Reproduce (RED anchor).**
+
+```
+## Reproduction
+- Repro command / URL / action: [exact sequence]
+- Observed: [what happens — exact error, status, behavior]
+- Expected: [what should happen]
+- Environment: [local / staging / prod / CI]
+- Reproducible?: [every time | intermittent N/M | unable to reproduce]
+```
+
+Then run the Step 0 identifier check (see FAQ) on every external name in the block.
+
+**Step 1 — Gather evidence (READ-ONLY — no code changes).**
+
+- `git log --oneline -10` — what changed recently?
+- Check logs (application, worker, CI output)
+- Check health endpoints
+- Check browser console errors (ask user for screenshot if needed)
+
+**Step 2 — Is / Is Not.**
+
+```
+## Is / Is Not
+- IS: [what fails — URLs, status codes, error messages]
+- IS NOT: [what still works — narrow the impact]
+- Changed: [recent commits, deploys, config, external services]
+```
+
+**Step 2b — Resolution Chain.**
+
+Pick the pre-configured chain for your domain. For each layer:
+
+- What does this layer contribute? (transform, filter, override, wrap, proxy)
+- Does it have hidden side effects? (implicit defaults, wrapper elements, middleware)
+- Can it silently override downstream layers? (specificity, precedence, config cascade)
+- Is a library or framework adding a layer you did not write? (READ THE SOURCE)
+
+Then identify which layer produces the observed behavior, which SHOULD control it, and whether any intermediate layers silently override or wrap.
+
+Skip Resolution Chain if the defect is single-file, obviously a typo / env var / off-by-one, or Is/Is Not already narrows to one layer.
+
+**Step 3 — Five Whys.**
+
+```
+## Five Whys
+1. Why does [symptom]? → because [X]
+2. Why [X]? → because [Y]
+3. Why [Y]? → because [Z]
+4. Why [Z]? → because [W]
+5. Why [W]? → ROOT CAUSE: [...]
+```
+
+**Step 4 — Hypothesis + Test.**
+
+```
+## Hypothesis
+- Cause: [your theory]
+- Test: [a read-only command to verify — NOT a fix]
+- If confirmed: [what you'll change]
+```
+
+**Step 5 — Significance check.**
+
+```
+## Significance
+- Level: [trivial / moderate / significant]
+- Criteria: [< 30 min + no new objects + no UI change = trivial]
+- UI surface impacted?: [yes/no — if yes, UX translation may be needed]
+- Epic required?: [trivial = no (log in commit), moderate+ = yes]
+```
+
+Moderate or significant → create a GitHub issue BEFORE writing fix code. Trivial → proceed to fix with commit-message note.
+
+**Step 6 — Write the gate marker, then fix.**
+
+```bash
+BRANCH=$(git branch --show-current)
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+BRANCH_HASH=$(echo "$BRANCH" | md5 -q 2>/dev/null || echo "$BRANCH" | md5sum 2>/dev/null | cut -d' ' -f1)
+SESSION_ID=${CLAUDE_SESSION_ID:-$$}
+
+# Ephemeral flag
+touch "/tmp/claude-diagnosis-done-${SESSION_ID}-${BRANCH_HASH}"
+
+# Durable git-tracked marker
+mkdir -p state/markers/diagnose
+date -u +%Y-%m-%dT%H:%M:%SZ > "state/markers/diagnose/${BRANCH_SLUG}.marker"
+git add "state/markers/diagnose/${BRANCH_SLUG}.marker"
+```
+
+Only NOW may you write code. The fix should address the ROOT CAUSE, not the symptom.
+
+**Step 7 — Pattern promotion check.**
+
+After the fix is confirmed working:
+
+- Did this diagnosis reveal a reusable pattern (new resolution chain, diagnostic technique, anti-pattern, or trap)?
+- Would this help in a DIFFERENT repo?
+- If yes → run `/promote` with the pattern, not just the fix.
+
+Skip if the fix was trivial.
+
+### Pre-configured resolution chains by domain
+
+**CSS / Layout / Scroll**
+```
+viewport → html → body → layout container → scroll container → target element
+```
+Per ancestor check: overflow-x / overflow-y, position, display (flex child missing min-w-0?), creates new scroll context?, creates new stacking context?, component library adding hidden wrapper divs? (READ THE SOURCE).
+
+Traps: shadcn/Radix wrapping in scroll containers, w-full overriding explicit width, border-collapse clipping box-shadow (Chrome), overflow:clip breaking sticky on iOS, flex children expanding past viewport.
+
+**Auth / Middleware**
+```
+client → proxy/CDN → edge middleware → route middleware → route handler → DB policy → response
+```
+Per layer check: short-circuit? (redirect, 401), modify the request? (headers, cookies), cache auth state? (stale session, revoked token still cached), which layer enforces tenant isolation?
+
+Traps: Next.js middleware running before route handlers, cached sessions surviving token revocation, middleware redirect loops, tenant context resolved at wrong layer.
+
+**State Management (React)**
+```
+server state → cache (React Query/SWR) → global store → context → component state → derived → render
+```
+Per layer check: is this layer stale?, are multiple layers holding copies?, does a re-render trigger here?, is the update path sync or async?
+
+Traps: optimistic UI not rolling back on server error, stale cache surviving a mutation, context re-rendering all consumers, derived state computed from stale inputs.
+
+**Config / Environment**
+```
+hardcoded default → config file → .env → env var → CLI flag → runtime override → framework injection
+```
+Per layer check: is this layer actually being read? (wrong .env, NODE_ENV mismatch), does higher-precedence layer silently override? (framework defaults), is the value being coerced? (string "false" → truthy in JS).
+
+Traps: Next.js/Prisma adding defaults, .env.local overriding .env, Docker not passing env vars, string coercion of booleans.
+
+**Database / ORM**
+```
+application code → ORM query builder → connection pool → DB engine → query planner → indexes → storage
+```
+Per layer check: is the ORM generating the expected SQL? (log the query), is the connection pool exhausted?, is the query planner using the expected index? (EXPLAIN), is there a transaction holding a lock?
+
+Traps: Prisma implicit select (fetching all columns), N+1 queries from relations, connection pool exhaustion from unclosed transactions, migration applied locally but not in prod.
+
+**Network / API**
+```
+client → DNS → CDN/proxy → load balancer → origin server → upstream API → response
+```
+Per layer check: is the request reaching the origin? (CDN cache, proxy rewrite), is the response being modified? (CORS headers stripped), is there a timeout at this layer? (LB timeout < API response time), is TLS terminating at the right layer?
+
+Traps: CDN caching stale responses, proxy rewriting headers, CORS preflight failing at CDN layer, WebSocket connections killed by LB timeout, DNS caching a dead IP.
+
+**Build Pipeline**
+```
+source → preprocessor → TypeScript compiler → bundler → tree-shaking → minifier → output
+```
+Per layer check: is the source file included in the compilation? (tsconfig includes), is tree-shaking removing code with side effects?, is the bundler resolving the expected module? (duplicate packages), is minification mangling names that are reflected on?
+
+Traps: barrel file re-exports defeating tree-shaking, tsconfig paths not matching bundler aliases, package duplicated at different versions in node_modules, CSS modules hashed differently in dev vs prod.
+
+**Module / Import Resolution**
+```
+import statement → tsconfig paths → bundler alias → node_modules → package.json exports → actual file
+```
+Per layer check: is tsconfig path mapping matching? (baseUrl, paths), is the bundler using different resolution than tsc?, is the package re-exporting from a different version?, are there multiple copies of the same package?
+
+Traps: path alias in tsconfig not matching webpack/vite, package using "exports" field that blocks deep imports, monorepo hoisting creating duplicate React instances.
+
+**Cross-Repo CI Write-Path (GitHub Actions / shared substrate distribution)**
+```
+source repo push → Actions trigger → workflow runner → checkout source → cross-repo action → target repo
+```
+Per layer check: is the workflow trigger firing? (event type, branch filter — check Actions tab), did the runner allocate?, is the cross-repo credential still valid? (PAT expired, GitHub App installation removed), does the credential carry the required target scope?, is the target repo accepting the write? (branch protection, Actions disabled), is the action library on a compatible version?
+
+Traps: PAT silently expires without CI failure signal (step reports "success" but opened zero PRs); fine-grained PAT scope reduced after creation; GitHub App installation removed from ONE target while others still work (silent matrix partial-fail); peter-evans/create-pull-request returning no-op when target branch already exists; target repo added branch protection after PAT creation; cross-repo rate limits; `add-paths:` filter silently excluding the intended file; `delete-branch: true` racing with a fresh open; auto-merge stalled waiting on required checks that never ran because Actions was disabled at target.
+
+Specific to bassclef substrate distribution: if `BASSCLEF_CONSUMER_WRITE_TOKEN` fails, the publish half (S3 upload) still succeeds because it uses different credentials — the pipeline is half-broken, surfaces only when consumers sync and hit a stale pin. Origin: bassclef#222, 2026-04-20.
+
+### Anti-patterns
+
+- Guessing-and-retrying with different parameters
+- Silently working around an error instead of understanding it
+- Fixing the symptom without tracing to root cause
+- Skipping diagnosis because "it's obvious" — it's usually not
+- Fixing at one layer without mapping the full resolution chain — each fix addresses the wrong layer, creating a whack-a-mole pattern that compounds over multiple commits. Origin: POA sticky columns — 16 commits because each attempt fixed one CSS layer without seeing the full containment chain.
+- Assuming the layer you wrote is the only layer involved. Libraries and frameworks routinely add intermediate layers (wrapper divs, middleware, config defaults) that silently override your code. READ THE SOURCE.
+
+### Output discipline
+
+Per bassclef#790 (operator-facing-prose discipline): /diagnose output (Step 0 repro, Is/Is Not table, Five Whys, Hypothesis, Resolution Chain) surfaces shorthand (WU-N, F-X.Y, ADR-NNN, #NNN, LF-N) with a plain-language gloss at first mention per response. See `standards/operator-facing-prose-discipline.md` for format examples.
+
+Per bassclef#790 Rule 2: any /diagnose SKILL.md edit applies a /kiss pass to the whole file in the same change.
+
+### Refs
+
+- `.claude/rules/assert-only-after-verify.md` — Step 0 identifier check sister discipline
+- `.claude/rules/blocked-items.md` — substrate-defect promotion mandatory trigger
+- `.claude/rules/stuck-signal-diagnostic.md` — stuck-counter path that surfaces substrate defects
+- `.claude/hooks/pre-build-gate.sh` — reads the diagnose marker on fix/ branches
+- `.claude/skills/promote/SKILL.md` — pattern promotion downstream skill
+- bet 2026-07-04b — R8 identifier-check parent
+- bet 2026-07-04c WU-4 — Step 0 identifier check shipped
+- bassclef#601 — data semantic rename trigger
+- bassclef#790 — operator-facing-prose discipline
+
+## 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/feynman/SKILL.md

@@ -0,0 +1,90 @@
+---
+tier: lite
+name: feynman
+description: "Explain a technical concept in plain English \u2014 Feynman style. For CTO-vettable sidebars in journal entries or standalone micro-posts."
+problem: "Technical concepts get explained with jargon. Non-technical readers stop reading."
+value: "Explains a technical concept in plain English \u2014 Feynman style. For CTO-vettable sidebars in journal entries."
+inputs: [A concept name or paragraph text]
+outputs: [Feynman-style explanation, Analogy anchors, Grade-8 prose]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Feynman — Plain-English Technical Explanation
+
+Explain a technical concept so that:
+- A PE operating partner understands why it matters economically
+- A CTO confirms it's technically precise
+- A board member can repeat the core idea in their own words
+
+Named after Richard Feynman's principle: if you can't explain it simply,
+you don't understand it well enough.
+
+## When to use
+
+- Flagged by /journal as `[FEYNMAN: concept]`
+- User asks "explain X simply" or "feynman this"
+- A post references a technical concept that needs unpacking for
+  non-technical senior leaders while remaining CTO-credible
+
+## Method
+
+### Step 1: State what it does in one sentence
+
+No jargon. No analogies yet. Just the function.
+
+"Temperance is a mandatory pause that forces the system to justify
+its approach before executing."
+
+### Step 2: Explain why it exists — the failure it prevents
+
+Connect to a real failure mode that the audience recognizes.
+
+"It exists because autonomous systems optimize for throughput. Without
+a pause, the system will retry failed approaches faster rather than
+understanding why they failed — the same pattern that causes large
+engineering organizations to ship broken features faster instead of
+fixing the root cause."
+
+### Step 3: Give the analogy (optional — only if it clarifies)
+
+Pick an analogy from the audience's world:
+
+- PE: "It's the investment committee memo before deploying capital"
+- Enterprise: "It's the pre-flight checklist — not bureaucracy, but
+  the minimum discipline that prevents expensive mistakes"
+- Board: "It's the governance gate between strategy approval and execution"
+
+### Step 4: State the technical precision (for the CTO)
+
+One sentence that a technical reviewer would nod at.
+
+"Implemented as a pre-execution checklist that evaluates five dimensions:
+simplicity, blast radius, verification cost, reversibility, and whether
+the system is treating symptoms or root causes."
+
+## Output format
+
+```markdown
+### [Concept Name]
+
+**What it does**: [one sentence, no jargon]
+
+**Why it exists**: [the failure it prevents, in operating terms]
+
+**Analogy**: [from the audience's world — PE, enterprise, or board]
+
+**Technical precision**: [one sentence a CTO would verify]
+```
+
+## Rules
+
+- Never more than 4 sentences total for the core explanation
+- The analogy must come from enterprise/PE/board — not academia, not startups
+- If the concept doesn't need all 4 parts, drop the analogy
+- The explanation must be accurate enough that a CTO wouldn't correct it
+- Avoid "it's like..." phrasing — state what it IS, then use analogy only to illuminate
+
+## 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/howdoi/SKILL.md

@@ -0,0 +1,105 @@
+---
+tier: lite
+name: howdoi
+description: "Search bassclef skills and rules for an adopter goal \u2014 LLM-assisted. Two modes \u2014 search (top matches) and compose (matches plus suggested chains). Ranks by semantic fit and cites what each match does."
+problem: "Adopters know what they want to do but not which bassclef skill or rule fits."
+value: "One question in. A short list of the skills and rules that match your goal."
+inputs: [A one-sentence goal in plain English]
+outputs: [Ranked list of matching skills and rules, One-line reason per match]
+user_invocable: true
+disable_model_invocation: false
+modes: [search, compose]
+composes_baseline: [ash-maurya, alan-cooper]
+---
+
+# /howdoi
+
+## What you get
+
+Ask "how do I add auth?" or "how do I test my API?" or "which skill drafts a value prop?". I grep bassclef's skills, rules, and standards for your keywords, use Claude to rank the top 3 matches, and explain what each returns and why it matches. In `compose` mode, I also suggest 1-3 skill chains when your goal spans multiple skills.
+
+Modeled on the Python `howdoi` CLI (github.com/gleitz/howdoi) which searches Stack Overflow from the terminal — same shape, adapted to bassclef.
+
+## When to use it
+
+Any time you know what you want but have not identified the skill yet. New adopters use it for signup-time questions ("how do I add auth?"). Returning adopters use it to recall a skill name ("which skill drafts a value prop again?"). Mid-flow, run it when you finish one skill and need to pick the next ("I just ran /decompose — what's next?").
+
+Skip it when the intent is obvious. If you already know the skill name, run the skill directly. `/howdoi` earns its cost on ambiguous intents.
+
+## FAQ
+
+### What's the difference between search and compose?
+
+`search` (default) returns the top 3 matches with a one-line explanation of what each does. `compose` returns the same top 3 plus 1-3 suggested chains when the goal spans multiple skills. Use `search` when you want a single skill; use `compose` when you're planning a workflow.
+
+### How does the ranking work?
+
+Two stages. Stage 1 greps `.claude/skills/*/SKILL.md`, `.claude/rules/*.md`, and `standards/*.md` for keywords Claude extracts from your intent (3-5 keywords). Grep returns up to 20 candidates. Stage 2 asks Claude to score each candidate 0-10 for semantic fit against your intent. Top 3 come back with a one-line why-it-matched.
+
+Grep is the fast filter; Claude is the semantic ranker.
+
+### What if the top match is wrong?
+
+Read the top 3, not just #1. Each match carries a one-line what-it-does + why-it-matched. If none fit, rerun `/howdoi` with a different intent phrasing — the ranking is sensitive to how you frame the goal.
+
+If you keep missing, file a ticket. The gap probably means either a skill description is too vague or a skill does not yet exist for the goal.
+
+### Does compose mode always suggest chains?
+
+No. Compose mode asks Claude "does this intent span multiple skills?" and returns chains only if the answer is yes. Single-skill goals return just the top 3 matches, same shape as search mode.
+
+### Can /howdoi call other skills for me?
+
+No. `/howdoi` surfaces matches; you decide what to run. The value is discovery, not dispatch.
+
+## Details below the fold
+
+### Procedure
+
+1. Ask for the intent — one sentence or a paragraph.
+2. Claude extracts 3-5 keywords (auth, schema, test, deploy, etc.).
+3. Grep runs across `.claude/skills/*/SKILL.md`, `.claude/rules/*.md`, `standards/*.md`. Up to 20 candidates.
+4. Claude scores each candidate 0-10 for semantic fit. Returns top 3.
+5. Format output — match name, path, one-line what-it-does, why-it-matched score.
+6. In `compose` mode only — Claude checks whether the intent spans multiple skills. If yes, propose 1-3 chains with rationale.
+
+### Output shape
+
+```markdown
+# /howdoi — matches for "<your intent>"
+
+## Top matches
+
+1. **`/skill-name`** (`.claude/skills/skill-name/`) — description. Match: N/10. Why: <why it matched>.
+2. ...
+3. ...
+
+## Suggested chains (compose mode only)
+
+**Chain A — <name>:**
+`/X` → `/Y` → `/Z`
+
+Rationale: <why this sequence fits the goal>.
+```
+
+### Anti-patterns this skill prevents
+
+- Adopter gives up on discovery — grep alone misses semantic matches ("add auth" will not grep-match `/security-review` reliably). INSTEAD: LLM rank surfaces the fit.
+- Wrong-skill invocation — adopter picks a skill that looks close but does something else. INSTEAD: top 3 with what-it-does explanations lets adopter pick with context.
+- Missing composition — adopter picks one skill when the goal needs a chain. INSTEAD: `compose` mode surfaces the chain shape.
+- Over-fitting to grep — grep is a fast filter, not the final answer. INSTEAD: LLM rank considers what each skill actually does.
+
+### Refs
+
+- Ticket #654 — this skill's filing (renamed from `/i-want-to` to `/howdoi` 2026-07-07)
+- Ticket #660 — CI/TDD nudge (split from this skill's original scope)
+- Bet 2026-07-07a — this skill's ship vehicle
+- Python `howdoi` CLI — github.com/gleitz/howdoi (naming precedent)
+- `.claude/rules/skill-composition-declarations.md` — the composability discipline this skill surfaces
+- `/skills` — browse-mode alternative to search
+- `.claude/luminaries/ash-maurya.md` — adopter voice framing
+- `.claude/luminaries/alan-cooper.md` — persona-goal anchor
+
+## 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/ia-model/SKILL.md

@@ -0,0 +1,108 @@
+---
+tier: lite
+name: ia-model
+description: "Build information architecture from an entity inventory plus task flows. Derives nav structure, labeling, and screen map from the domain nouns."
+problem: "Screens get designed before the nouns behind them are named. Nav drifts across pages."
+value: "One entity map that drives every downstream screen. Nav stays clean because the model is clean."
+inputs: [Task flows from spec, Entity inventory from decompose]
+outputs: [Entity model diagram, Navigation shape, Screen inventory]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Information Architecture — Entity-Driven
+
+Build the IA from entities and their relationships. For data-heavy operator tools,
+the IA is entity-driven — screens derive from objects, not content hierarchies.
+
+## When to Use
+
+- After `/jtbd-tasks` and `/task-scenarios` — you have task flows and stories
+- When navigation feels wrong or pages overlap in purpose
+- When adding a new entity (new database model, new concept)
+- When the user says "I don't know where to find X" or "these pages feel redundant"
+- UX fitness review flags drift (new entities without UI surface, nav doesn't match)
+
+## Method: Object-Oriented UX (OOUX)
+
+### Step 1: Entity Inventory
+
+List every object the system represents:
+
+| Entity | Attributes | Relationships | UI Surface |
+|--------|-----------|---------------|------------|
+| ... | ... | ... | /path |
+
+### Step 2: Entity Relationship Map
+
+Draw the relationships (Mermaid ERD or graph).
+
+### Step 3: Screen Derivation
+
+**Each primary entity gets a list view and a detail view.** Secondary entities appear within their parent's views. This is the core OOUX principle.
+
+| Entity | List View | Detail View | Appears In |
+|--------|-----------|-------------|------------|
+| ... | /path | /path/[id] | ... |
+
+### Step 4: Navigation Structure
+
+Derive nav from the screen map. Apply Peter Morville's IA framework:
+- **Organization**: How are screens grouped?
+- **Labeling**: What do we call each nav item? Match the user's mental model.
+- **Navigation**: Primary nav (always visible) vs secondary (contextual).
+- **Search**: When is filtering better than browsing?
+
+### Step 5: Apply LATCH
+
+5 ways to organize information — pick the right one per context:
+- **L**ocation: geographic grouping
+- **A**lphabet: alphabetical (rarely useful)
+- **T**ime: chronological (recent first)
+- **C**ategory: by type or classification
+- **H**ierarchy: by importance or score
+
+## Output Format
+
+```markdown
+## Entity Inventory
+[table]
+
+## Entity Map
+[Mermaid diagram]
+
+## Screen Map
+[table: entity → list view, detail view, appears in]
+
+## Navigation Structure
+[primary nav, contextual nav, future nav]
+
+## LATCH Analysis
+[which organization scheme for which context]
+
+## Gap Analysis
+- Entities without UI surfaces
+- Screens without clear entity ownership
+- Nav items that don't map to entities or jobs
+```
+
+## Component Naming Convention
+
+UI components should be **named after domain objects**, not generic UI concepts:
+- `DealCard` not `Card`
+- `ScorePills` not `BadgeGroup`
+- `ThesisFilter` not `TabGroup`
+
+## Next Step
+
+Feeds into `/interaction-design` (state diagrams, sequence diagrams).
+
+## References
+
+- Sophia Prater, OOUX methodology (ooux.com)
+- Peter Morville & Louis Rosenfeld, *Information Architecture for the World Wide Web*
+- Abby Covert, *How to Make Sense of Any Mess*
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.