@erclx/aitk 0.105.0 → 0.106.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.105.0",
+  "version": "0.106.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-address-review/SKILL.md

@@ -103,9 +103,10 @@ sessions addressing different pull requests never overwrite each other between
 the write and the post. Note any `.claude/` docs refreshed as a result of the
 fixes.
 
-The reply is a rendered-for-human GitHub surface, so follow
-`.claude/standards/prose.md` for voice, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md`
-when the project does not have it, and keep each mapping to a line or two.
+The reply is a rendered-for-human GitHub surface, so load the `write-human`
+skill for voice, follow `.claude/standards/markdown.md` for the banned words, or
+`${CLAUDE_SKILL_DIR}/../../standards/markdown.md` when the project does not have
+it, and keep each mapping to a line or two.
 
 Open the body with the `## Review response` heading so it anchors as a section
 distinct from human threads and stays subordinate to the `## Review` heading the

package/claude/skills/claude-design-extract/SKILL.md

@@ -32,8 +32,8 @@ Read these from the project root on both paths, skipping any that do not exist:
 
 - `CLAUDE.md`: voice, personality, spelling rules
 - `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
-- `.claude/standards/prose.md`: tone constraints
-- `.claude/standards/markdown.md`: punctuation and formatting constraints
+- `.claude/standards/markdown.md`: word, punctuation, and formatting constraints
+- The `write-human` skill: tone and sentence construction constraints
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
@@ -55,7 +55,7 @@ Use the returned content as the target shape. Keep every section heading and eve
 
 ## Step 4: fill the template
 
-Walk each section once. Follow `.claude/standards/markdown.md` for punctuation and `.claude/standards/prose.md` for word choice throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
+Walk each section once. Follow `.claude/standards/markdown.md` for punctuation and word choice throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
 
 Mark any cell not traced to a source value by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` after the row breaks the parser. A prose section takes its uncertainty inline instead, for example `Proposed 150ms ease-out, not yet confirmed.`, because a trailing tag on a sentence renders raw in the preview.
 

package/claude/skills/claude-docs/SKILL.md

@@ -106,7 +106,7 @@ The verb resolves the board at the main worktree root in-process, which is the r
 
 - Update only the sections affected by session decisions.
 - Do not rewrite sections unrelated to what changed.
-- Follow `.claude/standards/prose.md` and `.claude/standards/markdown.md` for all edits.
+- Follow `.claude/standards/markdown.md` and the `write-human` skill for all edits.
 - Close a decision entry in `.claude/ARCHITECTURE.md` with its verification anchor whenever this run writes that entry or amends its reasoning and that reasoning cites a measured number. Re-read the number against the tree first, since the marker records the read rather than the edit. `.claude/standards/architecture.md` fixes the sentence.
 - Leave every decision entry this run did not write alone, anchored or not. The rule is scoped forward, so an entry written before it is dated by blame rather than by a read. Step 6 reports a stale anchor and no step writes one on an entry it did not amend.
 

package/claude/skills/claude-memory-capture/SKILL.md

@@ -27,8 +27,8 @@ Read in parallel from the project root, skipping any that do not exist:
 - `CLAUDE.md`: the project's write location and any rule it states over the folder
 - `.claude/memory/index.md`: existing index, to avoid duplicates
 - `.claude/context/index.md`: the domain catalog Step 3 routes against
-- `.claude/standards/prose.md`: voice and banned words applied to memory file bodies
-- `.claude/standards/markdown.md`: punctuation and formatting applied to memory file bodies
+- `.claude/standards/markdown.md`: banned words, punctuation, and formatting applied to memory file bodies
+- The `write-human` skill: voice, rhythm, and sentence construction applied to memory file bodies
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/claude-pr-review/SKILL.md

@@ -111,7 +111,7 @@ An empty result means no response arrived since the prior pass, so this pass wou
 
 The response is also the whole read on a repeated head. Step 2 resolves an empty range, because a commit is its own ancestor and `<prior-oid>..<headRefOid>` spans nothing, so the delta cannot answer whether a prior finding landed. Read that comment for what the worker changed or accepted, and treat an accepted finding as closed rather than restating it.
 
-The comment is a rendered-for-human GitHub surface, so follow `.claude/standards/prose.md` for voice, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it: cut editorializing, and keep every sentence load-bearing. Match this shape on a first pass:
+The comment is a rendered-for-human GitHub surface, so load the `write-human` skill for voice and follow `.claude/standards/markdown.md` for the banned words, or `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` when the project does not have it: cut editorializing, and keep every sentence load-bearing. Match this shape on a first pass:
 
 ```markdown
 ## Review

package/claude/skills/claude-standards-audit/SKILL.md

@@ -8,8 +8,8 @@ description: Audits changed markdown files against every authoring standard that
 ## Guards
 
 - Resolve the base ref first, per Diff baseline below, then scope the file list exactly as Step 1 does, fallback included. If no markdown files changed, stop: `✅ No markdown changes to audit.` A guard that reads bare local `main`, or that skips the unusable-baseline fallback, passes the skill clean on a branch it never read.
-- If neither `.claude/standards/prose.md` nor `${CLAUDE_SKILL_DIR}/../../standards/prose.md` is present, stop: `❌ prose.md standard not found. Install toolkit standards first.` Test the file rather than the directory, since a project that installed standards before a given file existed keeps the directory without ever receiving that file.
-- Apply the same test to `markdown.md`, stopping with its own name. It carries the character bans and the formatting rules, so a run reaching only `prose.md` reports word choice against a clean file and calls the pass complete.
+- If neither `.claude/standards/markdown.md` nor `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` is present, stop: `❌ markdown.md standard not found. Install toolkit standards first.` Test the file rather than the directory, since a project that installed standards before a given file existed keeps the directory without ever receiving that file.
+- `markdown.md` is the one standard testable before the mapping runs, since its scope statement declares an attribute and every changed markdown file therefore maps to it. Every other standard is tested in Step 3, where the mapping has named which ones the run needs.
 
 ## Diff baseline
 
@@ -68,12 +68,14 @@ Every mapping names a changed markdown file, which is the only thing Step 1 prod
 
 ## Step 3: read standards and audit
 
-Read each applicable standard once. For each changed file, audit against every rule:
+Read each applicable standard once, testing `.claude/standards/<name>` and `${CLAUDE_SKILL_DIR}/../../standards/<name>` before reading it. A standard the mapping named and neither path carries is reported as a finding against the file that mapped to it rather than skipped, since a standard read from nowhere reports every file under it clean.
+
+For each changed file, audit against every rule:
 
 - **Pattern rules**: grep the file for every token the standard bans. Grep is authoritative. Reading alone misses occurrences.
 - **Judgment rules**: check each rule in context against the standard that states it.
 
-Every changed markdown file gets the prose pattern pass, since `.claude/standards/prose.md` and `.claude/standards/markdown.md` both apply to all of them. Take the banned tokens from those standards at read time rather than from a list held here. The banned words sit in the first and the banned characters in the second, so a pass reading one file finds half the tokens.
+Every changed markdown file gets the pattern pass, since `.claude/standards/markdown.md` applies to all of them. Take the banned tokens from that standard at read time rather than from a list held here. It carries the banned words, the banned spellings, and the banned characters together, so one read covers every token this pass greps for.
 
 ## Step 4: report
 
@@ -84,13 +86,13 @@ path/to/file.md
 
 - L12: `markdown.md`, em dash in prose
 - L34: `markdown.md`, semicolon used to join clauses
-- L51: `prose.md`, vague qualifier `simply`
+- L51: `markdown.md`, vague qualifier `simply`
 - L67: `context.md`, decision entry names no rejected alternative
 ```
 
 If clean, respond with `✅ No violations.`
 
-Reporting only. Do not rewrite any file, swap any punctuation, or propose fixes inline. Fixes are a separate user-initiated step because lazy swaps (semicolon to period, em dash to comma) violate the prose rule against shallow substitution.
+Reporting only. Do not rewrite any file, swap any punctuation, or propose fixes inline. Fixes are a separate user-initiated step because a lazy swap (semicolon to period, em dash to comma) leaves the sentence in the shape the ban exists to remove.
 
 ## Output
 

package/claude/skills/create-skill/SKILL.md

@@ -9,8 +9,8 @@ disable-model-invocation: true
 Read these files from the project root in parallel:
 
 - `.claude/standards/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
-- `.claude/standards/prose.md`: voice and banned words for skill body text
-- `.claude/standards/markdown.md`: punctuation and formatting for skill body text
+- `.claude/standards/markdown.md`: banned words, punctuation, and formatting for skill body text
+- The `write-human` skill: voice, rhythm, and sentence construction for skill body text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/create-snippet/SKILL.md

@@ -7,8 +7,8 @@ description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. U
 
 Creates one snippet file. Read these files in parallel:
 
-- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
-- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
+- `.claude/standards/markdown.md` from the project root: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `${CLAUDE_SKILL_DIR}/references/snippets.md`: authoring conventions, invocation channels, use patterns
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/create-snippet/references/snippets.md

@@ -13,8 +13,8 @@ Governs a snippet file: what one is for, whether a prompt qualifies as one, how
 Does not govern:
 
 - Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
-- Voice and word choice in snippet prose: `prose.md`
-- Punctuation and formatting in snippet prose: `markdown.md`
+- Voice, rhythm, and sentence construction in snippet prose: the `write-human` skill
+- Punctuation, formatting, and word choice in snippet prose: `markdown.md`
 
 ## What a snippet is
 

package/claude/skills/create-standard/SKILL.md

@@ -7,8 +7,8 @@ description: Creates a new standard file in `standards/` or `.claude/standards/`
 
 Creates one standard file. Read these files in parallel:
 
-- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
-- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
+- `.claude/standards/markdown.md` from the project root: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `.claude/standards/standard.md` from the project root: the meta-standard for shape, frontmatter, and structure
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/docs-sync/SKILL.md

@@ -7,8 +7,8 @@ description: Rewrites stale `README.md` and `docs/*.md` sections based on change
 
 Read these files from the project root in parallel:
 
-- `.claude/standards/prose.md`: voice and banned words for all generated text
-- `.claude/standards/markdown.md`: punctuation and formatting for all generated text
+- `.claude/standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `.claude/standards/readme.md`: README structure, required sections, and content rules
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/git-issue/SKILL.md

@@ -12,8 +12,8 @@ Format an issue from session context following the issue standard, then file it
 Read these in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/issue.md`: issue title, labels, body sections, and banned phrases
-- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
-- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
+- `.claude/standards/markdown.md` from the project root: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/git-issue/references/issue.md

@@ -14,8 +14,8 @@ Does not govern:
 
 - Pull request title and body: `pr.md`
 - Whether a phase label may appear in issue text: `versioning.md`
-- Voice and banned words in issue prose: `prose.md`
-- Punctuation and formatting in issue prose: `markdown.md`
+- Voice, rhythm, and sentence construction in issue prose: the `write-human` skill
+- Punctuation, formatting, and banned words in issue prose: `markdown.md`
 
 ## Title
 

package/claude/skills/git-pr/SKILL.md

@@ -12,8 +12,8 @@ Read these files in parallel:
 - `${CLAUDE_SKILL_DIR}/references/branch.md`: branch format, valid types, and constraints
 - `${CLAUDE_SKILL_DIR}/references/pr.md`: structure, rules, and banned phrases
 - `${CLAUDE_SKILL_DIR}/references/labels.md`: label map format, matching, and the missing-label warning. Skip when the project has no `.claude/pr-labels.toml`.
-- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
-- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
+- `.claude/standards/markdown.md` from the project root: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `.claude/standards/versioning.md` from the project root: phase label vs semver discipline
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/git-pr/references/pr.md

@@ -15,8 +15,8 @@ Does not govern:
 - Commit subject format, which shares the title form: `commit.md`
 - Branch naming: `branch.md`
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Voice and banned words in pull request prose: `prose.md`
-- Punctuation and formatting in pull request prose: `markdown.md`
+- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
+- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
 
 ## Title
 

package/claude/skills/git-split/references/pr.md

@@ -15,8 +15,8 @@ Does not govern:
 - Commit subject format, which shares the title form: `commit.md`
 - Branch naming: `branch.md`
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Voice and banned words in pull request prose: `prose.md`
-- Punctuation and formatting in pull request prose: `markdown.md`
+- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
+- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
 
 ## Title
 

package/claude/skills/git-stage/SKILL.md

@@ -8,8 +8,8 @@ description: Groups staged files by concern and generates one conventional commi
 Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/commit.md`: format, types, scopes, and constraints
-- `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
-- `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
+- `.claude/standards/markdown.md` from the project root: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 

package/claude/skills/migration-standards/SKILL.md

@@ -79,7 +79,7 @@ aitk gov sync .
 
 ## Inbound references to verify
 
-- CLAUDE.md:42 references standards/prose.md
+- CLAUDE.md:42 references standards/markdown.md
 - docs/contributing.md:8 references snippets/claude/feature
 
 ## Reminder

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

@@ -44,7 +44,7 @@ Ask the user which to bootstrap. Accept folder paths, `all`, or `none`. The user
 For each chosen folder, read every `*.md` sibling and draft frontmatter:
 
 - `title`: derived from the first H1. If absent, derive from the filename in sentence case.
-- `description`: one line summarizing the file's purpose, drawn from the first paragraph after the H1. Follow `.claude/standards/prose.md` § Frontmatter descriptions for length and style, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it.
+- `description`: one line summarizing the file's purpose, drawn from the first paragraph after the H1. Follow `.claude/standards/markdown.md` § Frontmatter descriptions for length and style, or `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` when the project does not have it.
 
 Surface every drafted entry to the user grouped by file:
 

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 `aitk 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 is a different job on a different trigger, since a restatement is asked for by name and this arrives on a glob match
+- 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 `.claude/standards/markdown.md` states and `aitk markdown audit` gates, and do NOT use to restate text that already exists in plainer words.
+---
+
+# 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/standards/markdown.md`, or `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` when the project does not have that file. They stay in force here. This skill adds to them and never restates them, since `aitk 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 `aitk 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 `aitk 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 `aitk 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.