@codegiveness/kernel-prompt 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @codegiveness/kernel-prompt
+
+## 0.1.0
+
+### Initial Release
+
+- Ship **`kernel-prompt`** — a prompt-engineering skill that refines or composes a prompt into one paragraph that lands on first try. The skill runs the KERNEL pass: six cuts (Keep it simple, Easy to verify, Reproducible, Narrow scope, Explicit constraints, Logical structure) that turn a vague request into a single paragraph carrying context, task, constraints, format, and verify as flowing prose.
+- Two branches: **Refine** (input is an existing prompt) and **Compose** (input is a task description). Same six letters, different starting material.
+- A grounding step pins vague input terms to concrete codebase symbols before the pass writes against them.
+- A vague-phrasing sweep tests every content clause against a two-reader test and applies one of seven named reformulation patterns when a clause fails.
+- Ships as installable npm prose (`@codegiveness/kernel-prompt`) — no compiled binary, no platform matrix.
+- `kernel-prompt update` pulls the latest version via npm.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codegiveness
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# Kernel — a prompt stripped to what works
+
+[![skills.sh](https://skills.sh/b/codegiveness/kernel-prompt)](https://skills.sh/codegiveness/kernel-prompt)
+[![npm version](https://img.shields.io/npm/v/@codegiveness/kernel-prompt.svg?style=flat-square)](https://www.npmjs.com/package/@codegiveness/kernel-prompt)
+[![npm downloads](https://img.shields.io/npm/dm/@codegiveness/kernel-prompt.svg?style=flat-square)](https://www.npmjs.com/package/@codegiveness/kernel-prompt)
+[![MIT License](https://img.shields.io/npm/l/@codegiveness/kernel-prompt.svg?style=flat-square)](https://github.com/codegiveness/kernel-prompt/blob/main/LICENSE)
+[![CI](https://github.com/codegiveness/kernel-prompt/actions/workflows/ci.yml/badge.svg)](https://github.com/codegiveness/kernel-prompt/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/codegiveness/kernel-prompt/actions/workflows/codeql.yml/badge.svg)](https://github.com/codegiveness/kernel-prompt/actions/workflows/codeql.yml)
+
+Six cuts that turn a vague request into a prompt that lands on first try.
+
+## Quickstart (30-second setup)
+
+1. Run the skills.sh installer:
+
+```bash
+npx skills@latest add codegiveness/kernel-prompt
+```
+
+2. Pick the skill, and which coding agent you want to install it on (Claude Code, Codex, OpenCode, or others).
+
+3. Bam — you're ready to go. The skill is prose; nothing compiles.
+
+## Install via npm
+
+Prefer a managed npm install you control by hand?
+
+```bash
+npm install -g @codegiveness/kernel-prompt
+kernel-prompt install   # symlinks the skill into ~/.claude/skills and ~/.agents/skills
+```
+
+Or copy the three files from `skills/engineering/kernel-prompt/` into your project's skill directory — the skill is prose, nothing compiles.
+
+To stay current:
+
+```bash
+kernel-prompt update    # npm install -g @codegiveness/kernel-prompt@latest
+```
+
+## Install as a Claude Code plugin
+
+This skill also ships as a native Claude Code plugin:
+
+```
+/plugin marketplace add codegiveness/kernel-prompt
+/plugin install kernel-prompt@codegiveness
+```
+
+Or from your shell:
+
+```bash
+claude plugin marketplace add codegiveness/kernel-prompt
+claude plugin install kernel-prompt@codegiveness
+```
+
+Three ways to install, three philosophies:
+
+- **[skills.sh](https://skills.sh/codegiveness/kernel-prompt)** copies the skill into your project so you can hack on it and make it your own.
+- **npm** installs the managed package globally and symlinks it into every agent harness you use.
+- **The plugin** keeps it as a read-only, always-current bundle you don't edit — best when you just want the skill to work and follow along as it evolves.
+
+## Why This Skill Exists
+
+> "No-one knows exactly what they want."
+>
+> David Thomas & Andrew Hunt, [The Pragmatic Programmer](https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)
+
+Every prompt-engineering failure mode traces back to one root cause: the request was vague. The agent filled the vagueness with its own priors, the priors were wrong, and the output missed. The fix is not a longer prompt — it is a tighter one. A prompt where every clause passes a two-reader test: would two different readers produce outputs matching in type and scope?
+
+> "The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
+>
+> John Ousterhout, [A Philosophy Of Software Design](https://www.amazon.co.uk/Philosophy-Software-Design-2nd/dp/173210221X)
+
+`kernel-prompt` is a deep module. Its interface is one paragraph; its behaviour is a six-letter pass — **K**eep it simple, **E**asy to verify, **R**eproducible, **N**arrow scope, **E**xplicit constraints, **L**ogical structure — plus an exhaustive vague-phrasing sweep. That paragraph carries five substances as flowing prose: **context** (grounded codebase symbols), **task** (the operation to perform), **constraints** (type, scope, limits), **format** (the deliverable shape), and **verify** (a checkable success criterion). You hand it a vague request, it returns a paragraph that lands. The simplicity is the point — the depth is in the cuts.
+
+> "With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model."
+>
+> Eric Evans, [Domain-Driven Design](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)
+
+The pass grounds vague terms to concrete codebase symbols before it writes. "The auth service" becomes `refreshToken (src/auth/tokens.ts:42)`. The paragraph carries the grounded vocabulary, not the user's original phrasing — so two readers see the same code, not the same ambiguity.
+
+The skill is model-invoked: any agent can reach for it when the task fits, and a user can call it directly. It has no `disable-model-invocation` flag — that's deliberate. A kernel'd prompt is the input every other skill wants.
+
+## Before / after
+
+**Vague input:**
+
+> Our auth service has a token refresh bug — users get logged out. Fix it, add a test that catches the regression, and update the runbook so on-call knows what to do.
+
+**Kernel'd output (one paragraph):**
+
+> `refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh, breaking `TokenStore` (src/auth/store.ts:15); patch `refreshToken` so it stops dropping sessions on refresh failure, add a `bun test` regression that fails before the fix and passes after, and update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each), shipping as one PR — TypeScript strict, no `as any`.
+
+The vague input names no symbols; the output grounds every term in a file and function, attaches a checkable success criterion, and carries its constraints inline. That's one pass — six cuts, one sweep, one paragraph.
+
+## Reference
+
+The skill splits on one axis — who can invoke it. **User-invoked** skills are reachable only when you type them; their job is to orchestrate. **Model-invoked** skills can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. `kernel-prompt` is model-invoked.
+
+| Skill | Invocation | Description |
+|---|---|---|
+| [kernel-prompt](./skills/engineering/kernel-prompt/SKILL.md) | Model-invoked | Kernel a prompt — refine or compose it into one paragraph that lands on first try. |
+
+### Files
+
+| File | Purpose |
+|---|---|
+| [`SKILL.md`](./skills/engineering/kernel-prompt/SKILL.md) | The KERNEL pass — six cuts (K-E-R-N-E-L) and the vague-phrasing sweep |
+| [`EXAMPLE.md`](./skills/engineering/kernel-prompt/EXAMPLE.md) | A full disclosed pass: grounding, combining, six letters, sweep with per-clause verdicts |
+| [`REFORMULATIONS.md`](./skills/engineering/kernel-prompt/REFORMULATIONS.md) | Seven named patterns for repairing clauses that fail the two-reader test |

package/bin/kernel-prompt.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// kernel-prompt — thin npm wrapper for install / update.
+// The skill itself is prose (skills/engineering/kernel-prompt/*.md); this script
+// only symlinks the skill into the local harness directories or pulls the
+// latest version via npm.
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+const PKG = "@codegiveness/kernel-prompt";
+const SKILL_NAME = "kernel-prompt";
+
+// Resolve the skill source relative to this bin file's installed location.
+// npm installs the package so that bin/kernel-prompt.mjs sits at <pkg-root>/bin/.
+const PKG_ROOT = resolve(dirname(new URL(import.meta.url).pathname), "..");
+const SKILL_SRC = join(PKG_ROOT, "skills", "engineering", SKILL_NAME);
+
+const DESTS = [
+  join(homedir(), ".claude", "skills"),
+  join(homedir(), ".agents", "skills"),
+];
+
+function linkSkill() {
+  if (!existsSync(SKILL_SRC)) {
+    console.error(`error: skill source not found at ${SKILL_SRC}`);
+    console.error("       the npm install may be corrupt; reinstall with:");
+    console.error(`       npm install -g ${PKG}`);
+    process.exit(1);
+  }
+
+  for (const dest of DESTS) {
+    // Bail if dest is itself a symlink into the package — would pollute the install.
+    if (existsSync(dest)) {
+      try {
+        const resolved = realpathSync(dest);
+        if (resolved.startsWith(PKG_ROOT)) {
+          console.error(`error: ${dest} is a symlink into the package (${resolved}).`);
+          console.error(`       Remove it (rm "${dest}") and re-run.`);
+          process.exit(1);
+        }
+      } catch {
+        // Not a symlink, or unreadable — proceed.
+      }
+    }
+
+    mkdirSync(dest, { recursive: true });
+    const target = join(dest, SKILL_NAME);
+
+    if (existsSync(target) || isSymlink(target)) {
+      try { rmSync(target, { recursive: true, force: true }); } catch {}
+    }
+
+    try {
+      symlinkSync(SKILL_SRC, target);
+      console.log(`linked ${SKILL_NAME} -> ${SKILL_SRC} (${dest})`);
+    } catch (err) {
+      console.error(`warn: could not link into ${dest}: ${err.message}`);
+    }
+  }
+}
+
+function isSymlink(p) {
+  try { readlinkSync(p); return true; } catch { return false; }
+}
+
+function update() {
+  console.log(`Updating ${PKG}...`);
+  try {
+    execSync(`npm install -g ${PKG}@latest`, { stdio: "inherit" });
+    console.log(`✅ ${PKG} updated.`);
+  } catch (err) {
+    console.error(`❌ npm install failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+const cmd = process.argv[2];
+
+switch (cmd) {
+  case "install":
+  case "link":
+    linkSkill();
+    break;
+  case "update":
+    update();
+    break;
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(`kernel-prompt — install or update the kernel-prompt skill
+
+usage:
+  kernel-prompt install   symlink the skill into ~/.claude/skills and ~/.agents/skills
+  kernel-prompt update    pull the latest version via npm
+  kernel-prompt help      show this help
+`);
+    break;
+  default:
+    console.error(`unknown command: ${cmd}`);
+    console.error("run `kernel-prompt help` for usage.");
+    process.exit(2);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@codegiveness/kernel-prompt",
+  "version": "0.1.0",
+  "description": "Kernel — a prompt stripped to what works. Six cuts that turn a vague request into a prompt that lands on first try.",
+  "license": "MIT",
+  "author": "codegiveness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codegiveness/kernel-prompt.git"
+  },
+  "homepage": "https://github.com/codegiveness/kernel-prompt",
+  "bugs": {
+    "url": "https://github.com/codegiveness/kernel-prompt/issues"
+  },
+  "keywords": [
+    "prompt-engineering",
+    "kernel",
+    "prompt",
+    "skill",
+    "agent",
+    "claude-code",
+    "opencode",
+    "codex",
+    "refinement"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "kernel-prompt": "bin/kernel-prompt.mjs"
+  },
+  "files": [
+    "skills/",
+    "bin/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "changeset": "changeset",
+    "version": "changeset version"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.30.0"
+  },
+  "packageManager": "npm@10.9.4"
+}

package/skills/engineering/kernel-prompt/EXAMPLE.md

@@ -0,0 +1,82 @@
+# Worked example
+
+Disclosed reference for [`kernel-prompt`](SKILL.md). A full pass: grounding, combining a multi-goal request into one prompt, the six-letter pass, and the exhaustive vague-phrasing sweep with per-clause verdicts.
+
+## Input (vague, multi-goal request)
+
+> Our auth service has a token refresh bug — users get logged out. Fix it, add a test that catches the regression, and update the runbook so on-call knows what to do.
+
+## Grounding
+
+Input references "auth service," "token refresh," and "runbook" — all vague. Explored the codebase and pinned each to a concrete symbol:
+
+- "token refresh bug" → `refreshToken` (src/auth/tokens.ts:42)
+- "users get logged out" → `TokenStore` (src/auth/store.ts:15) drops sessions on refresh failure
+- "runbook" → `docs/runbooks/auth.md`
+
+## Combining vs. chaining
+
+Three sub-goals: fix, test, docs. Test whether they combine:
+- Feed linearly? Yes — fix first, then test the fix, then document the fix.
+- Share context + constraints + verify? Yes — same auth module, same bug.
+- One deliverable? Yes — one PR (code + test + doc update).
+
+→ Combine into one prompt.
+
+## The KERNEL pass
+
+**K — Keep it simple.**
+- _Before:_ "Fix the token refresh bug, add a regression test, update the runbook"
+- _After:_ "Fix the token refresh bug in `refreshToken` (src/auth/tokens.ts:42), add a test that reproduces the bug before the fix, and update `docs/runbooks/auth.md` with the symptom and resolution."
+
+**E — Easy to verify.**
+- _Before:_ (none)
+- _After:_ "Test fails before the fix, passes after. Runbook entry has Symptom, Cause, Fix, Verification sections."
+
+**R — Reproducible.**
+- _unchanged_ — no temporal references in the input.
+
+**N — Narrow scope.**
+- _unchanged_ — combined into one deliverable (one PR). Sub-goals feed linearly and share context.
+
+**E — Explicit constraints.**
+- _Before:_ (none)
+- _After:_ "TypeScript strict, no `as any`. Test via `bun test`. Runbook update under 200 words per section."
+
+**L — Logical structure.**
+- _Before:_ one sentence
+- _After:_ one paragraph carrying context, task, constraints, format, and verify as flowing prose (below)
+
+## Drafted prompt (before sweep)
+
+```
+`refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh, breaking `TokenStore` (src/auth/store.ts:15); patch it so refresh stops dropping sessions, add a `bun test` regression that fails before the fix and passes after, and update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each), shipping as one PR — TypeScript strict, no `as any`.
+```
+
+## Vague-phrasing sweep
+
+Numbered list, one row per content clause, every clause in the paragraph:
+
+1. "`refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh" — same file, same bug. **Passes.**
+2. "breaking `TokenStore` (src/auth/store.ts:15)" — same file, same role. **Passes.**
+3. "patch it so refresh stops dropping sessions" — two readers would diverge: one patches the specific line, another redesigns the refresh flow. **Fails** — applying **Name the operation**: "patch `refreshToken` so it stops dropping sessions on refresh failure."
+4. "add a `bun test` regression that fails before the fix and passes after" — same operation, same tool, checkable criterion. **Passes.**
+5. "update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each)" — same file, same scope, concrete limit. **Passes.**
+6. "shipping as one PR — TypeScript strict, no `as any`" — same deliverable shape, same constraints. **Passes.**
+
+One clause reformulated (clause 3). Re-sweep the replacement: "patch `refreshToken` so it stops dropping sessions on refresh failure" — two readers would both modify `refreshToken` with the same target behavior (no session drop). Same kind (code patch), same coverage (the specific function). **Passes.**
+
+## Final kernel'd prompt (after sweep)
+
+```
+`refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh, breaking `TokenStore` (src/auth/store.ts:15); patch `refreshToken` so it stops dropping sessions on refresh failure, add a `bun test` regression that fails before the fix and passes after, and update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each), shipping as one PR — TypeScript strict, no `as any`.
+```
+
+## Completion check
+
+1. Every content clause in the paragraph passes the two-reader test, presented as a numbered list with per-clause verdict. One failure reformulated with pattern named. ✓
+2. All six letters have before/after or unchanged with cited reason. ✓
+3. Final prompt matches the L-letter form (one paragraph, all five substances present). ✓
+4. Final paragraph re-swept — no vague terms introduced. ✓
+
+Pass complete.

package/skills/engineering/kernel-prompt/REFORMULATIONS.md

@@ -0,0 +1,38 @@
+# Reformulations
+
+Disclosed reference for [`kernel-prompt`](SKILL.md). When a content clause fails the two-reader test, apply one of the seven patterns below. The table shows concrete examples of each pattern in action.
+
+## Patterns
+
+- **Assign a role** — name who is speaking or acting ("Act as a [specific role]")
+- **Name the lens** — specify the analytical frame ("Analyze through psychology, strategy, positioning")
+- **Set a concrete count** — replace "some" or "a few" with a number ("3 sentences", "5 ideas")
+- **Specify the audience** — name who the output is for ("for someone who already knows the basics")
+- **Name the operation** — replace a vague verb, modifier, or noun with the specific action ("Break this down", "Challenge this idea")
+- **Anchor to a real objection** — ground persuasion in a specific counterargument ("using this real objection: [X]")
+- **Add a structural constraint** — require a hook, format, or preservation rule ("with a hook in line 1")
+
+## Examples
+
+Each row shows a vague clause and its specific replacement. Rows marked † are marketing-specific examples that illustrate the pattern, not universal reformulations.
+
+| Vague | Specific | Pattern |
+|---|---|---|
+| Explain it to me | Act as a [specific role] | Assign a role |
+| Give me information about… | Analyze this through psychology, strategy, and positioning | Name the lens |
+| What is it? | Analyze this through non-obvious angles — cost, risk, timing | Name the lens |
+| Make me a summary | Summarize this through the lens of trade-offs and alternatives | Name the lens |
+| Content ideas | Write it for someone who already knows the basics | Specify the audience |
+| Strategies for… | Break this concept down | Name the operation |
+| Tips for… | Challenge this idea | Name the operation |
+| Examples | Give me 3 examples with the pattern explained | Set a concrete count |
+| Benefits of… | Analyze the benefits through the lens of trade-offs and alternatives | Name the lens |
+| Make me more professional † | Make sure my client understands it in 5 seconds | Add a structural constraint |
+| Improve it | Score this against 3 named criteria: [your criteria] | Set a concrete count |
+| Make it shorter | Summarize it in 3 sentences without losing the main point | Set a concrete count |
+| Make it sound natural | Write it the way I speak, without jargon | Name the operation |
+| Write a post about… † | Write a post for [client] with a hook in line 1 | Specify the audience |
+| I need content ideas † | Give me 5 Reel ideas with the hook and format | Set a concrete count |
+| Fix this | Fix spelling and rhythm without changing my style | Name the operation |
+| Make it more persuasive | Rewrite this to overcome this real objection: [X] | Anchor to a real objection |
+| Write me a caption † | Give me 3 versions and tell me which one you recommend | Set a concrete count |

package/skills/engineering/kernel-prompt/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: kernel-prompt
+description: Kernel a prompt — refine or compose it into one paragraph that lands on first try. Use when the user wants to refine or compose a prompt. Other skills reach this when they need a kernel'd prompt as input.
+---
+
+A **kernel** is a prompt stripped to what works. This skill runs the KERNEL pass — six cuts that turn a vague request into a prompt that lands on first try.
+
+## Branches
+
+Two branches, same six letters, different input material:
+- **Refine** — input is an existing prompt. The "before" for each letter is that prompt's current state.
+- **Compose** — input is a task description. The "before" for each letter is what the task description provides for that letter; if it provides nothing, record _absent_ as the before.
+
+## Grounding
+
+Before the pass, pin vague input terms to concrete symbols. When the input references a codebase, system, or API, explore it first (read files, query the index) and record a short grounding inventory: each vague term → the concrete symbol, file, or field it maps to. The pass writes the paragraph against this grounded vocabulary, not the user's original phrasing. Skip grounding only when the input is fully self-contained.
+
+## Combining vs. chaining
+
+When the input spans multiple sub-goals, the default is to **combine** them into one prompt. Combine when the sub-goals:
+- Feed linearly (output of one is input to the next, in order).
+- Share the same context, constraints, and verify criteria.
+- Produce one deliverable (one document, one script, one spec).
+
+Split into a chain only when sub-goals produce different output types (a script vs. a doc) or need independent execution with different constraints. See [Chaining](#chaining).
+
+## The KERNEL pass
+
+Run each letter in order. For each, produce a before/after note, or mark _unchanged_ with a reason that cites what's already in the prompt satisfying that letter (e.g., "unchanged — goal already stated as single sentence in line 1").
+
+**K — Keep it simple.** Strip to one clear goal. Cut context that doesn't serve it. If no goal is recoverable from the input, ask the user for one before continuing — do not invent one. This is the one legitimate pause point in the pass.
+- _Before:_ "I need help writing something about Redis"
+- _After:_ "Write a technical tutorial on Redis caching"
+
+**E — Easy to verify.** Attach a checkable success criterion. "Engaging" is not checkable; "3 code examples" is. If you can't verify success, the prompt can't deliver it.
+
+**R — Reproducible.** Remove temporal references ("current trends", "latest best practices"). Pin specific versions and exact requirements. The prompt should work next month.
+
+**N — Narrow scope.** One prompt, one deliverable. If the request genuinely cannot combine (see [Combining vs. chaining](#combining-vs-chaining)), split — see [Chaining](#chaining).
+
+**E — Explicit constraints.** List the exact scope: allowed libraries, max function length, output type, target audience. Keep a prohibition only as a hard guardrail you cannot phrase positively, and pair it with the positive target.
+- _Before:_ "Python code"
+- _After:_ "Python stdlib only; functions under 20 lines; output to stdout"
+
+**L — Logical structure.** Weave the prompt into **one paragraph** of prose carrying all five substances — context, task, constraints, format, verify — as flowing sentences joined by connectors (`;`, `,`, `and`).
+- _Before:_ scattered labeled lines — `Context: …` / `Task: …` / `Constraints: …`
+- _After:_ one paragraph — e.g. "`refreshToken` (src/auth/tokens.ts:42) drops sessions on refresh; patch it, add a failing-then-passing `bun test`, and update `docs/runbooks/auth.md` — TypeScript strict, no `as any`, one PR."
+
+## Vague-phrasing sweep
+
+After the six letters, present the sweep as a numbered list — one row per content clause across the paragraph (the same five substances, now as sentences), every clause, not a representative sample. Each row states the clause and a pass/fail verdict. Apply the two-reader test per clause: would two different readers produce outputs matching in type and scope? "Matching" means same output kind (both produce a Python script, not one script and one prose) and same coverage (both cover the same scope, not one comprehensive and one partial). It does not mean byte-identical implementations.
+
+For each failing row, replace the vague clause using a pattern from [`REFORMULATIONS.md`](REFORMULATIONS.md), and name the pattern in the row: "Fails — applying **[Pattern Name]**: [replacement]". No silent reformulation.
+
+If no clause fails, state "No reformulations needed" — this is the common outcome when the paragraph is well-constructed and the input was grounded.
+
+## Completion
+
+The pass is done when all four hold:
+1. Every content clause in the paragraph passes the two-reader test, presented as a numbered list with a per-clause verdict. Each failing clause names the REFORMULATIONS.md pattern applied.
+2. All six letters have a before/after note or _unchanged_ with a cited reason.
+3. The final prompt matches the L-letter form (one paragraph, all five substances present).
+4. The final paragraph passes its own two-reader sweep (re-swept after reformulation) — no vague verbs, vague nouns, or unscoped counts introduced in the output.
+
+## Chaining
+
+Split a task into a chain only when combining fails the test in [Combining vs. chaining](#combining-vs-chaining). Each prompt in the chain gets its own KERNEL pass.
+
+Chain format: numbered list of prompts, each noting its dependency on the prior (`1. → 2. (feeds output of 1) → 3. (feeds output of 2)`).
+
+Re-pass rule: treat each prior prompt's output as input to the next. Re-run the vague-phrasing sweep on your own output before passing it forward — do not propagate vague terms across the chain.
+
+## Worked example
+
+See [`EXAMPLE.md`](EXAMPLE.md) for a full pass: grounding, combining a multi-goal request into one prompt, the six-letter pass, and the exhaustive vague-phrasing sweep with per-clause verdicts.