paperthin 0.5.0 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,12 +1,19 @@
-{
-  "name": "paperthin",
-  "description": "Plain-Markdown skills that turn old engineering wisdom into reflexes your agent reaches for on its own — on any agent.",
-  "skills": [
-    "./skills/single/re0",
-    "./skills/single/re0-git",
-    "./skills/single/shower",
-    "./skills/single/tasting",
-    "./skills/cross/ssotchk",
-    "./skills/cross/ssotize"
-  ]
-}
+{
+  "name": "paperthin",
+  "description": "Plain-Markdown skills that turn old engineering wisdom into reflexes your agent reaches for on its own — on any agent.",
+  "skills": [
+    "./skills/depth/factchk",
+    "./skills/depth/mandela",
+    "./skills/depth/re0",
+    "./skills/depth/re0-git",
+    "./skills/depth/hate",
+    "./skills/depth/shower",
+    "./skills/depth/sip",
+    "./skills/breadth/ssotchk",
+    "./skills/breadth/ssotize",
+    "./skills/coil/retro",
+    "./skills/coil/scratch",
+    "./skills/coil/flywheel",
+    "./skills/coil/nba"
+  ]
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Validate the skill catalog
+        run: bash scripts/validate-skills.sh

package/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+permissions:
+  contents: write     # create the GitHub Release
+  id-token: write     # npm provenance via OIDC
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Validate the skill catalog
+        run: bash scripts/validate-skills.sh
+
+      - name: Verify tag matches package.json
+        run: |
+          PKG=$(node -p "require('./package.json').version")
+          TAG=${GITHUB_REF_NAME#v}
+          test "$PKG" = "$TAG" || { echo "tag $TAG != package.json $PKG"; exit 1; }
+
+      - name: Publish to npm (public, with provenance)
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "PaperThin ${GITHUB_REF_NAME#v}" --notes-from-tag

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # PaperThin
 
-The guide for authoring these skills — and itself a skill artifact, so `re0` it when it drifts. The shipped catalog is [README](./README.md).
+PaperThin is an agent-agnostic suite of plain-Markdown skills that keep an artifact **clean and true** — hygiene reflexes an agent reaches for on its own. This is the guide for authoring them — and itself a skill artifact, so `re0` it when it drifts. Every skill it names below — `re0`, `factchk`, `hate`, … — is defined in the shipped catalog, the [README](./README.md).
 
 ## Philosophy
 
-- **Trust the artifact, not the author.** A skill exists to make work read true to someone who wasn't there. The maker's in-session mind is the worst judge of whether it does — so a skill either re-derives the work from what's true now, or imports outside eyes to test it.
+- **Trust the artifact, not the author.** A skill exists to make work read true to someone who wasn't there — *clear* (does it read?) and *correct* (is what it claims real?). The maker's in-session mind is the worst judge of either — so a skill either re-derives the work from what's true now, or imports outside eyes to test it.
 - **Single source of truth.** One fact lives in one place; everything else references it by name. Skills compose by naming each other in prose — never by copying content or reaching into another skill's files. Shared material lives in its owning skill; others point to it.
 - **Restraint.** Change only what genuinely improves — a pass that finds nothing to improve changes nothing. The enemy is slop (noise, duplication, padding), not addition.
 - **Recursive.** Every skill is general enough to use *while building the skills*, so we maintain the skills with the skills, and each pass is audited and refined by the tools it ships. Treat that loop as the point.
@@ -15,12 +15,34 @@ The guide for authoring these skills — and itself a skill artifact, so `re0` i
 skills/<perspective>/<name>/SKILL.md
 ```
 
-Group by **artifact perspective** — which is the suite's two vectors made physical:
+Topic domains belong in separate plugins, so within a plugin the only durable cut is **perspective**. One skill = one directory with a `SKILL.md`.
+
+That cut is two orthogonal axes, **cardinality × time**:
+
+```text
+skills/
+├── depth/     one artifact · now
+│              refine or verify the thing in hand
+│              re0 · re0-git · shower · sip · factchk · mandela · hate
+│
+├── breadth/   many artifacts · now
+│              reconcile one truth across files and platforms
+│              ssotchk · ssotize
+│
+├── coil/      one project · across iterations
+│              carry learning between build cycles
+│              retro · scratch · flywheel · nba
+│
+└── mesh/      many minds · across rounds
+               converge independent views into consensus
+               (reserved · v0.8)
+```
+
+**File by trigger-scope, not by what a skill invokes.** A skill lives where the work it *triggers or emits* ranges, even when it orchestrates skills from other folders — `sip` gates one finished deliverable, so it's `depth/`, though its check runs a cross-file `ssotchk`.
 
-- `single/` — **depth**: refine or verify the one artifact in hand (`re0`, `re0-git`, `shower`, `tasting`).
-- `cross/` — **breadth**: reconcile one truth across many artifacts and platforms (`ssotchk`, `ssotize`).
+Reach for `breadth/` to *establish* order (legacy refactor, knowledge-base build, fresh scaffolding); once a fact is cleanly SSOT'd, *maintain* it with `re0` rather than re-consolidating. Keep drafts and retired skills out of the README and `plugin.json`.
 
-Reach for `cross/` to *establish* order (legacy refactor, knowledge-base build, fresh scaffolding); once a fact is cleanly SSOT'd, *maintain* it with `re0` rather than re-consolidating. Topic domains belong in separate plugins, so within a plugin the only durable cut is perspective. One skill = one directory with a `SKILL.md`; keep drafts and retired skills out of the README and `plugin.json`.
+**Name it for the reflex it fires** — a plain real word (`shower`, `sip`) or a tight compression of a real term (`re0`, `ssotchk`, `ssotize`); a stranger should half-guess what it does from the name alone, so no opaque coinage. A self-evident metaphor-noun is allowed only as a deliberate exception, when its own intuition carries it.
 
 ## SKILL.md format
 
@@ -28,6 +50,7 @@ Reach for `cross/` to *establish* order (legacy refactor, knowledge-base build,
 ---
 name: <kebab-name>            # matches the directory and the invocation
 description: "<trigger-rich one-liner>"
+# disable-model-invocation: true   ← user-invoked skills only
 ---
 
 <one line: what the skill does>
@@ -42,7 +65,14 @@ description: "<trigger-rich one-liner>"
 
 Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md).
 
-Default to model-invoked. Make a skill user-invoked only when the model should never reach it on its own — its trigger is a deliberate, human-decided action (commit, push, publish, deploy), or its mere presence in reach would bias the agent toward one. A user-invoked skill can't be composed, so it also stays out of `tasting`. Today only `re0-git` qualifies: it cleans a commit's message, and committing is human-decided.
+Default to model-invoked. Make a skill user-invoked only when the model should never reach it on its own — its trigger is a deliberate, human-decided action (commit, push, publish, deploy), or its mere presence in reach would bias the agent toward one. A user-invoked skill can't be composed, so it also stays out of `sip`. Two qualify today: `re0-git` (it cleans a commit's message — committing is human-decided) and `hate` (a hate-it reflex always in the agent's reach would bias it toward demolition).
+
+## Conventions
+
+Shared rules a skill references rather than restates:
+
+- **edit-safety** (any mutating skill — `re0`, `ssotize`, `scratch`): a find-replace that could match nothing must **assert its target exists** (report a MISS, never silently no-op); byte-level tools corrupt multibyte text, so mutate with a **unicode-safe** pass (`PYTHONUTF8=1`, stdout reconfigured to UTF-8); never **blanket-replace a single target whose right replacement is positional** (the same token mapping to different replacements per location) — decide per occurrence, never a blind sweep; and make large *structural* moves with a script, not by retyping.
+- **negatives-as-corpus**: "cut" means **move-to-archive, never delete** — pruned and failed branches are assets, not waste.
 
 ## Shipping
 
@@ -52,7 +82,7 @@ Before committing:
 2. **README** lists it — grouped Model-/User-invoked, each linked to its `SKILL.md`.
 3. **plugin.json** registers its path.
 4. **package.json** bumps version (new skill = minor; fix/docs = patch); `keywords` stay grouped logically.
-5. Run **`tasting`** — `shower` the artifact, `ssotchk` the repo, `re0` the docs.
+5. Run **`sip`** — `shower` the artifact, `ssotchk` the repo, `re0` the docs.
 
 Commit messages: Conventional Commits, one bullet per real change — no padding, no mechanical trivia, no co-author tags. `re0-git` cleans a drifted message back to its essence, in the author's own style.
 

package/README.md

@@ -1,132 +1,194 @@
-<div align="center">
-
-# PaperThin
-
-<img src="https://raw.githubusercontent.com/LilMGenius/paperthin/main/assets/banner.svg" alt="PaperThin — Trust the artifact, not the author." width="820">
-
-Plain-Markdown skills that turn old engineering wisdom into reflexes your agent reaches for on its own — on any agent: Claude Code, Codex, Cursor, Antigravity, Grok-Build, Hermes, OpenClaw, Pi, etc.
-
-[Quickstart](#quickstart-15-seconds) · [Reference](#reference) · [The Problem](#the-problem) · [The Fixes](#the-fixes) · [Credits](#credits)
-
-</div>
-
----
-
-## Quickstart (15 seconds)
-
-1. **Install** for every agent you use:
-   ```bash
-   npx skills@latest add LilMGenius/paperthin --global --agent '*'
-   ```
-2. **Run it elevated** so the skills are symlinked (they auto-update), not copied.
-3. **Use them** — model-invoked, so your agent reaches for them on its own; or call one by name, like `/re0`.
-
-**Not sure?** Paste that command into whatever agent you're using and just say "set this up for me" — it'll do the rest.
-
-## Reference
-
-### Model-invoked — your agent reaches for these on its own
-| Skill | Scope | What it does |
-|---|---|---|
-| ♻️ **[re0](./skills/single/re0/SKILL.md)** | one artifact | Rewrite a drifted artifact into a clean v0 — not another patch |
-| 🚿 **[shower](./skills/single/shower/SKILL.md)** | one artifact | Cold-read it with fresh, zero-context eyes — does it stand on its own? *(read-only)* |
-| 🔎 **[ssotchk](./skills/cross/ssotchk/SKILL.md)** | many artifacts | Find where one fact is scattered or duplicated; name the canonical source *(read-only)* |
-| 🧲 **[ssotize](./skills/cross/ssotize/SKILL.md)** | many artifacts | Consolidate it into one home and point the rest at it |
-| 🍴 **[tasting](./skills/single/tasting/SKILL.md)** | your output | After any change, auto-runs `shower` + `ssotchk` + `re0` on it |
-
-### User-invoked — you run these yourself
-| Skill | Scope | What it does |
-|---|---|---|
-| 🧾 **[re0-git](./skills/single/re0-git/SKILL.md)** | one commit | Rewrite a finished commit's message into a clean v0 so `git log` alone hands off |
-
-## The Problem
-
-**Most agent skills are slop.**
-
-Point an agent at a goal and it **adds** — more files, more options, more "helpful" boilerplate. Adding looks like progress, and nothing ever makes it go back and delete.
-
-> [!WARNING]
-> Repeat that across a project and you get the familiar AI-generated toolkit: near-duplicate skills, dead settings, a README that says the same thing three times. Plausible, busy, and quietly unmaintainable.
-
-These skills bet the other way — **every one of them removes:**
-
-- `re0` rewrites a draft into a clean v0 instead of patching it,
-- `ssotchk` / `ssotize` collapse the same fact scattered across files,
-- `shower` cuts whatever a stranger can't follow,
-- `tasting` runs all of it on your own output, automatically.
-
-> [!TIP]
-> The hard part isn't adding features — it's restraint. A pass that finds nothing to improve changes nothing. **That restraint is the product.**
-
-## The Fixes
-
-**Each is a well-worn principle, made automatic.**
-
-### #1 — Artifacts rot
-Edit a doc one piece at a time across a session and it bloats: stale deltas, duplicated noise, changelog scars. Patching on top just preserves the rot.
-
-**The fix → `re0`:** rewrite the artifact as a clean v0, as if it were the first version.
-
-> *Prior art: the Boy Scout Rule — "leave it cleaner than you found it" (Robert C. Martin, [Clean Code](https://www.informit.com/articles/article.aspx?p=1235624&seqNum=6), 2008). `re0` goes further: rewrite, don't just tidy.*
-
-<details>
-<summary><b>[PROOF]</b></summary>
-
-- **Setup** — we asked `re0` to refresh these docs once more, but they were already at v0.
-- **Result** — it found nothing to improve and left every line of prose untouched.
-- **So** — a tool that does nothing when nothing is wrong never bloats your repo: these skills remove noise, they never add it.
-</details>
-
-### #2 — You go blind to your own work
-After a long session you're the one person who *can't* read your own work straight: you know too much, so your brain quietly fills every gap and the holes turn invisible.
-
-**The fix → `shower`:** hand a stranger who never saw your session only the artifact, and ask "does this actually make sense?"
-
-> *Prior art: [egoless programming](https://en.wikipedia.org/wiki/Egoless_programming) — you can't review your own work objectively; someone else must (Gerald Weinberg, 1971). Here, that someone is a context-free sub-session.*
-
-<details>
-<summary><b>[PROOF]</b></summary>
-
-- **Setup** — we handed `shower` its own spec, to a sub-session with zero context, holding only the file.
-- **Result** — in minutes it found three bugs the author had missed:
-  - a step that hinted the answer it should hide,
-  - a path that leaked spoiler files,
-  - a scope too vague to act on.
-- **So** — a skill that catches its own bugs can catch yours.
-</details>
-
-### #3 — The same fact ends up everywhere
-A timeout value, a decision, a status — copied into a README, a doc, a ticket, and a Slack thread. The copies drift, and now no one knows which is true.
-
-**The fix → `ssotchk` + `ssotize`:** find the scatter, name the canonical source, then consolidate and point the rest at it.
-
-> *Prior art: [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) — one fact, one authoritative home (Hunt & Thomas, The Pragmatic Programmer, 1999).*
-
-### #4 — "Remember to verify" never fires
-A guideline buried in docs won't trigger in a brand-new session — exactly when author bias is highest.
-
-**The fix → `tasting`:** the moment you finish something, it runs `shower`, `ssotchk`, and `re0` on your output, automatically.
-
-> *Prior art: [dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) — eat your own dog food (Microsoft, 1988). Taste your own cooking before you serve it.*
-
-### #5 — Your session doesn't travel; the git log does
-Your session is stuck where it ran — this agent, this account, this machine. A teammate or another agent can't load the context your work happened in.
-
-**The fix → `re0-git`:** clean a finished commit's message so `git log` — the one thing every environment shares — carries the handoff, and anyone picks up from the log alone.
-
-<details>
-<summary><b>[PROOF]</b></summary>
-
-- **Setup** — `re0-git`'s very first target was its own release commit.
-- **Result** — dogfooding it surfaced two faults, both fixed:
-  - a message padded with trivia,
-  - a spec that preached "no redundancy" while repeating itself.
-- **So** — its first cleanup was after itself.
-</details>
-
-## Credits
-
-- **Built on** [mattpocock/skills](https://github.com/mattpocock/skills) (MIT) — its architecture and philosophy.
-- **Not a fork** — these are [LilMGenius](https://github.com/LilMGenius)'s own, non-overlapping workflows.
-- **Vendored verbatim** — a few shared building blocks, kept as-is with per-source attribution in [NOTICE](./NOTICE).
-- **Authoring guide** — conventions and philosophy live in [CLAUDE.md](./CLAUDE.md).
+<div align="center">
+
+# PaperThin
+
+<img src="https://raw.githubusercontent.com/LilMGenius/paperthin/main/assets/banner.svg" alt="PaperThin — Trust the artifact, not the author." width="820">
+
+Plain-Markdown skills that turn old engineering wisdom into reflexes your agent reaches for on its own — on any agent: Claude Code, Codex, Cursor, Antigravity, Grok-Build, Hermes, OpenClaw, Pi, etc.
+
+[Quickstart](#quickstart-15-seconds) · [Index](#index) · [The Map](#the-map) · [The Problem](#the-problem) · [The Fixes](#the-fixes) · [Credits](#credits)
+
+</div>
+
+---
+
+## Quickstart (15 seconds)
+
+1. **Install** for every agent you use:
+   ```bash
+   npx skills@latest add LilMGenius/paperthin --global --agent '*'
+   ```
+2. **Run it elevated** so the skills are symlinked (they auto-update), not copied.
+3. **Use them** — model-invoked, so your agent reaches for them on its own; or call one by name, like `/re0`.
+
+**Not sure?** Paste that command into whatever agent you're using and just say "set this up for me" — it'll do the rest.
+
+## Index
+
+### Model-invoked — your agent reaches for these on its own
+| Skill | Scope | What it does |
+|---|---|---|
+| ♻️ **[re0](./skills/depth/re0/SKILL.md)** | one artifact | Rewrite a drifted artifact into a clean v0 — not another patch |
+| 🚿 **[shower](./skills/depth/shower/SKILL.md)** | one artifact | Cold-read it with fresh, zero-context eyes — does it stand on its own? *(read-only)* |
+| 🔬 **[factchk](./skills/depth/factchk/SKILL.md)** | one claim | Verify a reality-grounded claim against sources, both directions — could the absurd be real, the obvious false? *(read-only → fix)* |
+| 🧪 **[mandela](./skills/depth/mandela/SKILL.md)** | one eval | Audit a validation for leakage — does outside ground-truth actually enter? Walks 8 patterns *(read-only)* |
+| 🔎 **[ssotchk](./skills/breadth/ssotchk/SKILL.md)** | many artifacts | Find where one fact is scattered or duplicated; name the canonical source *(read-only)* |
+| 🧲 **[ssotize](./skills/breadth/ssotize/SKILL.md)** | many artifacts | Consolidate it into one home and point the rest at it |
+| 🧭 **[retro](./skills/coil/retro/SKILL.md)** | one project, across iterations | Extract lessons, anti-patterns, gates, and vocabulary from a finished or failed cycle |
+| 🧱 **[scratch](./skills/coil/scratch/SKILL.md)** | one project, across iterations | Restart from v0 while preserving only proven lessons, contracts, gates, and negative corpus |
+| 🌀 **[flywheel](./skills/coil/flywheel/SKILL.md)** | one project, across iterations | Run build → QA → retro → scratch cycles without mistaking code accumulation for learning |
+| 🎯 **[nba](./skills/coil/nba/SKILL.md)** | one project, across iterations | Read the live cycle state and return the single next best action, not a menu *(read-only)* |
+| 🥄 **[sip](./skills/depth/sip/SKILL.md)** | your output | After any change, auto-runs `shower` + `ssotchk` + `re0` on it |
+
+### User-invoked — you run these yourself
+| Skill | Scope | What it does |
+|---|---|---|
+| 🧾 **[re0-git](./skills/depth/re0-git/SKILL.md)** | one commit | Rewrite a finished commit's message into a clean v0 so `git log` alone hands off |
+| 😈 **[hate](./skills/depth/hate/SKILL.md)** | one plan | Refuse to be nice to it — the one objection that could kill it + the cheapest test |
+
+## The Map
+
+**How many artifacts, and across how much time?**
+
+Two axes — **cardinality × time** — carve four regions.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/LilMGenius/paperthin/main/assets/map.svg" alt="The PaperThin map: a two-by-two matrix. Horizontal axis cardinality (one, then many); vertical axis time (now, then across iterations); four regions. Top-left, depth: one artifact, now; is this one thing clean and true? Top-right, breadth: many artifacts, now; is one truth consistent everywhere? Bottom-left, coil: one project, across iterations; did each pass teach the next? Bottom-right, mesh: many minds, across rounds; does the crowd converge on truth?" width="820">
+</div>
+
+## The Problem
+
+**Most agent skills are slop.**
+
+Point an agent at a goal and it **adds** — more files, more options, more "helpful" boilerplate. Adding looks like progress, and nothing ever makes it go back and delete.
+
+> [!WARNING]
+> Repeat that across a project and you get the familiar AI-generated toolkit: near-duplicate skills, dead settings, a README that says the same thing three times. Plausible, busy, and quietly unmaintainable.
+
+These skills bet the other way — **every one of them removes:**
+
+- `re0` rewrites a draft into a clean v0 instead of patching it,
+- `ssotchk` / `ssotize` collapse the same fact scattered across files,
+- `shower` cuts whatever a stranger can't follow,
+- `retro` / `scratch` preserve the lesson and let the wrong build die,
+- `sip` runs all of it on your own output, automatically.
+
+> [!TIP]
+> The hard part isn't adding features — it's restraint. A pass that finds nothing to improve changes nothing. **That restraint is the product.**
+
+## The Fixes
+
+<!-- Fixes follow the lifecycle of a piece of work, not the skill list: first keep it clean (draft → read fresh → reconcile across files → automate → ship), then keep it true (a single claim → a validation → the whole plan). Slot any new fix in by where it acts in that arc. -->
+
+**Each is a well-worn principle, made automatic.**
+
+### #1 — Artifacts rot
+Edit a doc one piece at a time across a session and it bloats: stale deltas, duplicated noise, changelog scars. Patching on top just preserves the rot.
+
+**The fix → `re0`:** rewrite the artifact as a clean v0, as if it were the first version.
+
+> *Prior art: the Boy Scout Rule — "leave it cleaner than you found it" (Robert C. Martin, [Clean Code](https://www.informit.com/articles/article.aspx?p=1235624&seqNum=6), 2008). `re0` goes further: rewrite, don't just tidy.*
+
+<details>
+<summary><b>[PROOF]</b></summary>
+
+- **Setup** — we asked `re0` to refresh these docs once more, but they were already at v0.
+- **Result** — it found nothing to improve and left every line of prose untouched.
+- **So** — a tool that does nothing when nothing is wrong never bloats your repo: these skills remove noise, they never add it.
+</details>
+
+### #2 — You go blind to your own work
+After a long session you're the one person who *can't* read your own work straight: you know too much, so your brain quietly fills every gap and the holes turn invisible.
+
+**The fix → `shower`:** hand a stranger who never saw your session only the artifact, and ask "does this actually make sense?"
+
+> *Prior art: [egoless programming](https://en.wikipedia.org/wiki/Egoless_programming) — you can't review your own work objectively; someone else must (Gerald Weinberg, 1971). Here, that someone is a context-free sub-session.*
+
+<details>
+<summary><b>[PROOF]</b></summary>
+
+- **Setup** — we handed `shower` its own spec, to a sub-session with zero context, holding only the file.
+- **Result** — in minutes it found three bugs the author had missed:
+  - a step that hinted the answer it should hide,
+  - a path that leaked spoiler files,
+  - a scope too vague to act on.
+- **So** — a skill that catches its own bugs can catch yours.
+</details>
+
+### #3 — The same fact ends up everywhere
+A timeout value, a decision, a status — copied into a README, a doc, a ticket, and a Slack thread. The copies drift, and now no one knows which is true.
+
+**The fix → `ssotchk` + `ssotize`:** find the scatter, name the canonical source, then consolidate and point the rest at it.
+
+> *Prior art: [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) — one fact, one authoritative home (Hunt & Thomas, The Pragmatic Programmer, 1999).*
+
+### #4 — "Remember to verify" never fires
+A guideline buried in docs won't trigger in a brand-new session — exactly when author bias is highest.
+
+**The fix → `sip`:** the moment you finish something, it runs `shower`, `ssotchk`, and `re0` on your output, automatically.
+
+> *Prior art: [dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) — eat your own dog food (Microsoft, 1988). Taste your own cooking before you serve it.*
+
+### #5 — Your session doesn't travel; the git log does
+Your session is stuck where it ran — this agent, this account, this machine. A teammate or another agent can't load the context your work happened in.
+
+**The fix → `re0-git`:** clean a finished commit's message so `git log` — the one thing every environment shares — carries the handoff, and anyone picks up from the log alone.
+
+<details>
+<summary><b>[PROOF]</b></summary>
+
+- **Setup** — `re0-git`'s very first target was its own release commit.
+- **Result** — dogfooding it surfaced two faults, both fixed:
+  - a message padded with trivia,
+  - a spec that preached "no redundancy" while repeating itself.
+- **So** — its first cleanup was after itself.
+</details>
+
+> [!NOTE]
+> The five fixes above keep an artifact **clean**. The next three keep it **true** — the same distrust of the author, turned on the reasoning instead of the prose.
+
+### #6 — Your gut isn't a source
+"Plausible," "absurd," "novel" — the least reliable line in any artifact. Human priors fail **both ways**: they exclude the real (desert frogs exist) and normalize the impossible (weightless crates).
+
+**The fix → `factchk`:** verify any reality-grounded claim against external sources, in both directions, before it ships — and flag, don't guess, when you can't reach one.
+
+> *Prior art: [WEIRD bias](https://www.cambridge.org/core/journals/behavioral-and-brain-sciences/article/abs/weirdest-people-in-the-world/BF84F7517D56AFF7B7EB58411A554C17) (Henrich, Heine & Norenzayan, 2010) and the [naive-physics / impetus error](https://www.science.org/doi/10.1126/science.210.4474.1139) (McCloskey, Caramazza & Green, 1980) — intuition misjudges reality in both directions.*
+
+<details>
+<summary><b>[PROOF]</b></summary>
+
+- **Setup** — we ran `factchk` on its own shipped citations, in both directions.
+- **Result** — all held, and it still caught two attribution slips to fix: the famous "what's measured becomes the target" wording is Strathern (1997), not Goodhart; and "McCloskey 1980" is the co-authored *Science* paper, not the 1983 *Scientific American* piece.
+- **So** — a fact-checker that audits its own footnotes will audit yours.
+</details>
+
+### #7 — The eval confirms itself
+A model, a scorer, and a designer can all agree a result is real while no outside ground-truth ever entered the loop — a whole room confidently remembering something that never independently happened.
+
+**The fix → `mandela`:** audit any eval, metric, or experiment against an 8-pattern leakage taxonomy — does external ground-truth enter independently, or is the verifier the designer?
+
+> *Prior art: [Goodhart's law](https://en.wikipedia.org/wiki/Goodhart%27s_law), [data leakage](https://dl.acm.org/doi/10.1145/2382577.2382579) (Kaufman et al., 2012), and [circular analysis](https://www.nature.com/articles/nn.2303) — "double dipping" (Kriegeskorte et al., 2009).*
+
+### #8 — You can't kill your own plan
+You built it, so you defend it. The questions that would break it are exactly the ones you won't ask.
+
+**The fix → `hate`:** refuse to be nice to the plan — return the one load-bearing objection that could kill it and the cheapest experiment that would prove it matters. User-invoked: you point it at a plan deliberately.
+
+> *Prior art: [egoless programming](https://en.wikipedia.org/wiki/Egoless_programming) (Weinberg, 1971 — the same root `shower` cites), hostile review, and fail-fast.*
+
+### #9 — A build can run and still be wrong
+Long agentic builds can produce many working parts while missing the product: panels, routes, screenshots, and tests that prove activity more than value. The mistake is carrying that architecture forward because it cost effort.
+
+**The fix → `retro` + `scratch`:** extract the lesson, anti-pattern, vocabulary, and next gate, then restart from a clean v0 when the foundation is wrong. Keep only what earned reuse.
+
+### #10 — Iterations can spin without learning
+After a disappointing pass, the next move can blur into a dozen plausible threads: patch, rebuild, test more, write docs, add features. That is how projects accumulate surfaces instead of compounding.
+
+**The fix → `flywheel` + `nba`:** run the build → QA → retro → scratch loop, and when the thread is lost, read the state and return one next best action with a clear done-when.
+
+## Credits
+
+- **Built on** [mattpocock/skills](https://github.com/mattpocock/skills) (MIT) — its architecture and philosophy.
+- **Not a fork** — these are [LilMGenius](https://github.com/LilMGenius)'s own, non-overlapping workflows.
+- **Vendored verbatim** — a few shared building blocks, kept as-is with per-source attribution in [NOTICE](./NOTICE).
+- **Authoring guide** — conventions and philosophy live in [CLAUDE.md](./CLAUDE.md).