@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/skills/decompose/SKILL.md

@@ -0,0 +1,280 @@
+---
+tier: lite
+name: decompose
+description: Pre-build responsibility audit — reads sequence diagrams, assigns responsibilities using GRASP with mandatory interface identification, audits functional and non-functional friction, selects patterns from GoF / Fowler / stack idioms. Bridges design and build.
+problem: "Cross-cutting concerns bolt into implementations. Logging and tracing pile inside business code."
+value: "A responsibility matrix that keeps each concern in its own class. Decorators stay clean."
+inputs: [Sequence diagrams from spec, A decomposition target — feature or defect]
+outputs: [Responsibility matrix, Interface registry, Pattern map for construction]
+user_invocable: true
+disable_model_invocation: false
+composes_with: [spec, ia-model, interaction-design, pattern-review, temperance]
+---
+
+# /decompose
+
+## What you get
+
+A responsibility matrix + interface registry + pattern map for any non-trivial construction work. Three phases — GRASP responsibility assignment with mandatory interface names, coupling / variation / stability audit plus cross-cutting concerns (the -ilities), and pattern selection from GoF / Fowler / DDD / Clean Architecture vocabularies. The output answers "who handles what, through which interfaces, with what cross-cutting concerns" before the Builder writes a line of code.
+
+Key principle: GRASP is applied literally, not conceptually. Every Indirection and Protected Variation assignment MUST produce a named interface. Every cross-cutting concern (observability, testability, extensibility, security, cacheability) MUST be identified in the NFR check and resolved as a Decorator or Proxy wrapping an interface — never bolted inside an implementation.
+
+## When to use it
+
+- **Before any non-trivial build.** If the work touches 2+ layers (UI + API, API + DB, worker + queue), decompose first.
+- **After `/interaction-design`** produces sequence diagrams. Those diagrams are the primary input.
+- **When responsibility is ambiguous.** "Should this logic live in the API route or a service?" — decompose answers that structurally, not by gut feel.
+- **On any Construction branch** (`feature/`, `fix/`) creating changes to `src/` per `.claude/rules/oo-ad-entry-point.md`.
+
+Skip for single-file changes, config updates, docs, simple CRUD with obvious ownership, or pure refactors within one function.
+
+## ADR-consult — fire before scope confirmation (per bassclef-upstream#424)
+
+Read every relevant ADR in `architecture/decisions/` before confirming scope. If your scope deviates from any ADR's decision or constraints, surface the deviation as the first agenda item — the operator decides amend-ADR vs revise-scope.
+
+Per `.claude/rules/adr-discipline.md`. Mechanism: `adr-discipline-check.sh` fires on architectural edits (wired in `.claude/settings.json` since bet 28a WU-1).
+
+## FAQ
+
+### What are the three entry-point states?
+
+- **State 1 — Canvas/greenfield.** Full flow preceded (canvas → spec → ia-model → interaction-design → sequence diagrams). `/decompose` reads sequence diagrams as primary input. If `/use-case` produced fully-dressed cases at `docs/use-cases/UC-NNN-*.md`, those feed in parallel.
+- **State 2 — Epic/defect (no sequence diagrams, spec exists).** Reverse-engineer — read the spec, read current implementation, identify system events from ticket + code, treat current as "as-is" and ticket as "to-be." Phase 2 NFR check becomes especially critical.
+- **State 3 — Bug/hotfix (symptom known, cause unknown).** `/diagnose` already ran per SDLC gates. Read the diagnose output (Is/Is Not, Five Whys, Hypothesis), identify which responsibility is mis-assigned OR which cross-cutting concern is missing (the bug is often a missing interface / decorator, not a logic error). Phase 1 is targeted.
+
+### Why must every Indirection or Protected Variation produce a named interface?
+
+Because "Indirection: adapter wraps provider" without naming `IProviderAdapter` has not completed the decomposition. The interface IS the artifact, not the principle citation. Bet 2026-07-04 experience — the POA session bolted Langfuse tracing inside HaikuImputer because the earlier decomposition named "Indirection" without producing `IAssociationImputer`. Interface name forces the concrete artifact.
+
+### What are the -ilities?
+
+Five cross-cutting concerns Phase 2 audits — observability, testability, extensibility, security, cacheability. Each maps to a Decorator or Proxy wrapping an interface. Missing any -ility from the audit is the same failure mode as skipping tests. If an -ility applies to a responsibility, it MUST appear as its own row with a named interface or wrapper.
+
+### When does a luminary lens influence pattern choice?
+
+Phase 1 (Responsibility Matrix) and Phase 2 (Friction Points + NFR) are luminary-agnostic — they are structural facts about the domain. Phase 3 is the first phase where a luminary POV legitimately influences pattern choice among valid options. A luminary cannot override GRASP or NFR gates; the luminary shapes pattern choice among valid options only.
+
+If the iteration goal declares multiple `primary_luminaries`, each pattern choice in Phase 3 cites which luminary drove it. All-one-name attribution when the goal lists multiple luminaries is the collapse-to-single failure.
+
+### What's the output artifact?
+
+A single Decomposition Summary at `docs/decompositions/[feature-name].md` containing the three-phase output plus an Interface Registry (the primary Builder handoff artifact) plus proposed file structure plus decisions.
+
+The Interface Registry answers "what interfaces do I need to implement?" before any code lands.
+
+### How does /decompose compose with /temperance and /pattern-review?
+
+`/temperance` fires BEFORE `/decompose`. Temperance asks "should we build this?" Decompose asks "how should we structure it?" — different questions, different answers.
+
+`/pattern-review` fires DURING or AFTER build. Decompose selects patterns before code lands; pattern-review validates they were applied per the decomposition.
+
+## Details below the fold
+
+### Position in the chain
+
+```
+/interaction-design (sequence diagrams, state diagrams)
+        ↓
+/decompose (responsibility audit → pattern map)
+        ↓
+Builder implements against the decomposition
+        ↓
+/pattern-review (validates patterns during/after build)
+```
+
+### Phase 1 — Responsibility Matrix (GRASP)
+
+For each system event in the sequence diagrams, assign responsibility using Larman's GRASP principles:
+
+| Principle | Question it answers | Stack translation |
+|---|---|---|
+| **Information Expert** | Who has the data needed to do this? | Prisma model → repository / service. React component with local state → handler stays in component. |
+| **Creator** | Who should create this object? | API route creates via Prisma. Factory if creation varies by type. |
+| **Controller** | Entry point for this system event? | API route (server boundary) or server action. One controller per use case, not per entity. |
+| **Low Coupling** | Does A need to know B's internals? | If yes → introduce indirection (service layer, repository, adapter). |
+| **High Cohesion** | Is this module doing too many unrelated things? | If a route handles validation + business logic + DB + email → extract. |
+| **Pure Fabrication** | No natural home for this logic? | `lib/services/ScoringService.ts`, `lib/repositories/DealRepository.ts`. |
+| **Indirection** | Need to decouple two things? | Middleware, event bus, service layer between route and DB. |
+| **Protected Variations** | What changes? What stays stable? | Interface / adapter around unstable external APIs. Strategy for varying business rules. |
+
+Output — Responsibility Matrix:
+
+```markdown
+| System Event | Controller | Expert | Fabrications | Interfaces | GRASP Justification |
+|---|---|---|---|---|---|
+| User submits deal | `POST /api/deals` | `Deal` (Prisma) | `DealRepository` | `IDealRepository` | Expert: Deal model owns fields. Pure Fabrication: repository isolates query logic from route. |
+| Score recalculates | Server action | `ScoreConfig`, `Deal` | `ScoringService` | `IScoringStrategy` | Expert: ScoreConfig owns dimensions. Protected Variation: scoring rules vary. |
+```
+
+Rules:
+
+- Every row cites at least one GRASP principle.
+- Interfaces column is mandatory. Every Indirection / Protected Variation names its interface.
+- If you cannot name the Expert, the entity model is incomplete — go back to `/ia-model`.
+- If a Controller handles 3+ responsibilities, split it.
+- Names in the matrix match the ubiquitous language of the domain (Evans DDD) — not database schema.
+- Each fabrication is a deep module (Ousterhout) — small interface, complex implementation hidden. A Service passing calls through to a Repository is two shallow modules pretending to be one deep.
+
+### Phase 2 — Coupling, Variation, NFR Audit
+
+Review the Responsibility Matrix. For each row, run four checks:
+
+1. **Coupling check.** Does the Controller reach into the Expert's internals? If yes → introduce a Repository or Service.
+2. **Variation check.** Does behavior vary by type / configuration / context? If yes → Protected Variation.
+3. **Stability check.** Does this touch an external API that could change? If yes → Adapter.
+4. **NFR check** (the -ilities):
+
+| -ility | Question | What it catches |
+|---|---|---|
+| **Observability** | Who traces this? Records latency / cost / input / output? | Missing Decorator — the Langfuse-inside-HaikuImputer mistake. Tracing bolted inside implementation instead of wrapping interface. |
+| **Testability** | Can I test this in isolation? What needs mocking? | Concrete dependencies without interfaces. Cannot swap implementation in a test. |
+| **Extensibility** | What's the next provider / strategy / channel? | Missing interface for Protected Variation. "Add SMS" means editing the email service. |
+| **Security** | Who authenticates / authorizes? Where is tenant context resolved? | Auth wired inside business logic instead of at the boundary. |
+| **Cacheability** | What's read-heavy and stable enough to cache? Where does invalidation live? | Cache logic mixed into business logic instead of isolated as Proxy / Decorator. |
+
+Rule: if an -ility concern applies to a responsibility, it MUST appear as its own row in Friction Points with a named interface or wrapper. "Add observability later" is the same failure as "add tests later."
+
+Output — Friction Points:
+
+```markdown
+| Location | Type | Risk | Resolution |
+|---|---|---|---|
+| `POST /api/deals` → Prisma query | Coupling | Route knows schema shape | Extract `DealRepository` |
+| Scoring dimensions | Variation | Rules vary per deal type | Strategy — `IScoringStrategy` |
+| Association imputation | Observability | Tracing lives inside HaikuImputer; swapping to Gemma loses traces | Decorator — `ObservedImputer(IAssociationImputer)` traces via Langfuse |
+| Association imputation | Testability | Cannot test imputation without LLM call | Interface — `IAssociationImputer` enables stub / mock |
+```
+
+### Phase 3 — Pattern Map
+
+Select concrete patterns from the vocabulary:
+
+**Functional patterns:**
+
+| Friction | Pattern sources |
+|---|---|
+| Variation by type | GoF: Strategy, State. React: polymorphic components, render props. |
+| Complex creation | GoF: Factory Method, Abstract Factory. Prisma: nested create, transaction. |
+| Unstable external API | GoF: Adapter. Next.js: route handler wrapping SDK. |
+| Complex orchestration | GoF: Facade. Next.js: server action composing services. |
+| Event propagation | GoF: Observer. Prisma: middleware hooks. Next.js: revalidation. |
+| Data access isolation | Fowler: Repository, Unit of Work. |
+| State complexity | GoF: State. React: useReducer, state machines (XState). |
+| Caching / memoization | React: useMemo, React.cache. Next.js: ISR, unstable_cache. |
+
+**Cross-cutting patterns (from NFR check):**
+
+| -ility | Pattern sources | Structural principle |
+|---|---|---|
+| Observability | GoF: Decorator, Observer. Langfuse: trace wrapper. OpenTelemetry: span instrumentation. | Decorator wraps the interface, not the implementation. Tracing MUST survive provider swap. |
+| Testability | Interface extraction → stub / mock. Fowler: Test Double. | Cannot swap implementation in a test = coupled to concrete class. |
+| Extensibility | GoF: Strategy, Abstract Factory. Plugin registries. | New provider = new class implementing existing interface. Zero edits to existing code. |
+| Security | Middleware chain. Next.js: middleware.ts. Fowler: Gateway. | Auth resolved at boundary, passed as context. Business logic never checks auth. |
+| Cacheability | GoF: Proxy. React: React.cache. Next.js: ISR. Redis wrapper. | Cache as Proxy / Decorator wrapping interface. Invalidation strategy declared, not bolted on. |
+
+Per @luminary gang-of-four: program to an interface, not an implementation; favor object composition over class inheritance. Cross-cutting concerns wrap interfaces via Decorator — they never live inside the concrete implementation.
+
+### Luminary lens on Phase 3
+
+Read the iteration goal's `primary_luminaries` field (list form) — treat scalar `primary_luminary` as single-element list for backward compat. For each entry, read `.claude/luminaries/[slug].md`.
+
+Multi-luminary handling: each luminary should have a `role` annotation. Phase 3 Pattern Map cites which luminary drove each pattern choice — no "applied the primary" language when 2+ luminaries active. Add an Attribution column to the pattern table.
+
+Stub-depth luminary — emit BLOCKED (per `.claude/rules/blocked-items.md`) and either upgrade the luminary or explicitly defer.
+
+Common preferences:
+
+| Primary luminary | Pattern preferences |
+|---|---|
+| Sophia Prater | Componentized content, progressive disclosure, entity-derived nav; Strategy over Factory when behavior varies by entity type |
+| Don Norman | Explicit affordances, feedback wrappers, constraint-first validation; Decorator for feedback consistency |
+| Edward Tufte | Small-multiples for comparison, sparklines in tables; data-dense patterns over card-based |
+| Dieter Rams / Jony Ive | Minimal API surface on components, removal over addition; Facade to hide complexity |
+| Alan Cooper | Role-based UI variants, primary-persona-optimized Controllers; Strategy per persona-role |
+| @luminary alistair-cockburn | Walking Skeleton as first PR; Hexagonal Architecture with Ports & Adapters — business logic at center, adapters at outside |
+
+### Final Output — Decomposition Summary
+
+Combine all three phases into `docs/decompositions/[feature-name].md`:
+
+```markdown
+# Decomposition: [Feature Name]
+
+**Source**: [sequence diagram reference or entry-point state]
+**Date**: YYYY-MM-DD
+
+## Responsibility Matrix
+[Phase 1 table with Interfaces column]
+
+## Friction Points
+### Functional
+[Phase 2 coupling / variation / stability rows]
+### Non-Functional (-ilities)
+[Phase 2 NFR rows]
+
+## Pattern Map
+### Functional patterns
+[Phase 3 functional table]
+### Cross-cutting patterns
+[Phase 3 cross-cutting table]
+
+## Interface Registry
+| Interface | Purpose | Implementations (known) |
+|---|---|---|
+| `IAssociationImputer` | Abstract LLM provider | `HaikuImputer`, `GemmaImputer` (future) |
+
+## File Structure (proposed)
+src/
+  app/api/[route]/    ← Controllers
+  app/actions/        ← Facades (server actions)
+lib/
+  services/           ← Pure Fabrications
+  repositories/       ← Data access (Fowler Repository)
+  adapters/           ← External API wrappers
+  decorators/         ← Cross-cutting: Observed*, Cached*, Logged*
+  [domain]/
+    types.ts          ← Interface definitions (I* contracts)
+    strategies/       ← Strategy implementations
+
+## Decisions
+- [Why X is a service, not inline in the route]
+- [Why observability is a Decorator, not inline tracing]
+- [Why caching is a Proxy, not inline Redis calls]
+```
+
+### Anti-patterns
+
+- Decomposing trivial work
+- Forcing patterns when the friction table is empty (say "no friction — build directly")
+- Skipping Phase 1 and jumping to "use a Factory"
+- Decomposing without sequence diagrams (State 1) or without spec / current code (State 2)
+- Skipping the NFR check — cross-cutting concerns identified later become bolt-on hacks
+- Naming principles without interfaces — the interface IS the artifact
+- Cross-cutting logic inside implementations — tracing inside HaikuImputer, caching inside DealRepository, auth inside a route handler are all the same mistake
+
+### Composes with
+
+| Skill | Relationship |
+|---|---|
+| `/temperance` | Fires BEFORE. Should we build this at all? |
+| `/interaction-design` | Produces sequence diagrams `/decompose` consumes |
+| `/ia-model` | Produces entity model that informs Information Expert assignments |
+| `/pattern-review` | Validates patterns DURING or AFTER build. Decompose selects BEFORE. |
+| `/spec` | May contain sequence diagrams inline. Decompose reads from spec or standalone artifacts. |
+| `/use-case` | Fully-dressed cases feed Phase 1 in parallel with sequence diagrams |
+
+### Refs
+
+- Craig Larman, *Applying UML and Patterns* — GRASP patterns
+- @luminary gang-of-four — *Design Patterns* — 23 pattern vocabulary
+- @luminary martin-fowler — *Patterns of Enterprise Application Architecture* + *Refactoring* catalog
+- @luminary eric-evans — *Domain-Driven Design* — Ubiquitous Language + Bounded Contexts + Aggregates
+- @luminary alistair-cockburn — *Writing Effective Use Cases* + Hexagonal Architecture (Ports & Adapters)
+- @luminary robert-c-martin — *Clean Architecture* — SOLID + Dependency Rule
+- @luminary john-ousterhout — *A Philosophy of Software Design* — deep modules + comments-as-design
+- `.claude/rules/oo-ad-entry-point.md` — entry-point rule requiring `/decompose` evidence
+- `.claude/rules/adr-discipline.md` — ADR-consult before scope confirmation
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/diagnose/SKILL.md

@@ -0,0 +1,297 @@
+---
+tier: lite
+name: diagnose
+description: Diagnose a defect before fixing — reproduce the failure (Step 0) + Is/Is Not + Five Whys + 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.