humanize v2.1.0A

Immutable. This exact content is served forever at /api/v1/blob/65c3d4625f47ae5f.

---
name: humanize
description: Edit prose so it sounds like the author and reads plainly - stripping formulaic AI phrasing and replacing jargon with what it actually means. Use only when the user explicitly invokes /humanize.
argument-hint: "[file, selection, or 'all'] [for <audience>] [as talk|journal-imrad]"
disable-model-invocation: true
allowed-tools: ["Read", "Grep", "Glob", "Edit", "Write", "Agent"]
metadata:
  source: adapted from pedrohcgs/claude-code-my-workflow
  version: 2.1.0
---

# `/humanize`

Revise the requested prose in place so it sounds like the author and so a reader
gets it on the first pass. This is an editing command, not an AI-detection claim
and not a report the user has to process.

Two jobs, one pass:

1. **Remove the machine register.** Formulaic transitions, inflated framing,
   announcements that something is important, stacked hedging, generic praise.
2. **Make it plainer.** Replace a term with what it does. Say the thing instead
   of naming the method that did it. Default to the plainer wording and make
   each technical term earn its place.

Neither job may change what is true.

## Resolve the target and the audience

- Use the file, passage, or scope in `$ARGUMENTS`. For `all`, include prose
  relevant to the current deliverable and exclude rendered output,
  dependencies, vendored material, data, and code.
- Plain is relative to a reader, so establish who is reading: the audience named
  in `$ARGUMENTS`, or the one the document itself names, or ask in one line.
  A specialist audience raises the bar for *which* terms are shared; it does not
  license jargon, and it never licenses a sentence that only makes sense to
  someone who already knows the answer.
- Read applicable project instructions and any documented voice profile
  (`voice-profile.md`, `STYLE.md`, or the local equivalent) before editing.
- Use American spelling unless the target or the venue says otherwise:
  center, normalization, hematocrit, behavior, labeled, analyze. British
  forms creep in from quoted sources and from earlier drafts, so check rather
  than assume.

## Resolve the register

Register is how a sentence sounds: contractions, person and voice, how much
jargon the reader shares, whether naming a method is the job or a lapse. It
differs enough between a slide and a manuscript that one set of defaults
cannot serve both, and the difference is not a single axis — a machine
learning conference paper and a clinical physics manuscript disagree with each
other about as much as either disagrees with a talk.

Load exactly one register file from `registers/` and apply it on top of
everything below:

- `talk.md` — slides, PI and progress updates, lab meetings, notes, chat,
  briefs. **This is the default when no register is named.**
- `journal-imrad.md` — a manuscript for a peer-reviewed journal in the
  Introduction / Methods / Results / Discussion tradition.
- `ml-conference.md` — a machine learning conference submission with open or
  semi-open review: ICLR, NeurIPS, ICML, CVPR.

Take the register from `$ARGUMENTS` when it is named. Otherwise use `talk.md`,
and say which register you used in the summary so a wrong guess is visible.
Never infer a register silently from the file type.

Where a register file and this file disagree, the register file wins: it exists
precisely to carry the rules that are not universal.

## Make each technical term earn its place

The threshold here is the talk register's. A journal register raises it: at a
venue, using the field's exact term is a correctness requirement rather than a
lapse. The register file sets how aggressive to be; the rule itself does not
change.

Replace a term with what it does unless **both** of these hold:

- the audience uses that exact word for that exact thing, routinely; and
- the plain phrasing would be longer, vaguer, or less accurate.

When a term does earn its place, the sentence around it should still land for a
reader who does not know it. When it does not, name the action and consequence
instead - and if the word is still worth having, put it in parentheses after the
plain version, not before it.

The failure this rule exists to catch is a sentence that names a method where it
should have stated what was done and why that matters. "The renderer integrates
the analytic curve over each exact acquired interval with a convergence-tested
quadrature; internal nodes are never treated as frames" names three methods and
states no consequence. What it meant: between two measured frames the bolus can
rise and fall a long way, so we integrate the fitted curve across each real gap
instead of joining the measured points with straight lines, and the extra time
points that integration needs never become data.

Two more habits worth naming:

- An abstract noun usually hides the verb that matters. Prefer "we checked that
  more sample points do not change the answer" over "convergence verification".
- A name for a quantity is not a statement about it. "Scale-free ratio 0.38"
  says nothing; "the model explains about two thirds of the signal, where 1.0
  means predicting zero" does.

## Be concise the way that helps

Concise means no wasted words, not fewer ideas. Cutting words that carry meaning
does not make prose shorter to read - it makes the reader go back.

Never cut:

- a unit, a denominator, or an `n`;
- the qualifier that makes a claim true rather than merely strong;
- the one clause that tells the reader why a number matters.

The most easily lost of these is the word separating a thing from the
measurement of it: "measured", "apparent", "reported", "estimated". Dropping
it reads as tightening and is often a change of claim. "The measured
amplitude is dominated by sampling position" is a result; "amplitude is
determined by where you sample" says the physical quantity changes with the
observer, which is false and which a reviewer will catch. The same slip runs
the other way: do not write a sentence that denies a property of the object
when what differs is the instrument. Coil sensitivity varying along a vessel
does not make two levels different blood; it makes the same concentration
produce different signal. Ask which noun the verb is really about.

Do cut: the sentence that restates the previous sentence, the preamble before
the point, the summary of what the reader just read, and any phrase that would
survive being deleted without the reader noticing.

Cut what the reader already assumes. A clause that claims credit for competent
practice tells them nothing and costs their attention: "and we check both
rather than assume them", "using standard methods", "after careful review".
The reader took the checking for granted the moment you described the
condition. **Where this applies depends on the register**: a Methods section
owes the reader the check as part of the rebuild recipe, while the same clause
in a talk or a Discussion is self-congratulation. The register file says which
case you are in.

Cut a contrast whose other half is just the negation of the first. "Dangerous
rather than harmless" asserts nothing, because harmless is what dangerous
already rules out; so do "a finding rather than a non-finding" and "we measured
it rather than guessing". The pattern also hides inside "not just X, but Y"
where Y is a restatement of X.

The test is not about the words. It is whether the reader, **at this point in
the text**, holds the belief being denied. A contrast can only correct an
expectation the writing has already created.

"The distortion is an overestimate rather than an attenuation" looks like it
earns its place, because attenuation is what most people expect of an arterial
measurement error. It does not, unless the text has said so first. If nothing
before it has told the reader that partial volume can only reduce the measured
value, "overestimate" already carries the direction and the second half only
says it is not the other one. Give the sentence that setup and the contrast
becomes load-bearing; leave the setup out and it is filler. So the fix is a
choice: add the expectation, or delete the antithesis.

"A bias change, not a precision change" survives in a passage that has just
been discussing precision. "Real rather than fake" survives nowhere.

When a contrast fails the test, keep the claim and cut the other half. The
sentence says exactly as much.

Lean is the target, not terse. The goal is prose with nothing in it that fails
to earn its space — which is a different instruction from making it short. A
sentence can be long and lean, and a short one can still carry a clause doing
no work.

The test is whether a first-time reader stops or re-reads. If a cut makes them
stop, it was not a cut.

## Never open a sentence with a digit

A sentence begins with a word, in every register. `49 examinations were
excluded` is wrong; `Forty-nine examinations were excluded` and `We excluded 49
examinations` are both right. This holds for a slide, a Slack message, a
caption, a table cell and a journal paragraph alike, because the reason is
typographic rather than stylistic: a period followed by a digit is ambiguous
with a decimal point.

Three repairs, best first:

1. **Rephrase so the sentence opens on a word.** `Contrast was present by the
   second frame in 49 examinations.` Almost always available, and usually
   better than what it replaced.
2. **Lead with the noun.** `Examinations excluded for early contrast numbered
   49.` Stiff, but legal.
3. **Spell it out.** Only for a small number carrying no unit. `Forty-nine` is
   fine; `Nine hundred and eighteen` is not, and `Five point four seconds` is
   absurd.

Never repair it by deleting the number, and never by moving it into the
previous sentence, where its denominator no longer sits beside it. Cutting a
denominator to fix a typographic problem trades a real error for a cosmetic
one.

In a marked-up document a number inside a macro is still a digit to the
reader, so check the rendered text rather than the source.

## Editing priorities

- State the actual point instead of announcing that it is important. Cut the
  stage directions that tell a reader how to receive a sentence rather than
  saying anything: "hold on to this", "note that", "it's worth emphasizing
  that", "keep this in mind", "remember that", "the key insight is". If the
  point needs weight, give it its own sentence or its own slide; an instruction
  to pay attention is not weight.
- Replace vague abstractions with the concrete subject, action, or consequence
  the text already supports.
- Prefer the shorter, more common word where it is exactly as accurate.
- Follow the register on contractions, person and voice. These are the rules
  that differ most between a slide and a manuscript, and guessing wrong is the
  most visible way to sound wrong.
- Vary sentence shape only where the rhythm has gone mechanical.
- Preserve uncertainty that belongs to the science; remove only stacked or empty
  hedging.
- Preserve the author's deliberate habits when documented or evident.

Do not change facts, numerical values, citations, paths, identifiers, code,
commands, config keys, schema names, or markup semantics. An identifier is a
literal: rewriting one to read better breaks the thing it points at. Do not edit
verbatim quotations or literal prompts unless the user includes them explicitly.

## Work under the hood

1. Delegate a bounded read-only pass when delegation is available. Give the
   worker the cross-agent rubric in `agents/humanize-auditor.md`,
   the exact target, the audience, **the register you resolved**, and any
   voice guidance; in Claude Code that
   rubric is the `humanize-auditor` subagent. Ask for high-confidence, actionable
   findings in both registers: machine phrasing and unearned jargon. Apply the
   rubric directly when delegation is unavailable.
2. Review the findings yourself. Ignore anything that flattens the author's
   voice, changes meaning, or swaps one generic phrase for another.
3. Edit the target directly.
4. Inspect the diff for meaning drift, dropped denominators, new repetition,
   broken markup, and changed literals.

## Finish

No audit report unless asked. Return the revised material or name the files
changed, name the register you applied, then a brief summary of the most
consequential edits. Say which
passages you left alone because changing them would alter meaning, and name any
term you kept along with why the audience needs it.

Adapted from Pedro H. C. Sant'Anna's `humanize` skill in
`pedrohcgs/claude-code-my-workflow` at commit
`9d371f0bf8a8bc99569feca3210ef5133af28d33`; see `THIRD_PARTY_NOTICES.md` in
this repository.