@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/standards/ogilvy-writing-rules.md

@@ -0,0 +1,225 @@
+---
+tier: lite
+title: Ogilvy writing rules — reference for the writing-craft discipline
+sources:
+  - David Ogilvy — "How to Write" internal memo (1982; 10 rules to Ogilvy and Mather management)
+  - Kenneth Roman + Joel Raphaelson — Writing That Works (Harper and Row, 1981)
+authoring_luminaries:
+  primary: [david-ogilvy]
+  supporting: [stephen-toulmin, rich-hickey, kent-beck]
+description: "This standard holds the 10 rules bassclef's writing-craft discipline references."
+---
+
+# Ogilvy writing rules — bassclef reference
+
+This standard holds the 10 rules bassclef's writing-craft discipline references. Each rule names the test, the violation pattern, the fix. Grounded in David Ogilvy's 1982 "How to Write" memo and Kenneth Roman and Joel Raphaelson's *Writing That Works* (1981). No wording lifted from any other source — bassclef's own restatement of the public rules.
+
+Cited by:
+
+- `.claude/rules/writing-craft-discipline.md` — auto-loaded rule; first-person composition checks
+- `.claude/skills/ogilvy-writing-audit/SKILL.md` — audit skill; severity-tagged violations
+- `.claude/hooks/plain-english-steering.sh` (extension per ticket #935) — steering hook reads rule names from here
+
+## Sources read
+
+- David Ogilvy 1982 "How to Write" memo — public circulation
+- Kenneth Roman + Joel Raphaelson 1981 *Writing That Works* — published book
+- `.claude/luminaries/david-ogilvy.md` — full luminary shipping alongside this standard
+
+## The 10 rules
+
+### Rule 1 — Natural voice
+
+Read the sentence aloud. Would a real person say it that way to a respected peer?
+
+**Fails.**
+- "Pursuant to our earlier discussion..."
+- "It has come to my attention that..."
+- "Please be advised that..."
+- Passive voice where active would fit: "A decision was made" → "We decided"
+
+**Fixes.**
+- "As we discussed..."
+- "I noticed..."
+- Just state the point without the preamble.
+
+Natural does NOT mean casual. Lawyers and engineers have natural voices that sound like lawyers and engineers. Natural means the writer sounds like themselves, speaking to a peer.
+
+### Rule 2 — Short units
+
+Words, sentences, paragraphs — keep them short.
+
+**Word swaps (Ogilvy's list, extended).**
+- utilize → use
+- commence → start
+- endeavor → try
+- facilitate → help
+- terminate → end
+- implement → do
+- demonstrate → show
+- approximately → about
+- subsequent → next
+- in order to → to
+
+**Sentence rule.** If a sentence runs past 25 words, it hides two or three sentences. Split at the natural clause boundary.
+
+**Paragraph rule.** If a paragraph runs past 6 sentences (about 100 words), it covers more than one idea. Split.
+
+### Rule 3 — No jargon
+
+If a normal word would carry the same meaning, use the normal word. Ogilvy's list — "reconceptualize," "demassification," "attitudinally," "judgmentally" — extends into modern consulting speak.
+
+**Common offenders in agent output.**
+- leverage (as verb), synergies, verticals, circle back, deep dive
+- ideate, iterate (vague), pivot (metaphorical)
+- value-add, move the needle, boil the ocean
+- robust, scalable, holistic (outside biology)
+- stakeholder (often no referent)
+- operationalize, incentivize, strategize
+
+**When jargon is fine.** Technical writing where the term has a precise meaning the audience shares. "API rate limit" in dev docs stays.
+
+**When jargon is not fine.** Anywhere the writer is trying to sound important instead of be precise.
+
+### Rule 4 — Verify quotations
+
+Flag quotations for verification. Attributed quotes ("As Einstein said...") are misattributed 90 percent of the time.
+
+Bassclef does not usually quote outside sources. When we do — in journal entries, luminary bodies, R&R citations — verify the source.
+
+### Rule 5 — Read-aloud test
+
+Read the passage in your head. If it stumbles, rewrite.
+
+**Fails.**
+- Tongue-twisters: "The situation's specification specifies..."
+- Long lines with no comma rest — a 35-word sentence is physically hard to speak
+- Unintentional rhymes: "The initiation of the presentation caused frustration..."
+- Repeated words within one sentence: "review the review of the review process"
+
+**Fix.** Split, rearrange, cut. The passage should flow at reading speed.
+
+### Rule 6 — Clear ask
+
+If the message requests action, is the ask crystal clear? Can the reader state, in one sentence, what they should do next?
+
+**Fails.**
+- Information dump with no ask at the end
+- Buried ask: "...and if you could send over the Q3 numbers as well..."
+- Vague ask: "Let me know your thoughts."
+- Passive ask: "It would be great if someone could..."
+
+**Fix.** State the ask directly at the top or bottom. Name the decision, the format, the deadline.
+
+When no ask is needed — pure information — say so: "No action needed — sharing for awareness."
+
+### Rule 7 — Comprehension (Roman + Raphaelson)
+
+"People seldom act on what they cannot understand."
+
+Could the intended reader — not an insider, but the actual recipient — understand what is being said on first read?
+
+**Fails.**
+- Unexplained acronyms (especially internal ones — "the PM flagged KR slippage")
+- Assumed context: "as discussed in the offsite"
+- Compressed logic that skips steps
+- Pronouns without clear antecedents: "They said this would happen"
+
+**Fix.** Write for the reader who was not in the last meeting. Expand acronyms first mention. Name the people. Show the steps.
+
+Different from Rule 3 (jargon). Jargon is bad words. Comprehension is the bigger question: after reading the whole thing, does the reader actually know what is going on?
+
+### Rule 8 — Completeness (Roman + Raphaelson)
+
+"When you say something, make sure you have said it. The chances of your having said it are only fair."
+
+Did the writer actually state the thing they meant to state, or did they dance around it?
+
+**Fails.**
+- Questions implied but not asked
+- Requests implied but not made
+- Conclusions implied but not stated
+- Main point arrives halfway through
+
+**Diagnostic.** What is the ONE thing the reader needs to take from this? Is that thing actually written down, in plain language, somewhere the reader will see it?
+
+Overlaps with Rule 6 (clear ask) but broader. Rule 6 covers action. Rule 8 covers whether the message itself is fully delivered.
+
+### Rule 9 — Honesty / no hedging (Roman + Raphaelson)
+
+"Intelligent readers develop a nose for deceptive writing and are seldom taken in by it."
+"Bad news is not made better by being baffling as well as unwelcome."
+
+Is the writer saying what they mean, or hiding behind softening language?
+
+**Fails (euphemisms).**
+- "right-sizing" → layoffs
+- "we're going in a different direction" → we're rejecting your proposal
+- "challenging" → bad, failing
+- "opportunity for improvement" → problem
+- "reached out" → contacted, called, emailed
+
+**Fails (weasel words).**
+- "arguably," "somewhat," "perhaps," "it could be argued"
+- "we believe" as a shield for controversial claims
+- Hedging adverbs stacked: "potentially," "possibly," "likely"
+- Passive voice hiding the actor: "mistakes were made"
+
+**Fix.** Say the thing straight. Bad news arrives first, then the reason, then the next step.
+
+**When hedging IS fine.** Genuine uncertainty honestly acknowledged: "I'm not sure — it might be A or B" is fine. Calibrated confidence: "likely" used when the probability is around 70 percent is fine.
+
+### Rule 10 — Facts with context (Roman + Raphaelson)
+
+"Never present facts on their own, like unstrung gems."
+
+For each fact, number, or data point: does the reader know why it matters? Is it connected to a point?
+
+**Fails.**
+- "Revenue was 4.2M." (What matters? Up? Down? Compared to what?)
+- Bullet lists of numbers with no interpretation
+- "The data shows..." followed by data but no "therefore..."
+- Percentages without denominators: "engagement up 40 percent" (from what? over what period?)
+
+**Fix.** For every fact, ask "so what?" Answer inline.
+
+**Diagnostic.** R&R's metaphor: facts are building materials. Readers are not impressed by a pile of bricks. They want to see the building.
+
+## Severity guidance
+
+When flagging a violation, tag severity:
+
+- **🔴 Critical** — The violation actively undermines the message. The reader will be confused, misled, or fail to act. Must fix.
+- **🟡 Moderate** — The violation weakens the writing. A sharp reader will notice. Should fix.
+- **🟢 Minor** — A small stumble. The message works without fixing it. Optional polish.
+
+**Calibration examples.**
+
+- Jargon in a customer-facing headline = Critical. Jargon in paragraph 4 of a memo = Moderate.
+- Missing ask in an action-requesting email = Critical. Unclear ask in an FYI update = Moderate.
+- A 30-word sentence in dense technical copy = Moderate. A 30-word sentence in a memo intro = Critical.
+- A stray euphemism in a friendly update = Minor. A euphemism burying bad news = Critical.
+
+**When in doubt, ask.** Would the intended reader still take the intended action after reading this? If no, it's Critical.
+
+## What the rules do NOT cover
+
+Ogilvy's memo names four more behavioral rules that prose alone cannot audit:
+
+1. Have you read *Writing That Works* three times? (Ogilvy's Rule 1)
+2. Did you check your quotations? (Rule 6 in text form is above; the behavioral check is separate)
+3. Did you sleep on it? "Never send a letter or memo on the day you write it. Read it aloud the next morning, then edit." (Rule 7)
+4. If it is important, did you get a colleague to improve it? (Rule 8)
+5. If you want action, is writing actually the right medium? Ogilvy's Rule 10: "Don't write — go tell the person what you want."
+
+The audit surface — `/ogilvy-writing-audit` skill — flags these as reminders at the end of every audit, without trying to check them from text.
+
+## Rules bassclef adds on top
+
+- **`/kiss words` composes with this standard.** After `/ogilvy-writing-audit` flags the violations, `/kiss words` mechanical substitution fixes what a wordlist covers. The audit diagnoses; the fix skill applies.
+- **`standards/bassclef-internal-jargon.md` extends the Rule 3 list.** Bassclef adds business jargon Ogilvy's 1982 memo did not cover (leverage as verb, synergies, circle back, deep dive, ideate, value-add, robust, scalable, holistic, stakeholder without referent).
+- **`.claude/rules/plain-english-discipline.md` sits alongside.** Grade-level target (grade 8-9 today; grade 8 after ticket #935 lands). This standard covers writing craft; that rule covers vocabulary and grade.
+
+## Retirement condition
+
+This standard retires only if bassclef stops shipping operator-facing prose. The specific rules may evolve (the wordlist grows; severity calibration adjusts) but the discipline of prose-as-craft persists.

package/dist/lite/standards/opener-discipline.md

@@ -0,0 +1,96 @@
+---
+tier: lite
+description: Every planning-surface opener carries three blocks in this order — Problem, Value prop, Evidence.
+---
+
+# Opener discipline — Problem + Value prop + Evidence
+
+Every planning-surface opener carries three blocks in this order — Problem, Value prop, Evidence. The reader sees the pain, then the fix, then the receipts. Same shape scales down (a short session) or up (a goal close).
+
+## The shape
+
+```
+## Problem (via /state-a-problem brief)
+[≤500 chars: who was affected + what pain + when + why now + outcome sought]
+
+## Value prop (via /value-prop tweet)
+[≤280 chars: claim + sharpener]
+
+## Evidence (per .claude/rules/assert-only-after-verify.md)
+- Source: [file path, ticket, commit SHA — what I read inline]
+- Warrant: [one sentence tying the source to the claim]
+```
+
+Three blocks. First block frames the pain. Second block names the outcome. Third block cites what backs the claim.
+
+## When this discipline fires
+
+Every planning surface where the agent addresses the operator:
+
+- `/longrun` prep + checkpoint + closeout output
+- `/sprint` opener output
+- `/session-log` (formerly `/chronicle`) opener block
+- `/session-end` closeout dispatch shape
+- Any agent turn prose that opens with a status assertion
+
+Pass-through cases (discipline does not fire):
+
+- Conversational asides mid-session ("switching to main now") — no assertion carried
+- Tool output relayed verbatim — the tool is the source
+- Direct answers to operator questions where the answer IS the value block
+
+## Why three blocks
+
+Seven luminaries converged on the shape:
+
+- **Alan Cooper** — persona-anchored. The reader wants pain framing before solution framing.
+- **Steve Krug** — don't make me think. A tweet claim alone makes the reader backfill "why should I care."
+- **Stephen Toulmin** — claim + data + warrant. Three blocks carry all three.
+- **Amazon PR/FAQ** — write the press release first. A press release opens with problem + value pairing, not claim + description.
+- **Marty Cagan** — outcomes not output.
+- **Kent Beck** — YAGNI. Three lines minimum; drop the fourth.
+- **Taiichi Ohno** — 7 wastes. Prior tweet + KISS pairing overlapped semantically; consolidate.
+
+## What replaces the old opener
+
+The prior shape was `/value-prop tweet` + `/kiss words` — a claim in tweet form plus a paragraph summary of the same claim. It carried the same information twice while missing pain framing and evidence citation.
+
+The new shape retires the tweet + KISS pair at planning surfaces. Tweet mode stays as one of the `/value-prop` sizes for other uses (like a status one-liner in chat). KISS words stays as a mode of `/kiss` for prose passes. Both stop being the opener default at planning surfaces.
+
+## Sizing guidance
+
+Scale the three blocks to the surface:
+
+| Surface | Problem | Value prop | Evidence |
+|---|---|---|---|
+| `/sprint` opener | 1-2 sentences | 1-line tweet | 1 source + 1 warrant |
+| `/longrun` prep | Full 500-char problem | Full 280-char tweet | 3-5 sources + warrants |
+| `/longrun` checkpoint | 1-2 sentences | 1-line tweet | 1-2 sources + warrants |
+| `/longrun` closeout | Full 500-char problem | Full 280-char tweet | Sources cited per major finding |
+| `/session-log` opener | Full 500-char problem | Full 280-char tweet | Sources per section |
+
+The reader's context governs the block size. A checkpoint mid-session needs less than a closeout at end-of-work.
+
+## Grace window
+
+Old openers keep working through 2026-10-31 per ADR-031 grace window and `.claude/rules/we-dont-break-adopters.md`. Sessions from before the rewrite still open with tweet + KISS; new sessions open with the three blocks. No adopter breakage.
+
+## Composes with
+
+- `.claude/rules/pr-body-shape.md` — sister discipline at PR body surface
+- `.claude/rules/github-issue-flash-tweet.md` — sister discipline at GitHub issue body surface
+- `.claude/rules/operator-facing-prose.md` Rule 3 — skill-dispatch citation extends to naming the standard opener
+- `.claude/rules/assert-only-after-verify.md` — the argument shape the Evidence block satisfies
+- `.claude/skills/state-a-problem/SKILL.md` — brief mode drafts the Problem block
+- `.claude/skills/value-prop/SKILL.md` — tweet mode drafts the Value prop block
+- ADR-040 Decisions 1-4 — the parent rewrite that introduced this standard
+
+## Refs
+
+- bassclef-upstream#750 — the ticket that mapped this rewrite
+- bassclef-upstream#1178 — the sister rewrite at PR + issue body surfaces
+- bassclef-upstream#559 — R8 mechanization umbrella (assert-only-after-verify parent)
+
+## Retirement condition
+
+This standard retires only if the three-block shape stops matching adopter reading behavior. The mechanical layer (hook scan for the shape) may ship as a follow-on when methodology drift is observed. Until then, this is methodology; the discipline holds at authoring time.

package/dist/lite/standards/operator-facing-prose-discipline.md

@@ -0,0 +1,201 @@
+---
+tier: lite
+description: "Universal principle: any shorthand in operator-facing prose carries a plain-language gloss at first mention per response."
+---
+
+# Operator-facing prose discipline
+
+Universal principle: any shorthand in operator-facing prose carries a plain-language gloss at first mention per response. When editing any SKILL.md file, apply a /kiss pass to the whole file in the same change.
+
+This standard scales operator attention across cross-session time gaps. The operator returns to substrate after hours, days, or weeks; the decoder ring for WU-N, F-X.Y, ADR-NNN, #NNN, LF-N, B1, B2 shouldn't have to be reconstructed from memory or substrate every time.
+
+## Scope
+
+Two surfaces:
+
+1. **All operator-facing skill output** — /sprint, /longrun, /diagnose, /autonomous, /retro, /promote, /temperance, /value-prop, /lean-canvas, /personas, /canvas, /roadmap-reconcile, /whereami, and any future skill that produces output an operator reads.
+2. **All turn-level prose between Claude Code and operator** — not just skill output. Conversational discipline applies the same gloss rule.
+
+## Rule 1 — Gloss at first mention per response
+
+Any shorthand reference in operator-facing prose carries a plain-language gloss at first mention per response. Subsequent mentions in the same response don't need to re-gloss.
+
+Format: `<shorthand> (<plain-language description>)`.
+
+Examples:
+
+| Shorthand | Glossed form |
+|---|---|
+| `WU-4` | `WU-4 (Tier 0 pitch draft using canvas UVP)` |
+| `#774` | `#774 (Phase XIV rescope proposal)` |
+| `F-D9.1` | `F-D9.1 (README hedges audience — audit HIGH)` |
+| `ADR-021` | `ADR-021 (anchor catalog selection)` |
+| `LF1` | `LF1 (Morgan-as-gatekeeper riskiest assumption)` |
+| `B1` | `B1 (tier-1-proposal-shaper bet)` |
+| `B2-WU1` | `B2-WU1 (README rewrite per F-D9.1)` |
+| `bassclef#739` | `bassclef#739 (substrate-coherence CI)` |
+| `Phase XIV` | `Phase XIV (Draw the Line — IP Guard, growth-loop rescope pending)` |
+
+### What this rule does NOT require
+
+- **Re-glossing within the same response.** First mention only.
+- **Glossing standard-vocabulary technical terms.** API, schema, hook, PR, commit, branch, merge — these stay as-is. See `standards/plain-english-discipline.md` "Keep standard technical vocabulary" section for the full allowlist.
+- **Glossing reserved concept names from the four-name system.** `substrate`, `bassclef`, `cameo`, `Studio`, `Band`, `bandleader` are allowlisted per bassclef#763 (/kiss reserved-name allowlist). They carry meaning the operator chose deliberately; gloss would be patronizing.
+- **Glossing skill names.** `/sprint`, `/longrun`, `/lean-canvas` — operator-invocable skills carry their own context via the `/` prefix.
+
+### When the gloss is awkward
+
+If the gloss inflates a sentence beyond readability, restructure the sentence rather than expand inline. Example:
+
+- Awkward: "Continue with WU-4 (Tier 0 pitch draft using canvas UVP A' selected for substrate-credibility audience + UVP D for dreamer-operator framing) after merging #773 (ADR-021 amendment for IP→growth-loop pivot)."
+- Restructured: "Continue with WU-4 after merging #773. WU-4 drafts the Tier 0 pitch using canvas UVP. #773 amends ADR-021 for the growth-loop pivot."
+
+The principle is operator readability, not mechanical glossing.
+
+## Rule 2 — /kiss pass when editing any SKILL.md
+
+When touching any SKILL.md file for any reason, apply a /kiss pass to the entire file in the same change. Not a separate cycle.
+
+Reasoning: if we're authoring an update to the skill that adds substrate discipline, the existing bassclef-internal vocabulary in that same file should be rewritten plain at the same time. Otherwise we ship discipline-as-substrate fixes that contain the very jargon the discipline catches.
+
+### /kiss pass mechanics
+
+Apply the rewrite rules from `.claude/rules/plain-english-discipline.md` (the master plain-English rule). Substitution targets that recur most often in SKILL.md files:
+
+| Phrase | Replacement |
+|---|---|
+| `load-bearing` | `essential` or `required` (or remove) |
+| `cross-cutting` | `affects multiple boxes` or name what it crosses |
+| `forcing function` | name what it forces directly |
+| `operator-locked` | `decided` or `set` |
+| `substrate-resident` | `in bassclef already` or `shipped` |
+| `operating thesis` | `the goal.we're making` |
+| `compose-with` | `uses` or `builds on` |
+| `tier-preset` | `preset` or `size` |
+| `operationalize` | `do` or `ship` |
+| `composer (as noun)` | `runs` or `chains` or `combines` |
+
+Allowlist per bassclef#763 holds: `substrate`, `bassclef`, `cameo`, `Studio`, `Band`, `bandleader` stay.
+
+### Scope of the /kiss pass
+
+The pass covers the SKILL.md file's prose — descriptions, procedure narrative, when-to-use sections, why-this-exists sections, examples in prose form. It does NOT cover:
+
+- Code blocks
+- File path references
+- Reserved skill names
+- Quoted vocabulary from operator memory or chronicles
+
+### When the /kiss pass produces no edits
+
+If the file is already clean, the pass produces no edits. State this explicitly in the commit message ("kiss pass: no edits — file already clean") so future readers know the discipline was applied.
+
+## Rule 3 — Tweets lead with the goal, not just the work done
+
+A Tweet (≤280 chars) in a PR body, chronicle entry, or summary table tells the reader two things: what the work is FOR (the goal it serves) and what the work DID (the changes it shipped). When a Tweet captures only the second, the first rots within weeks — a future reader can't tell what problem the PR solved or why anyone cared.
+
+Format: `<what this is for>. <what it did>.`
+
+The goal sentence comes first. The work sentence comes second.
+
+### Worked example — PR #825 (bassclef#811 implementation)
+
+The original Tweet shipped without a goal sentence:
+
+> Per bassclef#811: sunj-labs/bassclef-upstream created; 115 files migrated (2 with git history, 113 bulk-imported); per-subdirectory symlinks set up via scripts/operator-setup.sh; adopters see only README placeholder; Rule 3 still passes; two standards docs codify the workflow.
+
+This tells you what happened. It doesn't tell you the goal was: operator-private files now have backup and version history without leaking to people who clone the public repo.
+
+The goal-first rewrite:
+
+> Operator-private files now safe from disk loss and version-controlled, but still hidden from people who clone the public repo. Per bassclef#811: sunj-labs/bassclef-upstream created; 115 files migrated; symlinks via scripts/operator-setup.sh; adopters see only README placeholder.
+
+Fits 280 chars. Names the goal first. Says what was done second.
+
+### What counts as a "goal"
+
+The goal is what the operator (or adopter) gets from this work. Useful tests:
+
+- If someone reads only the Tweet in 6 months, can they tell what problem the work solved?
+- If a future contributor asks "why did we ship this?", does the Tweet answer them?
+- If the work didn't ship at all, what would the operator miss?
+
+### Three Tweet rules together
+
+Tweets now carry three discipline rules:
+
+1. **Fit in 280 chars** (per bassclef#785 — tweet-style descriptions in summary tables)
+2. **Keep scoping qualifiers** (per bassclef#805 — "deferred within Tier 1" not just "deferred")
+3. **Lead with the goal** (this rule, per bassclef#831 — what the work is FOR, then what it did)
+
+All three rules become a single mechanical check when Rule 5 of substrate-coherence CI lands (bassclef#807).
+
+### What this rule does NOT require
+
+- **Lengthening the Tweet.** Goal-first should compress, not expand. If adding a goal sentence pushes past 280 chars, compress the work sentence.
+- **Restating the title.** PR titles already name the work; the Tweet's goal sentence adds the WHY the title doesn't capture.
+- **Goal-first for every PR-body section.** Tweets carry the goal; deeper sections (Summary, Implementation, Test plan) can lead with mechanics.
+
+## Audience-vigilance scaling argument
+
+The operator works across cross-session time gaps. A morning /sprint output that references `B1-WU4` without gloss requires the operator to either:
+
+1. Remember what B1-WU4 was from yesterday's session (unreliable across multi-day gaps)
+2. Read substrate (goal body + stack manifest + chronicle) to reconstruct the reference (operator-time tax)
+3. Ask the agent to expand the reference (extra turn, breaks flow)
+
+Glossing at first mention costs the agent zero additional reasoning — the gloss is already in scope from substrate reads the agent did to produce the response. The cost-shift is from operator-time to agent-tokens. The operator-time savings compound across every reference in every operator-facing response.
+
+The /kiss pass on SKILL.md edits closes the meta-discipline gap: if we ship substrate that says "operator-facing output should be plain" and that substrate is itself dense with bassclef-internal vocabulary, the discipline corrodes at its own source. Every SKILL.md edit is an opportunity to apply the discipline to the substrate doing the enforcing.
+
+## Enforcement layers
+
+| Layer | Mechanism | Status |
+|---|---|---|
+| Methodology | This standard + `.claude/rules/operator-facing-prose.md` (the conversational rule) | Loaded into every session via `additionalDirectories` |
+| Skill-level | Every operator-facing SKILL.md cites this standard in its rules section | Phased rollout — /longrun + /sprint + /diagnose + /autonomous land first |
+| Mechanical | bassclef#739 (substrate-coherence CI) extension lints operator-facing skill output for unglossed shorthand | Deferred — methodology-first, mechanical later |
+| /kiss pass on SKILL.md edits | Discipline-as-substrate per Rule 2 above | Methodology-level; substrate-clarity-gate hook (bassclef#382) already enforces at file-write boundary for jargon |
+
+## Methodology source
+
+Andrej Karpathy (`andrej-karpathy` luminary entry) is the methodology source for bassclef's clarity discipline. Karpathy's CPU-and-RAM framing — LLM as stateless computation engine; context window as finite working memory — makes prose clarity an engineering constraint, not a stylistic preference.
+
+Operator-facing prose is the context the model loads next session. Glossing shorthand at first mention, applying `/kiss` on SKILL.md edits, leading tweets with the goal — all three rules are concrete implementations of Karpathy's framing applied at the operator-facing surface. Each rule reduces context-budget waste (operator-time on the surface side, model-attention budget on the substrate side).
+
+Downstream practitioners apply INSTEAD-block discipline and DO/DO-NOT bounding as specific patterns; this standard cites Karpathy as the methodology, not those patterns as the source. The patterns compose; the methodology grounds them.
+
+## Relationship to other discipline standards
+
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule. This standard extends it with the gloss rule + the /kiss-pass-on-edits meta-discipline.
+- `.claude/rules/skill-description-clarity.md` — narrow case at skill description field. This standard extends to skill body prose.
+- `.claude/rules/github-issue-flash-tweet.md` — flash-tweet-then-detail discipline for GitHub issue bodies. Sibling.
+- `.claude/rules/context-engineering.md` — INSTEAD-block discipline for negations. Karpathy's methodology grounds the rule; INSTEAD-block is the pattern.
+- `.claude/rules/visual-hierarchy.md` — formatting discipline for long agent output. Sibling.
+- `.claude/luminaries/andrej-karpathy.md` — methodology source. CPU-and-RAM framing makes prose clarity a substrate constraint.
+
+## Override
+
+Per `.claude/rules/plain-english-discipline.md`: `SKIP_PLAIN_ENGLISH=1 <command>` for genuine cases (quoting an exact phrase from memory or external doc). Logged via trace-helper. Use rarely.
+
+There is no override for the /kiss pass on SKILL.md edits — that's a meta-discipline that holds without exception. If a SKILL.md edit can't carry a /kiss pass within the same change (scope is too tight, urgency is too high), the discipline is signaling that the SKILL.md needs a dedicated /kiss-pass PR. File it.
+
+## Surfaced in
+
+- /sprint 2026-05-30 morning session — operator returned after overnight gap, surfaced that shorthand references in /sprint output require plain-language gloss for cross-session orientation. Pattern recurs in every operator session with a time gap from prior work.
+- Same session — operator surfaced the meta-discipline: if we are already authoring SKILL.md updates for the gloss rule, the existing jargon in those files should be rewritten in the same pass.
+
+## Refs
+
+- bassclef#790 — parent ticket
+- bassclef#785 — tweet-style descriptions in /longrun summary tables (sibling Tweet rule — length)
+- bassclef#805 — Tweet scoping-qualifier discipline (sibling Tweet rule — qualifiers)
+- bassclef#831 — Tweets lead with the goal (this Rule 3 — goal-first)
+- bassclef#807 — Rule 5 of substrate-coherence CI will check all three Tweet rules together
+- bassclef#780 — glossary + substrate-quote discipline (session-start glossary; this standard adds at-mention gloss)
+- bassclef#763 — /kiss reserved-name allowlist
+- bassclef#767 — /kiss hook coverage at artifact-write surfaces
+- bassclef#779 — /kiss interactive-session anchoring at turn-counter boundaries
+- bassclef#786 — /kiss PR-body hook enforcement decision (sibling)
+- bassclef#787 — PR-body scrub discipline (sibling)
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule (this standard extends)