@thebassclef/lite 1.0.3 → 1.1.0

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

@@ -0,0 +1,384 @@
+---
+tier: lite
+name: stage
+description: "Turn an idea into clickable mock variants on a deployed subdomain. Two sizes: quick (~30 min, 2 variants) and light (~2h, 3 variants plus an Anthropic baseline). Operator picks a direction from phone before committing to build work."
+problem: "A UI idea needs to be seen before it can be judged. Prose and wireframes lose the story."
+value: "Turns an idea into clickable mocks on a deployed subdomain. Operator taps through and picks."
+inputs: [A UI intent or design goal, Optional size — quick or light]
+outputs: [Deployed mock at a subdomain URL, Multiple variants to compare]
+user_invocable: true
+disable_model_invocation: false
+sizes: [quick, light]
+---
+
+# /stage (formerly /preview) — Prototype-Tier Workflow (Inception/Elaboration)
+
+End-to-end workflow for **prototype tiers** (quick + light). Takes
+operator input (text in Phase B; URL / image / repo / transcript /
+napkin in Phase C) and produces a PR containing deployed prototype
+variants + clickable comparison gallery (with back-navigation from
+each variant) + bind-subdomain wiring.
+
+After this skill + dependencies ship + merge, operator can dispatch
+a paragraph from phone to any consumer repo and
+`/stage quick "<paragraph>"` runs the chain end-to-end.
+
+**For Construction-input tiers (medium / full)**, use
+`.claude/skills/launch/SKILL.md`. The boundary is operator
+intent: `/stage` = "still picking direction"; `/launch` =
+"committing to ship this".
+
+## Phase boundary
+
+| Axis | `/stage` (this skill) | `/launch` (sibling) |
+|------|------------------------|---------------------------|
+| Phase | Inception / Elaboration | Construction transition |
+| Operator intent | "Pick a direction" | "Ship the chosen direction" |
+| Data substrate | Stubbed / hardcoded | Stubbed (variants) → real (post-build) |
+| Output | Variants for visual selection | Spec + GRASP + ux-migration + iteration-goal draft |
+| Cameo review | /visual-review with complement evaluators | Same + spec/decomp review |
+| Commitment level | None — variants are throwaway | Operator decides next: scaffold Construction or pivot |
+
+Quick + light produce visual artifacts only. Medium + full cross the
+prototype/production boundary by producing buildable specs (in
+`/launch`).
+
+## When to invoke
+
+- Operator dispatches new UX rework intent: `/stage quick "<paragraph>"`
+- Bake-off against existing surface: `/stage quick "<paragraph>" base=<existing-slug>`
+- Multi-variant exploration: `/stage quick "<paragraph>" variants=3`
+- Medium tier (Phase D follow-up): `/stage medium "<input>"` returns
+  "deferred to Phase D" stub in this MVP
+
+## What this skill is NOT
+
+| Skill | Altitude | Output |
+|-------|----------|--------|
+| `/stage` | **Pipeline** | PR with full chain output |
+| `/interpret-input` | Input normalization | InputArtifact (one step of preview) |
+| `/objectory-decompose` | Jacobson analysis | Decomposition (one step of preview) |
+| `/riff-prototypes` | Variant generation | Variants in docs/prototypes/ (one step) |
+| `/prototype-gallery` | Variant index page | Gallery scaffolding (one step) |
+| `/bind-subdomain` | Amplify deployment | Subdomain DNS + cert (one step) |
+
+`/stage` orchestrates these — it does NOT replace any of them. Each
+step's skill remains independently invocable for debugging or
+out-of-band work.
+
+## Hard constraints (per goal rules)
+
+- **MUST produce a PR**, never push directly to main (per
+  `.claude/rules/branching.md` + `.claude/rules/pr-strategy.md`)
+- **MUST run on a feature branch** — refuses to run from main
+- **MUST capture champion-challenger signal** in `preview-state.yml`
+  (`selected_variant` + `is_baseline` per step-11b)
+- **MUST tolerate stub-mode InputArtifacts** (Phase B is text-strict;
+  other types produce `extracted_text="deferred to Phase C"`)
+- **MUST NOT touch app-repo files outside the chain's expected paths**
+  (`docs/input-artifacts/`, `docs/decompositions/`, `docs/prototypes/`,
+  `docs/preview-state/`, plus consumer's gallery scaffolding paths
+  per `/prototype-gallery`)
+
+## Procedure
+
+### Phase 0 — Pre-flight
+
+```bash
+# Verify on feature branch (fail fast on main)
+CURRENT=$(git branch --show-current)
+case "$CURRENT" in
+  main|master)
+    echo "preview: refuses to run on $CURRENT — create a feature branch first" >&2
+    exit 2
+    ;;
+esac
+
+# Verify accessor library available
+[ -f lib/state.sh ] || { echo "preview: lib/state.sh not found; spine v0 not installed" >&2; exit 4; }
+source lib/state.sh
+
+# Validate args: <tier> "<input>" [variants=N] [base=<slug>]
+TIER="$1"; INPUT="$2"; shift 2
+case "$TIER" in
+  quick) ;;
+  medium) echo "preview: medium tier returns stub (Phase D deferred); proceeding with stub output" >&2 ;;
+  *) echo "preview: unknown tier '$TIER' (must be: quick|medium)" >&2; exit 2 ;;
+esac
+[ -z "$INPUT" ] && { echo "preview: input required" >&2; exit 2; }
+```
+
+Parse remaining args:
+- `variants=N` (default 2-3 per `/riff-prototypes` ceiling; max 4 luminary + 1 baseline = 5)
+- `base=<slug>` (optional — re-bake on existing prototype slug)
+
+### Phase 1 — `/interpret-input`
+
+```bash
+SPRINT_SLUG="$(date -u +%Y-%m-%d)-preview-$(echo "$INPUT" | md5 -q 2>/dev/null | cut -c1-6 \
+                                            || echo "$INPUT" | md5sum 2>/dev/null | cut -c1-6)"
+
+INPUT_ARTIFACT_PATH=$(bash scripts/interpret-input.sh "$INPUT" --persist --slug="${SPRINT_SLUG}-input")
+# State-validate.sh hook validates schema at write; failure → BLOCKED
+```
+
+Output: `docs/input-artifacts/<slug>-input.json`
+
+If the artifact is stub-mode (auto-detected as url/image/repo/transcript/
+napkin), surface a warning that downstream extraction will be empty
+but proceed — the chain validates the interface even without real
+extraction.
+
+### Phase 2 — `/objectory-decompose`
+
+The agent invokes the skill via Skill tool with:
+
+```
+/objectory-decompose ${SPRINT_SLUG}-input
+```
+
+(Skill reads InputArtifact, applies Jacobson method, writes
+`docs/decompositions/${SPRINT_SLUG}-input-domain.md`)
+
+If extraction is empty (stub-mode upstream), surface to operator
+that variant generation will be working from minimal domain context.
+
+### Phase 3 — `/value-prop`
+
+The agent invokes:
+
+```
+/value-prop --brief "<extracted_text from InputArtifact>"
+```
+
+Captures a brief value-prop (claim + 3 RTBs) for the prototype-variants
+step to consume.
+
+In Phase B MVP, value-prop output goes inline into the PR body (does
+not persist to disk — `/value-prop` outputs are typically ephemeral).
+
+### Phase 3.5 — `/pick-luminaries` (in-turn picker for variant grounding)
+
+Runs inside the current turn. Picks N luminaries whose lens fits the intent. No separate LLM call. No provider key required. Per web#193 Option A rewrite. Sibling adopters can override the picker with their own `/extract-intent`.
+
+```bash
+source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+CATALOG=$(luminary_pick_catalog)
+```
+
+Now Claude (in-turn) reads `$intent_text`, enumerates `$CATALOG`, picks `${VARIANTS:-3}` slugs whose lens fits. Writes JSON to `/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"
+}
+```
+
+If the catalog helper fails (missing catalog dir), Phase 4 falls back to `/luminary recommend` signal scoring.
+
+### Phase 4 — `/riff-prototypes` (with WU-11b Anthropic baseline)
+
+The agent invokes:
+
+```
+/riff-prototypes
+  scope: "${INPUT}"
+  decomposition: docs/decompositions/${SPRINT_SLUG}-input-domain.md
+  value_prop: "<step 3 output>"
+  grounding: /tmp/luminary-pick.json   # from Phase 3.5; matched luminaries drive variants
+  variants: ${VARIANTS:-3}    # luminary-driven count
+  base: "${BASE:-}"           # optional re-bake target
+```
+
+Per WU-11b, `/riff-prototypes` ALWAYS emits N luminary-driven
+variants + 1 Anthropic `/frontend-design` baseline. Output:
+`docs/prototypes/${SPRINT_SLUG}/variant-*/` (N+1 directories).
+
+### Phase 5 — `/prototype-gallery`
+
+The agent invokes:
+
+```
+/prototype-gallery
+```
+
+(Scaffolds gallery index page with all variants. Per WU-11b, the
+gallery flags the `variant-baseline-anthropic/` directory visibly.)
+
+### Phase 6 — `/bind-subdomain` per variant
+
+For each variant, the agent dispatches:
+
+```
+/bind-subdomain
+  product_slug: ${SPRINT_SLUG}-${VARIANT_NAME}
+```
+
+If `/bind-subdomain` fails (e.g., consumer's `substrate.config.md`
+lacks `deploy_targets` / `amplify.yml` not configured), surface the
+failures BUT proceed — bind-subdomain is best-effort in Phase B; the
+PR still ships with prototype HTML and gallery for local review.
+
+### Phase 7 — Persist preview-state.yml
+
+```yaml
+# docs/preview-state/${SPRINT_SLUG}.yml
+slug: ${SPRINT_SLUG}
+input_artifact: ${SPRINT_SLUG}-input
+decomposition: ${SPRINT_SLUG}-input-domain
+status: variants-ready  # operator picks; status moves to "selected" / "rejected"
+current_tier: quick
+luminaries_used: [<list from /riff-prototypes output>]
+current_variants:
+  - name: variant-a-<luminary>
+    is_baseline: false
+    bind_subdomain_url: <if successful>
+  - name: variant-b-<luminary>
+    is_baseline: false
+    bind_subdomain_url: <if successful>
+  - name: variant-baseline-anthropic
+    is_baseline: true
+    bind_subdomain_url: <if successful>
+selected_variant: null     # operator fills post-review
+created_at: <ISO timestamp>
+created_by_session: <session-id>
+```
+
+State-validate.sh validates against `preview-state.schema.json` (v0
+catalog). Champion-challenger signal lives in `current_variants[*]
+.is_baseline` + `selected_variant` (when operator picks).
+
+### Phase 8 — Open PR
+
+```bash
+git add docs/input-artifacts/${SPRINT_SLUG}-input.json \
+        docs/decompositions/${SPRINT_SLUG}-input-domain.md \
+        docs/prototypes/${SPRINT_SLUG}/ \
+        docs/preview-state/${SPRINT_SLUG}.yml \
+        public/prototypes/${SPRINT_SLUG}/ \
+        src/app/page.tsx  # if gallery scaffold updated
+
+git commit -m "feat(preview): /stage quick — ${SPRINT_SLUG}
+
+InputArtifact: docs/input-artifacts/${SPRINT_SLUG}-input.json
+Decomposition: docs/decompositions/${SPRINT_SLUG}-input-domain.md
+Variants: N+1 (N luminary-driven + 1 Anthropic baseline per step-11b)
+Gallery: <route>
+Bind-subdomain: <success/failure summary>"
+
+git push -u origin <branch>
+
+gh pr create --title "/stage ${TIER}: ${SPRINT_SLUG}" --body "<body summarizing chain output + variant URLs + champion-challenger>"
+```
+
+PR body must follow `.claude/rules/pr-body-shape.md` — Flash + Tweet + `## Goal` first section. Then include:
+- Variant URLs (one per variant, including baseline)
+- Bind-subdomain status per variant
+- Pointer to `docs/preview-state/${SPRINT_SLUG}.yml`
+- Operator's next action: "Review variants. Pick winner. Update
+  `selected_variant` in preview-state.yml. Merge PR."
+
+## Tier behavior (PROTOTYPE-only — see /launch (formerly /preview-build) for build tiers)
+
+| Tier | Phase B MVP | Status |
+|---|---|---|
+| `quick` | ✅ Full chain (Phases 1-8). 2 variants + Anthropic baseline. ~30 min wall time. Mobile-dispatchable. | shipped |
+| `light` | ✅ Full chain + carry-forward ledger if `base=<slug>` provided. 3 variants + Anthropic baseline. ~2h wall time. Adds `/personas` (operator default OK), `/jtbd-tasks` (top jobs only), `/user-stories` (3-5). | shipped (Phase 4 dispatch fans out to multi-skill chain when `--tier=light`) |
+| `medium` | ❌ Refused — use `/launch medium` instead. Construction-input tier; produces buildable spec + GRASP + ux-migration. | redirected |
+| `full` | ❌ Refused — use `/launch full` instead. Audit-grade tier; same as medium + per-persona analysis + /synthetic-user. | redirected |
+
+When operator dispatches `/stage medium "..."` or `/stage full "..."`, this skill:
+1. Surfaces a clear error: "medium/full tiers ship buildable specs, not just visual variants — use `/launch <tier> '<input>'` instead. See the phase-boundary section above for the prototype/production boundary."
+2. Exits without dispatching the chain.
+
+Operator who wants medium/full's deeper analysis but ALSO wants a shorter exploratory pass first runs `/stage light` first (3 variants), picks a winner, then runs `/launch medium "..." base=<winner-slug>` for the buildable spec.
+
+## Failure modes (Phase B MVP scope)
+
+| Failure | Behavior |
+|---|---|
+| Stub-mode InputArtifact | Proceed; warn that downstream extraction is minimal |
+| `/objectory-decompose` produces empty inventory | Proceed; warn that variants will lack domain language |
+| `/bind-subdomain` fails (no amplify.yml in consumer) | Proceed; PR ships without deployed URLs; operator handles Amplify wiring out-of-band |
+| `/prototype-gallery` fails (consumer not Next.js) | Proceed; surface gallery error in PR body; variants still committed |
+| state-validate.sh BLOCKs any write | Hard fail; surface BLOCK to operator; do not commit partial chain |
+| On main branch | Refuse with exit 2 (per branching.md) |
+| Empty input | Refuse with exit 2 |
+
+## Rules
+
+- **PR-first, always** — per `.claude/rules/branching.md` and
+  `.claude/rules/pr-strategy.md`. Never push directly to main.
+- **All state writes through accessor** — preview-state.yml writes
+  use `state_preview_state_set` (or equivalent); state-validate.sh
+  hook gates schema conformance
+- **Stub-mode gracefully proceeds** — Phase B is text-strict; other
+  input modes don't break the chain, they produce stubs that
+  downstream consumers handle
+- **Champion-challenger captured** — `is_baseline` flag preserved
+  through to preview-state.yml; future runs can audit ratio
+- **Best-effort bind-subdomain** — failures don't fail the chain;
+  operator wires Amplify config in consumer repo separately
+
+## Skipping / Aborting
+
+- Operator interrupts mid-chain: agent commits whatever's complete +
+  surfaces "preview interrupted at Phase N" in the partial PR body
+- Hard ceiling hit (per `guardrails.md`): pause + surface to operator
+- Schema validation block: stop chain; do not commit
+
+## Reserved-names check
+
+`preview` is NOT on `standards/reserved-skill-names.md` list. Verified
+during WU-9 goal shape and at branch creation time.
+
+## Relationship to other skills + standards
+
+- `standards/input-handler-interface.md` — InputArtifact contract
+  (Phase 1 dispatch)
+- `.claude/skills/interpret-input/SKILL.md` — Phase 1 producer
+- `.claude/skills/objectory-decompose/SKILL.md` — Phase 2 consumer
+- `.claude/skills/value-prop/SKILL.md` — Phase 3 producer
+- `.claude/skills/prototype-variants/SKILL.md` — Phase 4 (with WU-11b
+  baseline)
+- `.claude/skills/prototype-gallery/SKILL.md` — Phase 5
+- `.claude/skills/bind-subdomain/SKILL.md` — Phase 6
+- `standards/state-spine/schemas/preview-state.schema.json` — Phase 7 schema
+- `.claude/rules/branching.md` + `.claude/rules/pr-strategy.md` — Phase 8 PR discipline
+- `docs/iteration-bets/<goal-slug>.md` —
+  parent goal defining the full pipeline ambition (this MVP ships subset)
+
+## What this skill enables (post-merge)
+
+After this skill + dependencies ship + merge:
+
+1. Operator dispatches a paragraph from phone:
+   ```
+   cd ~/src/your-org/your-app
+   /stage quick "Dramatically simplify and delightfully surface deals..."
+   ```
+2. Chain runs end-to-end (~5 min wall time on quick tier)
+3. PR opens with InputArtifact + decomposition + N+1 variants + gallery
+4. Operator reviews PR (mobile-friendly via GitHub mobile app)
+5. Operator picks winner; updates `selected_variant` in preview-state.yml
+6. Operator merges PR; CI deploys variants to Amplify (if consumer has wiring)
+7. Operator decides: ship winner via `/ux-migration` (Phase D follow-up)
+   OR re-bake with different variants
+
+This is the mobile-dispatchable SDLC the parent goal was shaped for.
+Phase B MVP ships the dispatch path; Phase D ships the migration path
+to Construction.
+
+## Enforcement
+
+Methodology-level. State-validate.sh hook enforces preview-state.yml
+schema. PR-first discipline enforced via branching.md rule + pre-build-gate
+hook. Reserved-names check passes. No additional hook enforcement
+added by this skill.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/state-a-problem/SKILL.md

@@ -0,0 +1,185 @@
+---
+tier: lite
+name: state-a-problem
+description: "Draft a problem statement for a PR, issue, canvas, or spec. Two sizes: brief (\u2264500 chars, opener, framework implicit) and para (\u22641200 chars, 5-block Who/What/When/Why-now/Outcome template). Runs /kiss --grade8 inline by default."
+problem: "PR bodies and issue bodies open with framing that hides the user pain. Readers scroll past."
+value: "One statement that leads with who hurts and what breaks and why fix it now. Ready to paste."
+inputs: [A ticket ref or doc path or scope description, Optional size — brief or para]
+outputs: [A problem statement that leads with user pain]
+user_invocable: true
+disable_model_invocation: false
+sizes: [brief, para]
+composes_with: [kiss, value-prop]
+---
+
+# /state-a-problem
+
+## What you get
+
+A problem statement that leads with user pain. Two sizes.
+
+`brief` fits a PR or issue opener. Cap 500 chars. 3-4 sentences carry the 5W framework — Who, What, When, Why now, Outcome. Labels stay implicit.
+
+`para` fits a canvas Thesis or spec Problem section. Cap 1200 chars. 5 blocks name each W.
+
+Output runs through `/kiss --grade8` inline by default. The statement lands in plain English ready to paste.
+
+## When to use it
+
+Use this when opening a doc a reader will scan for "why does this exist?" — a PR body, an issue body, a canvas Thesis, a spec Problem section, an ADR Context section. Pair with `/value-prop` when both problem and value belong at the opener.
+
+Skip it for one-line status updates. Skip it for chat asides. The 5W framework earns its cost on scan surfaces.
+
+## FAQ
+
+### What's the difference between brief and para?
+
+`brief` (default) drafts 3-4 sentences in ≤500 chars. The framework labels stay implicit. Sentence structure carries the Who / What / When / Why now / Outcome without spelling them out. Use it for PR and issue openers where scan speed matters.
+
+`para` drafts the same content as 5 labeled blocks in ≤1200 chars. Use it for a canvas Thesis or spec Problem section. Named blocks help readers find each W.
+
+### What does the 5W framework cover?
+
+- **Who** — the user role that hits the pain. Agent, operator, adopter, end user, future reader. Specific — not "everyone."
+- **What** — the pain or gap. Stated with verbs. Concrete — not "the experience is poor."
+- **When** — the trigger. "On every commit." "When authoring a PR body." "After the third tab open."
+- **Why now** — the insight that makes this iteration the right time. A new signal, a fresh incident, a downstream block.
+- **Outcome we want** — the observable change once the work ships. Not the fix — the result.
+
+If "why now" is "it has always been this way" — surface to the operator. The problem may not be urgent.
+
+### Why /kiss runs inline by default?
+
+We use what we ship. A skill that drafts plain English must itself emit plain English. The default runs BLOCK plus ADVISE substitution. It reads the wordlist at `standards/bassclef-internal-jargon.md`. Use `--no-kiss` when you want to inspect the raw draft. Rare.
+
+### What if the draft runs over the char cap?
+
+The skill surfaces the overage with the AS-IS draft. You decide. Condense further. Or accept the overage with a note. Trim adjectives first. Then condense the When clause. Then merge sentences.
+
+### How does this pair with /value-prop?
+
+`/state-a-problem` states the pain. `/value-prop` states the solution claim. Together they open a PR body that reads pain-first, value-next, diff-after. Run them in sequence when a feature-scope PR wants both framings.
+
+### What are the three references behind the template?
+
+NN/g (Nielsen Norman Group) — the 5W1H plus insight framework. UX Design Institute — the User / Problem / Outcome template that seeds the para-mode block names. OpinionX — the discovery framing that anchors "Why now" as the insight worth addressing. All three converge on the same form. The skill synthesizes them.
+
+## Details below the fold
+
+### Procedure
+
+**Step 0 — Read the situation.**
+
+The operator pastes the situation. Or links the ticket. Or describes it verbally. Read every artifact named. The ticket body. Prior PRs. The iteration goal. Sibling tickets. The 5W answers come from the situation. Not from imagination.
+
+If the situation is thin ("draft a problem statement for bassclef#NNNN") — read the ticket body first.
+
+**Step 1 — Extract the five Ws.**
+
+Ask each block's question. Land a concrete answer. If any block reads as vague — "everyone", "the experience is poor", "it has always been this way" — pause. Surface to the operator.
+
+**Step 2 — Draft at the requested size.**
+
+For `brief` — compose 3-4 sentences. Aim ~400 chars. Cap 500. Order — When plus Who plus What sets the situation. Why-now grounds urgency. Outcome names the change. Labels stay implicit.
+
+Sample form — `Today [Who] [What] when [When]. [Why now]. The change we want is [Outcome].`
+
+For `para` — use the 5-block named template. Aim 80-200 chars per block. Cap the whole at 1200.
+
+```
+**Who:** [1-2 sentences naming the user role]
+**What:** [1-2 sentences naming the pain or gap, with verbs]
+**When:** [1 sentence naming the trigger context]
+**Why now:** [1-2 sentences naming the insight or new evidence]
+**Outcome we want:** [1 sentence naming the measurable change]
+```
+
+**Step 3 — Run /kiss --grade8 inline (default).**
+
+Unless `--no-kiss` is set — pass the draft through `/kiss --grade8` substitution.
+
+- Replaces BLOCK-tier terms per `standards/bassclef-internal-jargon.md`
+- Replaces ADVISE-tier terms per the same standard
+- Preserves ALLOW-tier terms (substrate, bassclef, cameo, Studio, Band, bandleader per bassclef#763)
+- Preserves standard tech vocab (API, hook, schema, etc.)
+
+**Step 4 — Verify length + return.**
+
+Check the output fits within the requested size's char cap. If over — surface to the operator with the AS-IS draft.
+
+Return the cleaned statement. If `--no-kiss` — return the raw draft with a one-line note.
+
+### Example output — brief mode
+
+For bassclef#1178 (this skill's parent ticket):
+
+```
+Today PR + issue body openers use Flash + Tweet — both solution-framed,
+neither stating the user pain. Readers scan from "what this PR ships"
+straight to the diff without seeing why the work exists. UX research
+frameworks center user pain before solution; applied at PR + issue
+opener, the same template gives readers a clean entry. The change we
+want is one problem-grounded section per opener, drafted by a skill
+that runs /kiss --grade8 inline so adopters get plain English by
+default.
+```
+
+478 chars — fits the ≤500 cap.
+
+### Example output — para mode
+
+For bassclef#1178 (same ticket, canvas Thesis size):
+
+```
+**Who:** Agents and operators authoring PR + issue bodies, and the
+readers scanning those bodies.
+
+**What:** Today's PR + issue opener uses Flash (≤180) + Tweet (≤280) —
+both solution-framed. Neither states the user pain. Readers jump from
+"what this PR ships" to the diff without seeing why the work exists.
+
+**When:** Every PR-body or issue-body draft. The skip happens at the
+first scan, every time.
+
+**Why now:** Three UX research frameworks (NN/g, UX Design Institute,
+OpinionX) converge on a stable template — Who/What/When/Why-now/
+Outcome — that centers user pain. The substrate already ships /kiss +
+/value-prop as the discipline layer; one more skill locks in the shape.
+
+**Outcome we want:** Every feature-scope PR + issue opens with a
+problem-grounded section drafted by /state-a-problem and run through
+/kiss --grade8 inline. Reader orientation costs drop; adopters get
+plain English by default.
+```
+
+~1100 chars — fits the ≤1200 cap.
+
+### Composes with
+
+- `/kiss --grade8` — runs inline by default on the skill's output
+- `/value-prop` — pairs at solution framing. Problem first, value next.
+- `/ticket` — this skill drafts the opener. `/ticket` drafts the INVEST story or epic that follows.
+- `/spec` — `/state-a-problem para` drafts the Problem section. `/spec` drafts the rest.
+
+### Distinct from
+
+- `/value-prop` — states the solution claim. Not the pain. Complements. Does not replace.
+- `/feynman` — explains a concept in plain English. Different intent. Explain vs orient.
+- `/kiss` — substitutes jargon line by line. Different scope. Line edit vs section draft.
+
+### Refs
+
+- bassclef#906 — original PR-body contract being retired
+- bassclef#484 — issue-body Flash + Tweet rule being retired
+- bassclef#1178 — this skill's parent ticket
+- bassclef#1181 — sister audit ticket for inline /kiss default across other skills operators read
+- `.claude/rules/pr-body-shape.md` — the contract this skill's output ships into
+- `.claude/rules/github-issue-flash-tweet.md` — sister rule at issue surface
+- `.claude/rules/assert-only-after-verify.md` — Toulmin argument (My claim + Evidence + Why the evidence supports the claim)
+- `standards/bassclef-internal-jargon.md` — wordlist `/kiss --grade8` reads from
+- `standards/opener-discipline.md` — the three-block opener discipline this skill drafts the Problem block for
+- NN/g, UX Design Institute, OpinionX — the three references synthesized in the template
+
+## 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/temperance/SKILL.md

@@ -0,0 +1,108 @@
+---
+tier: lite
+name: temperance
+description: "Pause and think before you code. Asks \u2014 am I building the right thing AND building it the right way? Fires before every non-trivial action."
+problem: "Sessions dive into edits before the operator asks whether it's the right work or the right shape."
+value: "A pause-and-think gate at every scope decision boundary. Six questions before code."
+inputs: [Optional scope decision context]
+outputs: [Right-thing answer, Right-way answer, Drift trigger for future watch]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Temperance
+
+A pause before you write code. Two questions that every other governance mechanism misses.
+
+Question one — am I building the right thing?
+
+Question two — am I building it the right way?
+
+## When to invoke
+
+- Before starting any non-trivial task.
+- When you feel the urge to "just ship it."
+- When the approach has more than 3 steps.
+- When you are about to touch auth, middleware, data pipeline, or external services.
+- When the user says "just do it" or "go fast" — that is exactly when to slow down.
+
+## The temperance checklist
+
+Answer these honestly before writing code.
+
+### 0. Right thing check — are you building the right thing?
+
+- Does this trace to a real need? A canvas, spec, issue, or user request.
+- Can you state the business signal this proves in one sentence?
+- If this ships and nobody uses it, was it still worth building?
+- Are you building this because the spec says so, because the user asked, or because it feels like a good idea?
+- At standard or full level — is this in the declared iteration scope? Retiring the declared risk? Proving the declared value?
+
+If you cannot answer "why does this matter?" in one sentence, stop. The most expensive thing you can build is a well-engineered feature nobody wanted.
+
+### 1. Simplicity check — building it the right way
+
+- Is this the simplest correct approach?
+- Are you adding complexity to handle scenarios that may not happen?
+- Could you solve this with config instead of code?
+- Would a senior engineer look at this and ask "why didn't you just...?"
+
+### 2. Brute-force check
+
+- Are you brute-forcing to make the user happy instead of designing properly?
+- Are you trying many approaches hoping one works?
+- Did you run `/diagnose` before jumping to a fix?
+- Are you treating symptoms or root causes?
+
+### 3. Blast radius check
+
+- What else does this change affect?
+- What working parts could break?
+- Have you verified the "before" state so you can confirm "after"?
+
+### 4. Verification check
+
+- How will you know this works — not just that it compiles?
+- What is the smallest test you can run?
+- Can you verify in under 2 minutes? If not, the approach may be too complex.
+
+### 5. Reversibility check
+
+- If this is wrong, how hard is it to undo?
+- Are you about to do something destructive? Force push. Schema change. Delete data.
+- Should you commit what you have first, before the change?
+
+## The decision
+
+State these five lines after the checklist:
+
+- **Why this matters** — one sentence naming the need this serves.
+- **Approach** — what you are going to do.
+- **Why this is the simplest correct approach** — one sentence.
+- **What you are NOT doing** — the temptations you resist.
+- **Verification plan** — how you will know it works.
+
+Then write the gate marker. BOTH the ephemeral flag AND the durable git-tracked marker. The pre-build-gate hook accepts either. The durable marker lets the 5-session compliance counter see mobile firings that would evaporate at sandbox teardown.
+
+```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 (existing pre-build-gate contract)
+touch "/tmp/claude-temperance-done-${SESSION_ID}-${BRANCH_HASH}"
+
+# Durable git-tracked marker
+mkdir -p state/markers/temperance
+date -u +%Y-%m-%dT%H:%M:%SZ > "state/markers/temperance/${BRANCH_SLUG}.marker"
+git add "state/markers/temperance/${BRANCH_SLUG}.marker"
+```
+
+The durable marker commits with the branch's normal flow. `state/markers/` is git-tracked per `.claude/rules/mobile-ephemeral-session.md` section 2.
+
+Then proceed with the work.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.