technical-writer

This skill is the pipeline. technical-writing carries the craft rules and the measured targets; this skill says what order to do things in, what to gather first, and what must pass before a page is done.

Two failure modes it exists to prevent:

1. Writing before knowing. A page drafted from the model's impression of a system is fluent and unfalsifiable. It reads as generated because it is describing a guess. Step 1 is not optional.
2. Passing the checks in the wrong order. Simplifying after de-slopping reintroduces phrasing that the de-slop pass already cleaned, so the pass has to run twice and the second run flattens the prose.

---

Step 1 — Prepare context

Nothing is drafted until this is done. Produce a source table before writing a sentence.

1. Read the implementation, not the description of it. For each claim the page will make, open the file that makes it true — the hook script, the config key, the CLI parser, the schema. Record path:line.
2. Run the thing where running it is cheap. A flag table copied from a parser is right; a flag table recalled is not. Capture real output for the examples.
3. Reconcile against the governing docs. Where this repository has a constitution, a genesis spec, or a manifest, the page must not contradict it. Note the Article or section each claim answers to.
4. Check third-party APIs against current documentation before describing them (the declared documentation provider, official docs, or a pinned local cache). Never from recall.
5. List what you could not verify. Anything left unverified is cut from the draft or written as an explicit open question. It is never softened into a vague sentence.

Output of this step is a working note: claim → source → verified date. Every factual sentence in the finished page traces back to a row in it.

If the source material is thin, the page is thin. Do not pad it with description. A short page that is entirely true is the correct deliverable.

---

Step 2 — Classify and shape

Pick exactly one Diátaxis type: reference, explanation, tutorial, or howto. This decides the numeric targets, the heading grammar, the person and the passive rate. See technical-writing Step 1.

Then sketch the section list before prose. Headings are noun phrases for reference and explanation; gerunds are correct for roughly a third of tutorial and how-to headings. Corpus mean heading length is 2.7 words.

Check the section count against the corpus: reference runs about 1,160 words per section, explanation 445, tutorial 225, how-to 201. A page with two enormous sections is under-structured.

---

Step 3 — Draft

Skill(technical-writing) — the craft rules and the measured profile.

Draft from the Step 1 source table only. While drafting, hold the four range moves in mind, because they are the ones that cannot be added by a later pass without rewriting:

• Vary the paragraph opening move. Assertion should be about two thirds, not all of them.
• Let roughly one sentence in nine run past 30 words, and put a short one after it.
• Use can, may, must, will, should — about 20 per 1000 words.
• Use the passive where the actor is irrelevant. Reference prose is around 36% passive.

Name real identifiers, enumerate real options, and show real output. Density of evidence is what separates a technical writer's page from a plausible one.

---

Step 4 — Reader level

node .claude/skills/reader-level/score.mjs --target 11 <file>     # reference, explanation
node .claude/skills/reader-level/score.mjs --target 10 <file>     # tutorial, how-to

Skill(reader-level) for the rewriting moves when it fails.

Use these targets, not the skill's default of 9. reader-level is a ceiling — it catches prose pitched above the reader. technical-writing sets the floor. Professional documentation measures at grade 10.7, so a target of 9 drives the page below the corpus band and strips the qualifying clauses that carry the meaning. Run together at target 11, the two gates bracket the page into the range real documentation occupies.

The other three reader-level limits (hard words, clause load, jargon load) stay at their defaults. They do not conflict with the corpus profile: the corpus sits at roughly 0.36 subordinate clauses and 0.6 identifiers per sentence, inside both limits.

---

Step 5 — Humanizer

Skill(humanizer) on the full draft. Always. Use its output.

Then re-check that its edits did not flatten the page: humanizer removes patterns, and removal moves several axes downward at once. Step 6 catches this.

---

Step 6 — Gates

Both must pass, in this order.

node .claude/skills/technical-writing/measure.mjs --type <type> <file>
node .claude/skills/reader-level/score.mjs --target <11|10> <file>

The first is the binding one. Threshold 4.5; the corpus median is 0.14. If it fails, read the named axes — each finding says which direction the page is wrong in and why that direction reads as machine-written — and return to Step 3. Do not tune sentences one at a time to move the number; fix the underlying habit the axis is reporting.

If a fix at Step 3 depends on a fact you do not have, go back to Step 1. A page that cannot pass without inventing something is a page missing source material.

---

Step 7 — Read it

The gates cannot see these. Run them by hand before declaring done.

• Paragraph-reshuffle. Swap two body paragraphs. If nothing breaks, the section is a list wearing prose.
• Treadmill. Per paragraph, ask what is new. Cut what is not.
• Headings alone. Read them in order. They should read as a table of contents, not a series of claims.
• Trace three claims. Pick three factual sentences at random and find their row in the Step 1 table. A miss means the page invented something, and the whole page needs re-checking.
• Type leakage. Instruction on a reference page, explanation inside a tutorial — move it and link.

---

Receipt

Close with:

Field	Value
Page type	one of the four
Sources verified	count, and anything left unverified
measure.mjs	score before → after (threshold 4.5)
reader-level	grade before → after (target 11 or 10)
Axes moved	the ones that were out of band and now are not

A receipt that cannot honestly be written means the page is not done.