@erclx/canon 4.0.0

package/claude/skills/setup-plugins/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: setup-plugins
+description: Installs curated community and official Claude Code plugins user-scoped on the current machine via the `claude plugin` CLI. Use when asked to "install plugins", "set up plugins", "install the frontend/design/security/debugging plugins", "provision plugins on this machine", or when setting up Claude Code on a new computer. Do NOT use to install toolkit workflow skills, which load live via `--plugin-dir`. Assumes the `claude` CLI is on PATH.
+---
+
+# Setup plugins
+
+Automates plugin installs by reading the curated catalog, detecting what is already
+installed, and shelling out to the `claude plugin` CLI with `--scope user` so the
+plugins are available in every project on this machine.
+
+Domain-knowledge plugins install once per machine. They are not copied into any
+project. Toolkit workflow skills are a separate concern and load live through
+`--plugin-dir`, so never install those here.
+
+## Guards
+
+- If the `claude` CLI is not on PATH, stop: `❌ claude CLI not found. Install Claude Code first.`
+
+## Read the catalog
+
+Read the curated list from the skill folder. Use `${CLAUDE_SKILL_DIR}`, which
+expands to this skill's own directory, so the path resolves from any project. Never
+invent plugin names or install strings that are not in it.
+
+- `${CLAUDE_SKILL_DIR}/references/plugin-catalog.md`: verified plugins, marketplace sources, and the recommended default set
+
+## Detect what is installed
+
+Run this to skip plugins already present. Do not reinstall an installed plugin.
+
+```bash
+claude plugin list 2>/dev/null || echo "NONE"
+```
+
+## Select
+
+When plugin names are passed as arguments, install exactly those and skip the prompt.
+
+When invoked bare, present the catalog grouped by category with the recommended
+default marked, then ask which to install. Accept a bulk answer:
+
+- `recommended`: the default set from the catalog
+- `all`: every catalog row not already installed
+- a specific list of plugin names
+
+## Preview
+
+Before executing, output:
+
+- **Installed:** plugins already present, skipped
+- **To install:** each chosen plugin with its category and marketplace source
+- **Scope:** `user` (every project on this machine)
+- **Commands:** the exact shell commands to run
+
+## Execute
+
+For each chosen plugin, add its marketplace source if it is not already added, then
+install the plugin user-scoped. Run each install independently so one failure does
+not abort the batch.
+
+```bash
+claude plugin marketplace add <source> 2>/dev/null || true
+claude plugin install <name> --scope user
+```
+
+For a catalog entry listed under "Installs outside the claude plugin CLI", skip the
+marketplace step and run its installer command verbatim instead.
+
+Claude Code's tool permission dialog is the confirmation gate. Do not pause for a
+separate confirmation.
+
+## Response
+
+After execution, report:
+
+- Plugins installed, each with its marketplace
+- Plugins skipped as already installed
+- Any install that failed, with the CLI error
+- A reload note: installed plugins apply on the next session or after `/reload-plugins`
+- A tuning note: if a plugin over-triggers, set `skillOverrides` in settings to `name-only`, `user-invocable-only`, or `off` rather than uninstalling

package/claude/skills/setup-plugins/references/plugin-catalog.md

@@ -0,0 +1,53 @@
+---
+title: Plugin catalog
+description: Curated community and official Claude Code plugins that setup-plugins installs
+---
+
+# Plugin catalog
+
+Curated domain-knowledge plugins the `setup-plugins` skill installs user-scoped.
+Each row is verified to install through the `claude plugin` CLI. This file holds
+only the actionable install data.
+
+## Install data
+
+Add the marketplace source once, then install the plugin by name. The CLI resolves
+the plugin across added marketplaces, so `<name>@<marketplace>` is only needed to
+disambiguate a name that exists in more than one marketplace.
+
+| Plugin              | Category  | Marketplace source       | Why                                                                  |
+| ------------------- | --------- | ------------------------ | -------------------------------------------------------------------- |
+| `frontend-design`   | design    | `anthropics/claude-code` | Steers UI generation toward intentional typography, hierarchy, color |
+| `security-guidance` | security  | `anthropics/claude-code` | Security-aware authoring guidance during code generation             |
+| `code-review`       | review    | `anthropics/claude-code` | Multi-agent PR review across compliance, bugs, history, and comments |
+| `superpowers`       | debugging | `obra/superpowers`       | Methodology skills: systematic-debugging, root-cause-tracing         |
+
+## Recommended default
+
+The `design` and `security` categories cover the common gaps for a new machine.
+When the user asks for a recommended set, propose `frontend-design` and
+`security-guidance`. Offer `code-review` and `superpowers` as additions.
+
+`code-review` overlaps the toolkit's own `claude-review` skill. They run in
+different places, the plugin on a PR and the toolkit skill on a local diff. Install
+`code-review` only when the user wants the GitHub-side flow too.
+
+## Installs outside the claude plugin CLI
+
+Some strong plugins do not distribute through a marketplace, so the `claude plugin`
+path does not reach them. List them here with their real installer. Surface them to
+the user during selection, but do not run their install through the marketplace
+step above. Run the installer command verbatim only when the user picks it.
+
+| Plugin       | Category | Installer                       | Why                                                               |
+| ------------ | -------- | ------------------------------- | ----------------------------------------------------------------- |
+| `impeccable` | design   | `npx impeccable skills install` | Curated anti-slop reference files, sharper than `frontend-design` |
+
+`npx impeccable skills install` detects the Claude Code harness and installs into
+`.claude/`. It may prompt, so it is not fully non-interactive. After install, run
+`/impeccable init` and reload.
+
+Install per project, not per machine. The skill invokes its scripts through paths
+relative to the current project (`.claude/skills/impeccable/scripts/*.mjs`), so a
+copy under `~/.claude/` cannot locate them once the working directory is a
+different project. Re-run the installer in each project that wants impeccable.

package/claude/skills/setup-verify/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: setup-verify
+description: Why a fresh scaffold is checked with declared leaf scripts in a fixed order, and what the excluded stages would cost
+---
+
+# Setup verify requirement
+
+## Gap
+
+Without this skill, a freshly scaffolded project is handed over on the strength of the configs looking right, and the first typo surfaces when the user runs something. A scaffold is generated from a reference, so the errors it carries are wiring mistakes and missing dependencies, both of which any script run would have caught.
+
+The naive check fails two ways. A session that assumes script names runs `test` against a stack that exposes `test:run`, or invents a fallback command when a script is absent, and either result reports on something the project never declared. A session that runs a composite script gets one failure covering several stages, so the output names the wrapper rather than the break.
+
+The stages left out are the ones that lie. A dev server or a preview reads as failed when it starts slowly, a browser test needs an install and a running server before it can even fail correctly, and a CI workflow cannot be judged locally at all. Including any of them turns a scaffold check into a flaky one, and a flaky check gets ignored.
+
+## Must
+
+- Read the scripts the project declares and run only those
+- Run leaf scripts in a fixed order, so a failure points at the exact stage that broke
+- Stop at the first failure and surface its output rather than continuing to collect more
+- Report per script and close with one summary line naming the failing stage when there is one
+
+## Must not
+
+- Invent a fallback command for an absent script. Skip it.
+- Run a composite script, which hides which stage broke
+- Run a dev server, a preview, or a browser test
+
+## Guards
+
+- No `package.json` at the project root stops, since there are no declared scripts to read
+- A missing dependency folder installs first rather than letting every script fail on the same cause
+
+## Out of scope
+
+- Dev and preview smoke tests, which `project-commands` starts on request
+- Browser end-to-end tests, which need a browser install and a running server
+- CI workflow validation, which runs on the pull request rather than locally
+- Generating the configs it checks, which the tooling stack reference owns

package/claude/skills/setup-verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: setup-verify
+description: Verifies a freshly scaffolded project by running its `package.json` scripts in order and reporting pass/fail per script. Use after the agent has followed a tooling stack reference and generated configs, or when asked to "verify the scaffold", "check the setup", "run verify", or "make sure everything works". Do NOT use on a project without `package.json`, or to run E2E or dev servers.
+---
+
+# Verify scaffold
+
+Runs the local verification chain against a freshly scaffolded project. Catches config typos, missing deps, and wiring mistakes before the user ever sees them.
+
+## Guards
+
+- If `package.json` does not exist at the project root, stop: `❌ No package.json found. Cannot verify.`
+- If `node_modules/` does not exist, run `bun install` first, then proceed.
+
+## Step 1: read scripts
+
+Read `package.json` from the project root and extract the `scripts` block. Do not hardcode script names. Different stacks expose different scripts.
+
+## Step 2: run the chain
+
+Run the scripts below in order. Stop on the first failure and surface the error. Each script is a leaf command so failures point at the exact break.
+
+| Order | Script      | Skip if                     |
+| ----- | ----------- | --------------------------- |
+| 1     | `lint:fix`  | absent                      |
+| 2     | `typecheck` | absent                      |
+| 3     | `check`     | absent                      |
+| 4     | `test:run`  | absent, fall back to `test` |
+| 5     | `build`     | absent                      |
+
+Skip any script not present in `package.json`. Do not invent a fallback command. Do not run composite scripts like `check:full`. Do not run `dev`, `preview`, `test:e2e`, `test:ui`, `screenshot`.
+
+Run each as `bun run <script>` from the project root.
+
+## Step 3: report
+
+For each script run, report one of:
+
+- `✅ <script>`
+- `❌ <script>` followed by the failing output (last 40 lines)
+
+End with a summary line:
+
+- On pass: `✅ Scaffold verified (<n> scripts passed).`
+- On fail: `❌ Scaffold failed at <script>. Fix the error and re-run setup-verify.`
+
+## Out of scope
+
+- Dev server and preview server smoke tests. Too flaky for a scaffold check, where a slow start reads as a failure. Use `project-commands` to start one on request.
+- Playwright E2E tests. Require browser install and a running server.
+- CI workflow validation. Runs in GitHub Actions on PR, not locally.

package/claude/skills/systematic-debugging/REQUIREMENT.md

@@ -0,0 +1,41 @@
+---
+name: systematic-debugging
+description: Why a fix is blocked until investigation completes, and what the three-attempt stop is measuring
+---
+
+# Systematic debugging requirement
+
+## Gap
+
+Without this skill, a session handed a failure proposes a fix from the first plausible reading of the error, and the fix is judged by whether the symptom moved. A symptom that moves is the normal result of changing something near it, so the session reports success and the cause is still there.
+
+The compounding failures come next. Several changes go in at once, so a pass says nothing about which one mattered. A fix that fails gets another fix stacked on top of it rather than a new hypothesis, and the code accumulates changes nobody can trace to a reason. A bad value gets corrected where it was observed rather than where it was produced, which moves the failure downstream instead of removing it.
+
+Two failures are about stopping rather than about fixing. A session that never counts its attempts keeps fixing through the pattern where each fix reveals a problem elsewhere, which is architectural and cannot be reached from inside the loop. And a session that concludes an issue is environmental usually has an incomplete investigation rather than an environmental issue, because that conclusion is available at any point and is never contradicted by evidence.
+
+## Must
+
+- Complete the investigation before any fix is proposed, reading the failure in full and reproducing it
+- Trace a bad value back to where it was produced and fix there
+- Compare the broken code against working code in the same codebase before hypothesizing
+- State one hypothesis and change one variable to test it
+- Write the failing test before the fix, so the fix is judged against a reproduction rather than against the symptom
+- Stop after three failed attempts and hand the architectural question to the user
+
+## Must not
+
+- Stack a second fix on a failed one rather than forming a new hypothesis
+- Bundle a refactor or an unrelated improvement into the fix
+- Accept an environmental or timing conclusion before the investigation is exhausted
+- Claim an understanding it does not have
+
+## Guards
+
+- An incomplete investigation blocks the fix proposal, which is the skill's one refusal and the reason it exists
+- Three failed attempts stop the loop, since the pattern is evidence about the design rather than about the bug
+
+## Out of scope
+
+- A typo fix and a cause already agreed on, where the phases cost more than they return
+- Reviewing a change for defects it has not yet exhibited: `claude-review`
+- Deciding whether the architecture should change, which the three-attempt stop hands to the user rather than answering

package/claude/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: systematic-debugging
+description: Forces root-cause investigation before any fix when a test fails, a bug surfaces, or unexpected behavior appears. Auto-triggers on "test is failing", "it's broken", "why does X happen", "this isn't working". Do NOT use for trivial typo fixes or when the cause is already agreed on.
+---
+
+# Systematic debugging
+
+Random fixes waste time and create new bugs. Before proposing any fix, complete the four phases below in order.
+
+## The rule
+
+No fixes without root-cause investigation first. If phase 1 is incomplete, no fix may be proposed.
+
+## Phase 1: investigate
+
+1. Read every line of the error, stack trace, and log output. Note file paths, line numbers, error codes.
+2. Reproduce the failure. If it is not consistently reproducible, gather more data before guessing.
+3. Check what changed. Run `git diff` and `git log --oneline -10` from the project root to see recent changes.
+4. For multi-component systems, add instrumentation at each component boundary and run once to see which layer fails before investigating further.
+5. Trace bad values backward to their source. Fix at the origin, not the symptom.
+
+## Phase 2: find the pattern
+
+1. Locate similar working code in the same codebase. Compare it to the broken code line by line.
+2. If following a reference implementation, read it completely before adapting. No skimming.
+3. List every difference between working and broken, no matter how small.
+
+## Phase 3: hypothesize and test
+
+1. State one hypothesis: "I think X is the root cause because Y". Be specific.
+2. Make the smallest possible change to test it. One variable at a time.
+3. If the change does not resolve the issue, form a new hypothesis. Do not stack another fix.
+4. If you do not understand something, say so. Do not pretend.
+
+## Phase 4: fix
+
+1. Write a failing test case that reproduces the issue before fixing.
+2. Make one change that addresses the root cause. No bundled refactors, no "while I'm here" improvements.
+3. Verify the test passes and no other tests break.
+
+## Three-fix circuit breaker
+
+After three failed fix attempts, stop. This pattern indicates an architectural problem, not a bug:
+
+- Each fix reveals a new problem somewhere else.
+- Each fix requires refactoring elsewhere to apply.
+- Symptoms keep moving.
+
+When this happens, stop fixing and ask the user whether the underlying pattern should be reconsidered.
+
+## Red flags that mean "return to phase 1"
+
+- "Quick fix for now, investigate later"
+- "Try X and see if it works"
+- "It's probably Y, let me change that"
+- Proposing a fix before tracing data flow
+- Adding multiple changes and running tests to see what sticks
+- Skipping the failing test "because I'll verify manually"
+
+Any of these means phase 1 is not complete. Return to it.
+
+## When investigation reveals no root cause
+
+Rarely, an issue is genuinely environmental, timing-dependent, or external. In that case:
+
+1. Document what was investigated and ruled out.
+2. Implement appropriate handling: retry, timeout, explicit error.
+3. Add logging so the next occurrence can be investigated.
+
+Most "no root cause" conclusions are incomplete investigations. Exhaust phase 1 before accepting them.

package/claude/skills/write-human/REQUIREMENT.md

@@ -0,0 +1,46 @@
+---
+name: write-human
+description: Scope boundary between the writing rules a scan enforces and the ones only a reader can, and why the second set travels in a skill
+---
+
+# Write human requirement
+
+## Gap
+
+Without this skill, a session is graded on the words it avoids and never on how the prose reads. The banned words, characters, and spellings ship as data the CLI and the installed hook both read, so that half is measured on every run. The voice half sat under a heading in a standard nothing opened, so a session wrote the whole passage without it and the audit reported a clean exit over prose that read machine-written.
+
+The output of that arrangement is specific rather than general. Paragraphs come back with every sentence landing within a few words of the last, with consecutive sentences opening on the same word and the same grammatical shape, and with the compression rule applied until the verb is gone, so the passage trades uniform sentences for uniform fragments. A session told to be terse and told nothing about cadence produces exactly that, since cutting is the only instruction it holds.
+
+A session also has no name for the patterns no closed word set can match. Rule-of-three, synonym cycling, false ranges, inline-header lists, and adverb propping each survive a clean scan, so a passage carrying all five reports zero findings and still reads wrong. Nothing tells the session those patterns exist, and a ban list cannot be extended to reach them, because each is a shape rather than a token.
+
+Importing that catalog wholesale fails on a different measurement. External material of this kind bans abstract metaphor nouns and names `surface` among them, which this corpus uses 593 times in tracked markdown at `57ee7467`. A session handed the catalog with no stated position either rewrites established vocabulary or silently ignores the item, and neither outcome is recoverable by a later reader who cannot tell which happened.
+
+## Must
+
+- Arrive attached to the writing rather than waiting to be consulted, which is why the path-scoped rule on a markdown edit carries an explicit instruction to load this skill
+- State cadence as something to measure, giving the sentence-length spread and the repeated-opening count a session can check, since a rule to vary sentence length is one a session satisfies by assertion
+- Ban the fragment trade by name, since compression is the instruction a terse register already carries and the verb is what it drops first
+- Name the machine tells a scan cannot reach, and hold the catalog behind a stated trigger so a run that needs none pays no read for it
+- Point at the banned words rather than restating them, since they ship as package data a command reads and a second copy drifts with nothing comparing the two
+- Record which external patterns were adopted, which were declined, and the measurement behind each, so a later session extends the position instead of re-deriving it
+- Yield voice to a surface that states its own, and hold rhythm, density, and the tells on every surface
+
+## Must not
+
+- Restate the banned words, characters, or spellings, at any length or as an example set
+- Claim the reported failure is closed. Cadence is a property of a passage and nothing measures the output against these rules yet, so this skill states the rule and the measurement is owed separately.
+- Rewrite a term the corpus already uses because an external source bans it, without the count and a recorded position
+- Grow a second voice register inside this body. One baseline covers every surface, and a register a real surface needs arrives as an overlay that yields on voice alone.
+
+## Guards
+
+- A passage on a surface stating its own voice keeps that voice, so the yield is read before the voice rules are applied rather than after the rewrite
+- Text a model drafted goes through the tells catalog, and a short original draft with nothing reading off skips it
+
+## Out of scope
+
+- The banned words, characters, and spellings, which `markdown.md` states for a reader and `canon markdown audit` gates from package data
+- Markdown mechanics, being headings, lists, code spans, punctuation, and file references
+- Restating text that already exists in plainer words, which `restate-plainly` owns on a different trigger, since a restatement is asked for by name and this arrives on a glob match. The rules here still govern how that restatement reads, and that body cites this one rather than carrying a copy.
+- What voice a given surface declares, which belongs to the standard governing that surface
+- Measuring whether finished output followed these rules, which needs a check this skill does not carry

package/claude/skills/write-human/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: write-human
+description: Carries the voice, rhythm, sentence construction, and information density rules a banned-word list cannot express, plus the catalog of machine tells that survive a clean ban scan. Use when writing or revising prose a person will read, when a passage reads flat or uniform, or when asked to "make this read like a person", "fix the cadence", "this reads like AI wrote it", "vary the sentences", or "tighten this without gutting it". Do NOT use for banned words, characters, or spellings, which `markdown.md` states and `canon markdown audit` gates, and do NOT use to restate text that already exists in plainer words, which is `restate-plainly`, whose body loads these rules from here.
+---
+
+# Write human
+
+Write prose that reads as though a person wrote it. A ban list subtracts words and reaches nothing about how a passage moves, so this skill carries the half no scan measures.
+
+Load this before drafting a passage rather than after. A revision pass recovers the words and never recovers the structure the draft already settled.
+
+The banned words, characters, and spellings sit in `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`. They stay in force here. This skill adds to them and never restates them, since `canon markdown audit` reads them from the package and a second copy would drift.
+
+## What yields and what does not
+
+- A surface stating its own voice keeps that voice. Blogs, emails, changelogs, and commit messages are surfaces of that kind, as is any document whose own standard states a voice.
+- The yield covers voice alone. Rhythm, density, and the machine tells below apply on every surface, as do the bans and the markdown mechanics.
+- Terse reference prose is the default register. A warmer register is an overlay a surface declares, never a reason to drop the rules underneath it.
+
+## Voice
+
+- Write for a developer who is scanning rather than studying. Every sentence has to land on first read.
+- Use active voice, and present tense unless past or future is factually correct.
+- Name the actor in a sentence that has one. Passive voice with an unnamed actor hides who acts and reads as evasion.
+- Prefer direct verbs and plain words. Write `use` over `utilize`, `help` over `facilitate`, `is` over `serves as`.
+- Be direct on an established fact. Hedge on a genuinely uncertain claim and say which it is.
+- Assume developer-level knowledge. Skip the explanation the reader already carries.
+- Front-load the key information in a paragraph, and give every sentence something the reader did not have.
+
+## Rhythm
+
+Uniform cadence is the tell that survives the cleanest ban scan. Measure it rather than judging it:
+
+- Read the paragraph as one block. Uniformity is audible and close to invisible line by line.
+- Compare the longest and shortest sentence in a paragraph. Within roughly five words of each other means the paragraph has one cadence and needs a short sentence or a long one added.
+- Count the opening word of each sentence. Two alike is coincidence and three is a pattern to break.
+- Vary the grammatical shape of the opening, not the word alone. Three sentences opening on three different subjects still share one shape.
+- Never buy variety with a fragment. A verbless clause standing as a sentence trades one uniformity for another and is the failure these rules exist against.
+- Use a substantive connective where the flow needs one, and never add a word for rhythm alone.
+
+## Density
+
+- Carry one claim per sentence. A sentence carrying three claims hides the two the reader most needs to check.
+- Cut a sentence restating the one above it at a different altitude. A summary of the previous sentence is the most common padding in machine prose.
+- Compress by removing what repeats, never by removing the verb. Dropping the verb is the fragment rule wearing an efficiency argument.
+- Resolve a pronoun or a demonstrative to its noun whenever more than one antecedent is in reach.
+
+Read `${CLAUDE_SKILL_DIR}/references/density.md` when a passage is dense and still reads long, or when cutting it keeps breaking the sentences.
+
+## Machine tells
+
+Read `${CLAUDE_SKILL_DIR}/references/machine-tells.md` before revising text a model drafted, and whenever a passage clears the ban scan and still reads wrong. It catalogs the patterns no closed word set can match, being rule-of-three, synonym cycling, false ranges, inline-header lists, adverb propping, and the rest, each with the fix.
+
+Skip that reference on a short original draft where nothing reads off. The catalog is a diagnostic and costs a read on every invocation that does not need it.
+
+## Revising a passage
+
+1. Read the whole passage before editing a line of it.
+2. Mark the sentence lengths and the openings in each paragraph, and rewrite the flattest run first.
+3. Check each paragraph for a sentence that adds no claim, and cut it rather than shortening it.
+4. Re-read for the tells the catalog names, if the passage came from a model.
+5. Run `canon markdown audit <path>` for the mechanical half, and rewrite each hit rather than swapping the token for a near-synonym.
+
+Report each file written or updated by its full path from the project root.
+
+## Source material
+
+The position on external writing guidance sits in `${CLAUDE_SKILL_DIR}/references/source-material.md`, which states what this skill adopted, what it declined, and the measurement behind each. Read it before importing a rule from outside this corpus. Do not re-derive that position, since a second answer will disagree with the recorded one.

package/claude/skills/write-human/references/density.md

@@ -0,0 +1,38 @@
+---
+title: Information density
+description: What to cut from a passage, what never to cut, and how to keep a compressed sentence unambiguous
+---
+
+# Information density
+
+Read this when a passage is dense and still reads long, or when cutting it keeps breaking the sentences. Density is claims per sentence rather than words per sentence, so a short passage carrying one claim four times is the failure this reference addresses.
+
+## What to cut
+
+- A sentence restating the one above it at a different altitude. Machine prose states the specific claim, then the general version of it, then the reason it matters.
+- A setup clause that names what the next clause already names. `In terms of performance, the query is slow` carries one claim and two subjects.
+- A qualifier that changes no truth condition. `Generally`, `in most cases`, and `typically` earn their place where an exception exists and gets named, and nowhere else.
+- An example that demonstrates the same thing as the example above it. Two examples differ in what they teach or one of them goes.
+- A transition that names the relationship the sentences already carry. `Additionally` before an addition adds nothing.
+
+## What never to cut
+
+- The verb. A compressed clause with the verb removed is a fragment, and the fragment is the failure the rhythm rules exist against.
+- A qualifier that bounds a claim. `Every tracked markdown file` and `most files` are different claims, and dropping the bound is a fabrication rather than a compression.
+- The named source of a claim, and the date or ref a measurement was taken at. A number with no stamp cannot be re-measured, so it stops being evidence.
+- The actor of a sentence that has one. Compressing to the passive removes the fact rather than the words.
+
+## Keeping a compressed sentence unambiguous
+
+Compression is what creates ambiguity, so each pass over a tightened sentence checks the same four things:
+
+- Resolve every pronoun and demonstrative to a noun when more than one antecedent is in reach. `This breaks the build` after two clauses names neither.
+- Attach every modifier to the word it modifies. A clause that moved during a rewrite lands next to the wrong noun and reads as a claim about it.
+- Quantify an amount rather than naming it. `Large`, `often`, and `slow` each ask the reader to supply the number.
+- Split a sentence carrying two claims joined by `and` when either claim can be false on its own. One sentence per truth condition is what makes a passage checkable.
+
+## Measuring a paragraph
+
+Count the claims a paragraph makes and the sentences it uses. More sentences than claims means the paragraph is padded, and the cut targets the restatements above. Fewer sentences than claims means the paragraph is compressed past the point a reader can check it, and the split targets the joined sentences.
+
+A paragraph carrying no claim at all is a transition, and a transition earns one sentence at most.

package/claude/skills/write-human/references/machine-tells.md

@@ -0,0 +1,107 @@
+---
+title: Machine tells
+description: Patterns that survive a clean ban scan, why each is invisible to a word set, and the fix for each
+---
+
+# Machine tells
+
+Each pattern below is a shape rather than a token, so no closed word set matches it and `canon markdown audit` reports a clean exit over a passage carrying every one. Read this when revising text a model drafted, or when a passage passes the scan and still reads wrong.
+
+Work top down. The first three account for most of what a reader calls machine-written.
+
+## Rule of three
+
+A triad wherever a list appears, whatever the subject actually holds. Three adjectives, three clauses, three examples, over and over, until the count is the only thing a reader can predict.
+
+The tell is the regularity rather than the number. A subject with two parts gets a third invented to fill the shape, and a subject with five gets cut to three.
+
+```markdown
+Bad: The parser is fast, simple, and reliable.
+Good: The parser reads 40k lines a second and has no configuration.
+```
+
+Fix by counting what the subject has and writing that many. A list of two is fine, and so is a list of six.
+
+## Synonym cycling
+
+One thing named four ways across a paragraph, on the belief that repeating a noun reads poorly. The reader then cannot tell whether `the handler`, `the callback`, `the listener`, and `the hook` are one thing or four.
+
+```markdown
+Bad: Register the handler. The callback receives the event, and the listener returns a promise.
+Good: Register the handler. The handler receives the event and returns a promise.
+```
+
+Fix by picking one name per thing and repeating it. Repetition of a term is precision in reference prose.
+
+## False ranges
+
+`from X to Y` used over things that form no spectrum, which smuggles a claim of coverage the sentence cannot support.
+
+```markdown
+Bad: Everything from authentication to deployment.
+Good: Authentication, schema migration, and deployment.
+```
+
+Fix by naming the members. Keep the range form where the endpoints bound a scale, such as a version range or a byte size.
+
+## Inline-header lists
+
+A bullet opening with a bold label and a colon, where the body then restates the label in a sentence. The shape looks organized and carries one fact per bullet instead of two.
+
+```markdown
+Bad: - **Caching**: Caching stores the response so the next request skips the fetch.
+Good: - Caching stores the response, so the next request skips the fetch.
+```
+
+Fix by cutting the label when the sentence already names the subject. Keep the label where the bullets form a lookup table a reader scans by key.
+
+## Adverb propping
+
+An adverb carrying the weight the verb should. `significantly improves`, `dramatically reduces`, and `effectively handles` each name no amount and no mechanism.
+
+```markdown
+Bad: The index significantly improves query performance.
+Good: The index cuts the median query from 400ms to 12ms.
+```
+
+Fix by replacing the adverb with the measurement, or by cutting it and leaving the verb alone.
+
+## Passive voice with an unnamed actor
+
+`it was decided`, `changes were made`, `the file is expected to be updated`. The actor is the fact the reader wanted, and the construction is what removes it.
+
+```markdown
+Bad: The threshold was raised after the incident.
+Good: The on-call engineer raised the threshold after the incident.
+```
+
+Fix by naming who acts. Keep the passive where the actor is genuinely unknown or genuinely irrelevant, and say which.
+
+## Closing restatement
+
+A final sentence per section summarizing the section, at a higher altitude and with no new claim. In a short document every section then ends the same way.
+
+Fix by cutting it. A section that needs a summary is too long, and the split is the answer.
+
+## Question as transition
+
+`So what does this mean?` or `Why does this matter?` standing alone between paragraphs. It addresses the reader as a participant and delays the answer by one line.
+
+Fix by stating the answer as the next sentence.
+
+## Escalating parallel clauses
+
+`not only X but also Y`, and the longer chains built on it. The construction promises a second claim that outranks the first and usually delivers a restatement.
+
+```markdown
+Bad: The cache not only stores responses but also improves latency.
+Good: The cache stores responses, which is what cuts latency.
+```
+
+Fix by writing the two claims as two sentences, or by cutting the one that repeats.
+
+## Empty superlative frames
+
+`one of the most important`, `a critical piece of`, `at the heart of`. The frame ranks a thing against a set the sentence never names.
+
+Fix by stating what the thing does. A ranking survives only where the set is named and the position is measured.

package/claude/skills/write-human/references/source-material.md

@@ -0,0 +1,37 @@
+---
+title: Source material
+description: Which external writing patterns this skill adopted, which it declined, and the measurement behind each decision
+---
+
+# Source material
+
+Two external writing skills were read on 2026-08-19 as source material for this one. The first catalogs 31 patterns of machine-sounding prose. The second layers document mode, sentence construction, information density, and ambiguity prevention.
+
+Neither was imported wholesale, and one measurement settles why. Read this before adding a rule from outside this corpus, and extend the position below rather than deriving a second one.
+
+## What was adopted
+
+Roughly half the pattern catalog had no counterpart in this corpus, and six of those patterns are now in `machine-tells.md`: rule-of-three, synonym cycling, false ranges, inline-header lists, adverb propping, and passive voice with an unnamed actor. Each is a shape rather than a token, which is what kept it out of a ban list that matches words.
+
+The density layer had no counterpart at all and is now `density.md`. Its useful half is the split between what a compression pass may cut and what it may not, since a terse register already instructs a session to cut and names nothing that has to survive.
+
+The ambiguity rules travel with that layer for the same reason. Compression is what creates the ambiguity, so a rule about pronouns and modifiers belongs beside the rule that shortened the sentence.
+
+## What was declined
+
+- **The ban on abstract metaphor nouns.** The nouns it names are load-bearing terms in this corpus rather than decoration, and the count below is what decides it.
+- **Document mode as a selector.** The source has the writer pick a mode before drafting. In this corpus a document's shape is already fixed by the standard governing its type, so a mode selector adds a second authority over one question and the two will disagree.
+- **Any restatement of a banned word set.** The bans ship as package data that `canon markdown audit` reads, and a copy here would be a second source for one list with a machine reading the other.
+- **A voice register per surface.** One baseline covers every surface. A surface needing a warmer register states its own voice and claims the yield, which lifts voice alone and leaves the bans, the rhythm rules, and the tells in force.
+
+The first of those four rests on a count. The source names `surface` among the nouns it bans, and tracked markdown in the authoring repository used `surface` 593 times, `harness` 95, `scaffolding` 17, and `primitive` 4, measured at `57ee7467` on 2026-08-19. Adopting the item either rewrites established vocabulary across the corpus or is ignored in silence, and a reader arriving later cannot tell which happened.
+
+## Where this diverges
+
+The source material treats repetition of a noun as a defect. This skill treats it as precision and bans the synonym cycling that avoids it, which reverses the item for reference prose where a reader has to know that two names are one thing.
+
+The source material also prefers shorter sentences without bound. This skill measures the spread instead, since a passage of uniformly short sentences is the reported failure rather than the fix for it.
+
+## The industry-guide record
+
+The cadence rules and the bans they pair with trace to three industry style guides, being Google's developer documentation style guide, Microsoft's writing style guide, and Apple's style guide. The authoring toolkit keeps the per-rule attributions and the dates each guide was read, and no install carries that record, so this file is the position a target reads.