@thebassclef/lite 0.1.3 → 1.0.0

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

@@ -1,449 +0,0 @@
----
-tier: lite
-name: kiss
-description: "Keep it simple. Two modes: scope (compresses what ships; runs /value-prop brief plus MUST/SHOULD/COULD buckets) and words (rewrites to grade 8; big word to small word swap). Reads standards/bassclef-internal-jargon.md."
-problem: "Scope grows. Prose fills with jargon. Adopters read a wall of bassclef-internal words and give up."
-value: "Two modes \u2014 scope compresses what ships. Words rewrites vocabulary to grade 8. Plain English at the wire."
-inputs: [A ticket or goal path for scope mode, Paragraph text for words mode]
-outputs: [MUST/SHOULD/COULD buckets when scope, Grade-8 rewrite when words]
-user_invocable: true
-disable_model_invocation: false
-modes: [scope, words]
-composes_with: [value-prop, feynman]
----
-
-# /kiss — Keep It Simple
-
-Two modes for the two ways things get complicated:
-
-1. **`scope`** — too much being shipped. Cut down to what matters. Runs `/value-prop` brief + `/feynman` + MUST / SHOULD / COULD buckets with deferrals.
-2. **`words`** — too much jargon. Rewrite at grade-10 reading level. Big word → small word swap that keeps the structure.
-
-`/feynman` stays separate (different output shape — narrative + analogy, not word swap). `/kiss words` and `/feynman` solve different problems: `/kiss words` swaps words in place; `/feynman` writes a new explanation.
-
-This skill reads its vocabulary list from `standards/bassclef-internal-jargon.md` — the one source of truth shared with the PR-body-scrub hook and the pre-push `/kiss` hook. Edits to the list flow to all surfaces at once.
-
-**Tier gate (bassclef#740 Task 1.8).** `/feynman` ships at `tier: standard`. Lite adopters skip the /feynman dispatch. Print: "/feynman requires bassclef standard. Skipping." Resolve tier via `lib/tier-check.sh`.
-
-## Usage
-
-<!-- FKGL-EXEMPT: CLI reference table -->
-```
-/kiss                                  → infer mode from input + active context
-/kiss scope                            → default: read active iteration goal
-/kiss scope [ticket-ref]               → specific ticket
-/kiss scope for [freeform description] → freeform scope
-/kiss words [text]                     → rewrite at grade-10 (default)
-/kiss words --grade8 [text]            → strictest; board / mobile / parent-readable
-/kiss words --grade11 [text]           → engineering precision OK; PR descriptions
-/kiss words --rewrite [text]           → six heuristic checks per Hemingway / ONS / NN/g
-```
-<!-- /FKGL-EXEMPT -->
-
-**Mode inference (when invoked without explicit mode):**
-- Input is a ticket-ref, goal path, or "for [scope description]" → `scope`
-- Input is paragraph text → `words`
-- Input is empty → `scope` reading the active iteration goal
-
----
-
-## Mode: `scope` — compress what we're shipping
-
-One command that forces an agent to answer three questions about any
-scope it's about to act on:
-
-1. **What's the value?** (`/value-prop` brief mode)
-2. **Can you explain it simply?** (`/feynman`)
-3. **What's actually MUST vs SHOULD vs COULD?** (bucketed enumeration with explicit deferrals)
-
-Combined, the three answers constitute a one-page gut check. If the
-agent can't answer all three clearly, the scope isn't ready to build.
-
-### When to use scope mode
-
-- Scope feels bloated — too many WS, too many deliverables per WS
-- Operator can't cleanly say "this is what we're doing" in one sentence
-- Before committing a stacked-branch plan to Construction
-- When `/sprint` surfaces multiple options and you need to pick one
-- Post-canvas, pre-spec — sanity check the shape
-
-### When NOT to use scope mode
-
-- Trivial tasks (typo fix, single-line config change)
-- Tasks already covered by a specific chain (`/new-feature` for
-  greenfield features, `/autonomous` for SDLC sessions)
-- Standalone `/value-prop` or `/feynman` invocations when you only
-  need one of them
-- When you want to *produce the shaping artifacts*, not compress scope.
-  See `/shape` (preset-sized chain that runs the full shaping flow).
-  `/kiss scope` compresses; `/shape` dispatches.
-
-### Ticket references accepted (same shape as `/value-prop`)
-
-- GitHub issue: `#NNN` or `owner/repo#NNN`
-- File path: `docs/iteration-bets/YYYY-MM-DD-slug.md`
-- Spec path: `docs/specs/NNN-feature.md`
-- Canvas path: `docs/strategy/canvases/YYYY-MM-DD-slug.md`
-
-### Procedure (scope mode)
-
-#### Step 1: Read the scope
-
-Apply `artifact-ingestion.md` — read every referenced artifact before
-producing output. State sources read upfront.
-
-#### Step 2: Run /value-prop in brief mode
-
-Produce: claim (≤180 chars) + 3 RTBs (reasons to believe). Each RTB
-backed by evidence (prior chronicle, telemetry, commit history, or
-operator feedback).
-
-#### Step 3: Run /feynman
-
-Plain-English explanation of what this is and why it matters. 2-4
-sentences max. No jargon (composes with `words` mode below if needed).
-
-#### Step 4: Bucket the work
-
-Three buckets:
-- **MUST** — what gets built this iteration. Must fit declared time budget.
-- **SHOULD** — wanted but cuttable; explicitly defer with rationale
-- **COULD** — nice-to-have; explicit deferral
-
-Per `.claude/rules/plan-enumeration-needs-value-props.md`: each item
-in each bucket carries a tweet (claim + sharpener), not a bare
-ticket number or task name.
-
-#### Step 5: Gut-check question
-
-End with a single yes/no question for the operator: "Are we agreed
-that [MUST item 1] and [MUST item 2] are the only things in scope,
-and [SHOULD item], [COULD item] are explicitly deferred?"
-
-### Output format (scope mode)
-
-```markdown
-## /kiss scope — [goal/ticket name]
-
-### Value (per /value-prop brief)
-**Claim**: [≤180 chars]
-
-**Reasons to believe**:
-1. [evidence-backed reason]
-2. [evidence-backed reason]
-3. [evidence-backed reason]
-
-### Feynman (plain-English)
-[2-4 sentences, plain language]
-
-### Buckets
-
-**MUST** (this iteration):
-- [item with tweet]
-- [item with tweet]
-
-**SHOULD** (deferred — reason):
-- [item with tweet] — *deferred because [reason]*
-
-**COULD** (further deferred):
-- [item with tweet]
-
-### Gut-check
-Are we agreed [MUST list] is the entire scope, and [SHOULD/COULD] are
-explicitly deferred?
-
-### Sources read
-- [paths read for this output]
-```
-
----
-
-## Mode: `words` — rewrite vocabulary at grade-10
-
-Take any agent-produced text and rewrite it using grade-10 vocabulary. Mechanical word substitution. No new structure, no analogies, no stories.
-
-### The contract — substitute, do not advise
-
-`/kiss words` **rewrites the text and returns the rewritten output**. It does not flag terms and ask the operator to fix them. It does not produce a list of findings. It produces clean prose.
-
-When invoked on input containing BLOCK terms from `standards/bassclef-internal-jargon.md`:
-
-- `composer` becomes `runs` or `chains` (per surrounding context — pick whichever fits)
-- `load-bearing` becomes `required` or `essential`
-- `operationalize` becomes `do` or `ship`
-- `primitive` becomes `building block`
-- `tier-preset` becomes `preset` or `size`
-- `blast radius` becomes `impact` or `what it can break`
-- `compose-with` becomes `uses` or `builds on`
-- `scope-bounded` becomes `small` or `tight`
-
-This is the substitution contract. Skills firing `/kiss words` get back text without these terms; the CI advisory + scrub hooks then have nothing to flag.
-
-If the surrounding context genuinely requires the BLOCK term (e.g., quoting an external source verbatim), backtick the term so it ships as code reference, not prose. The hooks strip backticked content from their checks.
-
-### When to use words mode
-
-- Agent output reads as obtuse or jargon-heavy ("atomic," "load-bearing,"
-  "blast radius," "machine-readable," "determinism")
-- Operator on mobile asks "say that simpler" or "more plain English"
-- Chronicle, journal entry, or status surface needs to read clean
-- Composing into output that downstream skills (e.g., `/value-prop`
-  tweet mode) want plain by default
-
-### When NOT to use words mode
-
-- Code, commit messages, or technical reference where precise
-  terminology is essential (file paths, function names, API names —
-  these stay)
-- `/feynman` is the right call: needs analogy + story to ground a
-  concept for a non-technical audience. `/kiss words` doesn't add
-  explanation; it just trades words.
-- Operator-asked-for jargon ("explain rebase precisely") — don't
-  strip precision the operator asked for.
-
-### Sub-modes (words)
-
-Sub-mode names label the word swap tier. They do not name the target reading grade. The target lives in `skill-body-grade-gate.sh` and `plain-english-steering.sh`. Aim grade 8 for 80% of sentences. Ceiling grade 10 per sentence.
-
-Renamed 2026-07-27 per bassclef-upstream#957 Path A (Norman consult). The old name `grade10words` stays working as an alias through 2026-10-31 per ADR-031.
-
-<!-- FKGL-EXEMPT: flag-name reference table -->
-- **`default`** — moderate word swap. Keeps engineering terms. Alias: `grade10words` through 2026-10-31.
-- **`--grade11`** — lighter word swap. Jargon stays where precise. PR bodies and design docs.
-- **`--grade8`** — heaviest word swap. Strips bare technical terms unless backticked. Journal entries and executive summaries.
-- **`--rewrite`** — six heuristic checks on top of the substitution table:
-  passive voice, hyphen words, long sentences, non-SVO openers,
-  noun stacks, adverb density. Surfaces candidates for human review.
-  Grounded in Hemingway Editor + UK ONS Style Guide + NN/g Plain
-  Language + US Federal Plain Language Guidelines. Ships via
-  `lib/rewrite-check.sh` (goal 25d Step 5).
-<!-- /FKGL-EXEMPT -->
-
-### Procedure (words mode)
-
-#### Step 1: Read input
-
-Take input as inline text, file path, or "the previous agent output."
-If multiple inputs, process each separately.
-
-#### Step 2: Apply substitution table
-
-Run mechanical substitution per the table below. For each match:
-- Replace the term with its plain equivalent
-- Preserve case (lowercase → lowercase, Capital → Capital)
-- Preserve surrounding punctuation + structure
-- Code paths, file names, function names, API names — DON'T touch
-- Backtick-quoted text — DON'T touch (it's code)
-
-#### Step 3: Apply mode-specific rules
-
-`grade10` (default):
-- Substitute table-listed jargon
-- Keep widely-understood technical terms (commit, branch, merge, test, schema, hook, file, function)
-
-`--grade11`:
-- Substitute only the most opaque jargon (Helland, Yegge, GRASP, BCE)
-- Keep engineering-common terms
-- For PR descriptions where engineering precision matters
-
-`--grade8`:
-- Substitute table + drop ALL bare technical terms unless backticked
-- Pre-pend a one-line "what this is" if the paragraph is dense
-- For executive / board / parent-readable output
-
-#### Step 4: Output
-
-Print the rewritten text. Optionally show a diff (`--diff`) if the
-operator wants to audit the substitutions.
-
-### Substitution table (~40 entries — v0)
-
-Seeded from observed jargon in bassclef agent output. Grows over time
-as new jargon surfaces (mark new entries with the date they were added
-so growth is visible).
-
-| Big word / phrase | Plain equivalent (grade-10) |
-|---|---|
-| atomic | all-or-nothing |
-| determinism | same answer every time |
-| replay-deterministic | gives the same answer when re-run |
-| load-bearing | actually used / counted on |
-| machine-readable | the system can read it directly |
-| primitive | building block |
-| substrate | shared toolkit |
-| compose / composes | combine / works with |
-| ingest / ingestion | read in / reading |
-| enforcement | the rule that catches it |
-| enforce | catch it / make it stick |
-| instrumentation | what we measure |
-| blast radius | how much breaks if this goes wrong |
-| idempotent | safe to run twice |
-| bassclef | shared / official |
-| orthogonal | unrelated / separate concern |
-| obviate | make unnecessary |
-| supersede / supersedes | replaces |
-| coherent | consistent / it fits together |
-| heterogeneous | mixed / not the same kind |
-| homogeneous | same kind / consistent |
-| nominal | the expected case |
-| pathological | the bad case |
-| degenerate | broken / not the normal shape |
-| MECE | clean buckets, nothing overlaps, nothing missed |
-| time budget | how much we'll spend |
-| iteration / iteration goal | a chunk of work we commit to |
-| stack / stacked | a chain of small PRs |
-| retro | look-back / what we learned |
-| scope-bounded | bounded by what we said we'd ship |
-| stopping criteria | when we know we're done |
-| surface | the thing the user sees |
-| projection | computed view |
-| invariant | thing that's always true |
-| anti-pattern | the wrong way that looks right |
-| harness | the system Claude Code runs in |
-| hook | code that fires automatically |
-| cardinality | how many of them |
-| latency | wait time |
-| throughput | how many per second |
-| backpressure | when to slow down |
-| tier-preset | preset / size |
-| compose-with | uses / builds on |
-| operationalize | do / ship |
-| stuck-signal | repeated warning |
-| substrate-defect | bug in the rules |
-| INSTEAD-block discipline | the pairing rule |
-| composer (as bassclef noun) | runs / chains / combines |
-
-### Standard tech vocabulary — keep as-is
-
-These stay. Don't expand them into multi-sentence explanations. Per `.claude/rules/plain-english-discipline.md`:
-
-```
-API, SDK, CLI, GUI, HTTP, REST, JSON, YAML, schema, regex, hook,
-repo, branch, commit, PR, MR, CI, CD, workflow, action, artifact,
-function, class, method, property, field, constant, variable, enum,
-database, query, index, migration, transaction, cache, queue, lock,
-container, image, pod, cluster, node, runner, build, deploy, rollback,
-test, assert, mock, stub, fixture, snapshot, regression,
-auth, token, secret, credential, scope, permission, role,
-file, directory, path, glob, pattern, prefix, suffix
-```
-
-If a term is in this whitelist, words mode does NOT substitute it. The whitelist works alongside the substitution table — words mode runs the table substitutions, then verifies whitelist terms remain untouched.
-
-### What words mode does NOT touch
-
-- File paths: `lib/state.sh`, `docs/whereami.md`
-- Function names: `state_roadmap_get`, `claim_wu`
-- Issue / PR refs: `bassclef#337`, `PR #343`
-- Branch names: `feature/BASSCLEF-339-...`
-- Backticked strings: `` `last_event` ``
-- Code blocks (anything between triple backticks)
-- Skill names: `/temperance`, `/verify`, `/longrun`
-
-### What words mode does NOT do
-
-- Doesn't add new content. If a paragraph is missing context, it stays
-  missing — `/kiss words` trades vocabulary; it doesn't explain.
-- Doesn't restructure. Long sentences stay long; verbose paragraphs
-  stay verbose. Use `/value-prop` for compression.
-- Doesn't translate language. English stays English.
-- Doesn't replace `/feynman`. They're different jobs.
-
----
-
-## Surfaces that MUST use /kiss words by default
-
-These surfaces should pass output through `/kiss words` by default:
-
-- **Chronicle entries** — body should read in plain language
-- **journal entries** — board-level audience; use `--grade8`
-- **`/sprint` output** — operator-facing scan surface; default
-- **`/longrun` status blocks** — same
-- **`/whats-the-plan` output** — operator decides from this; default
-- **`/value-prop` tweet/flash output** — composing per bassclef#339 rule
-- **PR descriptions** — `--grade11` (engineering precision OK)
-- **Ticket bodies** (gh issue create / gh issue comment) — `--grade11` (engineering precision OK; same audience as PR descriptions). Per bassclef#832: ticket-body authoring without `/kiss words` lets bassclef-internal jargon leak into adopter-facing surfaces. Apply at every `gh issue create` invocation and at every ticket-body edit.
-- **SKILL.md bodies** (any edit to any `.claude/skills/*/SKILL.md`) — `--grade11` applied to the WHOLE file in the same change as any edit, per `standards/operator-facing-prose-discipline.md` Rule 2 (the meta-discipline: substrate that prescribes plain language must itself be plain). Per bassclef#790: when the agent updates a skill body for any reason, the existing bassclef-internal vocabulary in that same file gets rewritten in the same pass. Otherwise discipline-as-substrate edits ship with the very jargon the discipline catches. Scope per Rule 2: prose sections (descriptions, procedure narrative, when-to-use, why-this-exists, examples). Does NOT cover code blocks, file paths, reserved skill names, or quoted vocabulary from operator memory/chronicles.
-
-## Rules
-
-- Every `/kiss scope` output MUST include all five sections (value prop,
-  RTBs, Feynman, buckets, gut-check question). Omitting any defeats
-  the purpose.
-- Bucket enumerations (MUST/SHOULD/COULD) MUST follow
-  `.claude/rules/plan-enumeration-needs-value-props.md` — each item
-  carries a tweet (claim + sharpener), not a bare ticket number.
-- MUST items must fit declared time budget. If they don't, the skill has
-  done its job — force the re-shape.
-- Never invent evidence for RTBs. Use prior chronicle entries,
-  telemetry, commit history, or stated operator feedback. "Proven to
-  work" is not evidence.
-- Never output more than one page of content for `scope`. If the bet
-  is too complex to fit, it's too complex for one `/kiss scope` pass —
-  run once per workstream.
-- For `words` mode, never invent substitutions not in the table. If a
-  jargon term isn't listed, leave it (and propose adding it for next
-  session). Preserve all structure: headings, bullets, code blocks,
-  links. Preserve all proper nouns (people, places, products) and
-  code identity.
-- For `--grade8`, if a sentence still reads obtuse after substitution,
-  suggest invoking `/feynman` for full explanation.
-
-## Relationship to other skills
-
-| Skill | Relationship |
-|-------|-------------|
-| `/ogilvy-writing-audit` | Pair skill — audit diagnoses via Ogilvy's 10 rules; `/kiss words` fixes what a wordlist covers. Run audit first, then kiss (per `standards/ogilvy-writing-rules.md`) |
-| `/value-prop` | Composer embeds `/value-prop` brief mode in `scope` Step 2; `words` mode operates on /value-prop OUTPUT |
-| `/feynman` | Composer embeds `/feynman` in `scope` Step 3; different from `words` mode (analogy vs substitution) |
-| `/whats-the-plan` | Orthogonal — `/whats-the-plan` declares skill chain; this declares scope shape |
-| `/sprint` | `/sprint` proposes next work; `/kiss scope` gut-checks it before commit; `/kiss words` makes its output mobile-readable |
-| `/canvas` | Canvas stages produce raw scope; `/kiss scope` compresses for decision |
-| `/spec` | Spec is the full contract; `/kiss scope` is the one-pager gut check before spec |
-| `/longrun`, `/chronicle`, `/journal` | MUST use `/kiss words` per the surfaces list above |
-
-## Relationship to rules + standards
-
-- `.claude/rules/assert-only-after-verify.md` — plain English does
-  not replace argument shape. `/kiss words` swaps vocabulary; the
-  assert-verify rule requires My claim + Evidence + Why the evidence supports the claim at every
-  operator-facing assertion regardless of vocabulary level. The two
-  rules compose — grade-10 vocabulary carrying a well-shaped Toulmin
-  argument. Per bet 2026-07-01b (R8 cure) + anchor luminary
-  `.claude/luminaries/stephen-toulmin.md`
-
-## Common pitfalls
-
-- **Bucketing by hope, not discipline** — "this one small extra thing
-  should fit in MUST" is how scope creeps. If it wasn't in the goal's
-  acceptance criteria, it's SHOULD or COULD.
-- **Inventing RTBs** — if no evidence exists, state "no prior
-  evidence — proof is forward-looking, validate via [signal]."
-- **Skipping Feynman because "it's obvious"** — if it's obvious,
-  writing it takes 30 seconds. The discipline is the point.
-- **Running on trivial scope** — this combined skill has overhead; don't use it
-  on single-line changes.
-- **Words mode mistaken for /feynman** — `/kiss words` swaps
-  vocabulary; `/feynman` writes a new explanation. Use the right
-  tool.
-
-## History
-
-- 2026-04-29: Renamed from `/keep-it-simple` to `/kiss`. Added `words`
-  mode (mechanical vocabulary substitution at grade-10 / 11 / 8 levels).
-  Closes bassclef#340 (folds the planned `/grade10words` skill
-  into this one; same intent — keep it simple — different axes).
-- (prior history) — `/keep-it-simple` shipped 2026-04 with the scope
-  combined skill (value-prop + feynman + MUST/SHOULD/COULD).
-
-## Retirement condition
-
-This skill retires only if both axes get separate dedicated tooling:
-`/value-prop` brief becomes the bassclef scope chain (no need for
-this layer) AND agent output is uniformly grade-10 by default (no
-need for vocabulary substitution). Until then, both modes earn their
-place.
-
-## Output discipline
-
-Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.