cratis-writing-voice-and-cadence
Review and revise existing prose so it reads as written by a person, by finding overused constructions and stock phrasing in one piece and structural sameness across a batch, then fixing both with specifics instead of injected variety, without changing any technical claim. Flags are editing prompts and never a verdict on who wrote something. Use when reviewing or rewriting documentation, release notes, pull request descriptions, posts or reviews for voice. Do not use for technical accuracy review, original drafting, authorship detection, or as a reason to touch approved copy without authorization.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- cratis-writing-voice-and-cadence
- license
- MIT
- description
- Review and revise existing prose so it reads as written by a person, by finding overused constructions and stock phrasing in one piece and structural sameness across a batch, then fixing both with specifics instead of injected variety, without changing any technical claim. Flags are editing prompts and never a verdict on who wrote something. Use when reviewing or rewriting documentation, release notes, pull request descriptions, posts or reviews for voice. Do not use for technical accuracy review, original drafting, authorship detection, or as a reason to touch approved copy without authorization.
02 资源文件 2
- 许可证LICENSE211 B
- 参考文档references/ai-tells.md25.2 KB
03 SKILL.md 正文
<!-- cratis-ai-managed: skills/cratis-writing-voice-and-cadence/SKILL.md -->
Writing voice and cadence
Material that is factually correct can still read as if nobody wrote it. The usual diagnosis is "it sounds like AI wrote it", and the usual response is to rewrite by feel. That tends to produce a second machine voice: new stock phrases in place of the old ones, a joke dropped in, a sentence chopped short for rhythm.
This skill works from what can be counted and what can be checked. Three things go wrong:
a handful of constructions recur often enough to be worth a second look, a body of work
falls into one shape, and underneath both, something only the author knew is missing.
It revises existing material. For drafting, use the skill for the content type:
cratis-release-notes for release notes and cratis-technical-examples for code
samples (both profiles), cratis-social-feed-post for feed posts (cratis/content) and
cratis-documentation-writing for pages (cratis/documentation).
Read the full catalog in references/ai-tells.md before running single-piece or batch checks, with a word list or regex and a batch threshold for each, and the studies behind them. IDs such as HV-02 below point to that file's Sources table.
This is an editing aid, not a detector
Read this before running any check.
People are poor at telling AI text from human text. In six experiments with 4,600 participants, readers could not reliably pick out AI-generated self-presentations, and the cues they leaned on, first-person pronouns and contractions among them, were flawed (HV-01, HV-02). In a separate paired-essay study, instructors identified the ChatGPT essay 70% of the time; subject expertise did not reliably improve performance (HV-03). Studies do find differences between human and model text, but in aggregate over many texts and within the genres and models they tested (HV-05, HV-06). None of that says who wrote a particular paragraph.
So these rules hold for every use of the skill:
- A flag means "read this passage again". It never means "AI wrote this".
- Never use a flag, a count or a detector score to accuse a person, grade them, or block their work. Don't combine flags into an "AI score".
- A contributor writing in a second or third language has their own rhythm. Fix what is unclear to the reader. Don't push them toward an arbitrary house style because a pattern list matched.
- Contractions, "I", humor, short sentences and typos prove nothing about who wrote a text (HV-02). Adding them so copy passes as human is the same mistake in reverse.
- A construction that carries a real distinction stays, however often the catalog lists it.
Never trade a claim for a smoother sentence
This is the part that makes a voice pass dangerous, and the reason to do one carefully instead of quickly.
The risk is not an obvious rewrite. It is a hedge dissolving into nicer phrasing. "There is no need to" becomes "without needing to", and a limit quietly widens. "Not its meaning" becomes "and leaves its meaning alone", and a distinction softens. Both read better. Both changed what the text asserts.
Before accepting any rewrite, confirm that:
- every identifier and every number present before is still present, and none was invented;
- every hedging word (not, never, only, may, unless, until) survives in substance;
- every stated limitation survives, including one that reads as an awkward caveat, because it is a caveat and it is deliberate;
- the closing limitation or evidence statement is not thinned, relocated into a subordinate clause, or dropped because it spoiled the ending.
A mechanical before-and-after check over identifiers, numbers and hedge words catches most of this before anyone reads a word. The catalog describes one. A person still reads every flagged pair, because a count can't tell a widened limit from a harmless rephrase.
Stop conditions
Stop and hand back when:
- a rewrite would change what the material claims;
- the named author hasn't supplied or accepted a perspective, detail or opinion being put in their mouth;
- the material is under an approval the rewrite would invalidate, and nobody has authorized a refresh;
- the request is to judge whether a person used AI, or to gate their work on a flag count;
- the copy is for Hacker News.
Reviewing or revising copy never includes publishing, scheduling, posting or replying. An agent hands the text back; a person decides what goes out.
The constructions
None of these is wrong. A single corrective tail can be the clearest sentence in the piece. What turns a construction into a tell is recurrence: the same move three times in a short post, or in the same position in every post of a series.
| Construction | What it looks like |
|---|---|
| Corrective tail | "…, not a fresh count." The sentence ends by correcting itself. "It's not X, it's Y" is the same reflex |
| Balanced semicolon | Two clauses of equal weight either side of a semicolon |
| "rather than" | The same correction carried by a different connective |
| Em-dash pivot | The dash used to swing into a closing clause |
| "That is what X is for" | A pointer sentence standing in for an explanation |
| Punchline fragment | A two- or three-word sentence landing a slogan: "They run." |
| Signpost pair | "That's the X. Here's the Y." Announcing the structure instead of having one |
| Labeled caveat | "One honest limit:" A limitation parked in its own closing paragraph |
| Aphoristic close | A tidy maxim as the last line, restating what the piece already said |
| Reflexive triplet | Three parallel items where the thought had one or two |
Vocabulary is a weaker signal than it looks. "Delve", "underscore" and "showcase" rose sharply in a large corpus of biomedical abstracts (HV-10), and a published editors' guide lists phrasing like "evolving landscape" as a possible sign (HV-25). The same guide says its signs are observations that prove nothing on their own (HV-23). Use the word lists to find a vague word and put the specific one in its place. When "robust" means what an engineer means by it, leave it.
Review a single piece
- Read it aloud once, start to finish. Most of these constructions are audible long before they are countable.
- Run the single-piece checks from the catalog: the word lists, the construction patterns, list shape, opening and close. Record each match with its sentence, so whoever reads the report can judge it in context.
- For each flag, ask what the sentence is standing in for. A significance word usually covers a missing measurement. A reflexive "X, not Y" often means nobody said what X does. A caveat in the last paragraph usually belongs inside an earlier sentence.
- Mark the passages that need something only the author has: a reason, a version, a result. Those go back to the author as questions.
Structural sameness is the more damaging half
A reader meeting the second piece in a series can recognize the format before reading a word of it, and a per-piece review can't see that. Put ten comparable pieces side by side, same channel and same content type, and compare openings, shapes, lengths and closes.
Openings come first. Classify each first sentence as an event, a problem, a question, direct address, a number, an identifier, or an abstract assertion ("A registration test can…"). Six of ten opening the same way, or three that share their first two words, is an uncalibrated trigger to inspect the batch for a template.
Then paragraph shapes: how many paragraphs, and how much each weighs. When most pieces run three or four paragraphs of about the same size, the format is doing the writing. Length across the batch tells the same story. Pieces on very different subjects shouldn't all land within a few words of each other.
Last, closes. Label each last paragraph as a result, a next step, an open question, a limit, a summary or a maxim. A summary or maxim in most of the batch is a template. So is the same labeled caveat at the bottom of every piece.
Within a piece, sentence length that barely moves reads as a monotone. Compare it with the rest of your own corpus; there is no correct spread, and short reference entries or numbered steps are allowed to be even.
The fix for a template is not a better template. Swapping every abstract opening for a question gives you ten question openings. Flag concentration in the batch, never one outlier, and don't adopt a target shape. With fewer than five comparable pieces, say so and skip the batch conclusions.
Fix with substance
When a piece reads as generated, what is usually missing is a fact. Varying sentence length on purpose or shuffling paragraph counts treats the symptom and grows a new pattern. Language models struggled to match the range of human stylistic variation in the genres studied (HV-06). Let differences in subject and purpose determine the shape, and add whatever makes this piece different from the last one:
- the specific artifact: the command, the event type, the file, the error text, the before-and-after;
- the named thing in place of the category: "the retry loop in the importer" for "complex workflows";
- a reason the author owns, in words they would say out loud, supplied by them;
- the limit, placed in the sentence it limits: "On macOS and Linux, the installer…".
Where a sentence has nothing to add, cut it. Concreteness has a ceiling too. In past headline experiments, extra concreteness helped headlines that were too vague and hurt ones that were already very concrete (HC-03). Packing identifiers into an opening won't rescue it.
If the source material doesn't contain the substance, don't supply it yourself. Ask the author, or leave the passage plain and accurate.
What a person leaves behind
These are signs that someone who knows the work was involved. Look for them in review and note which ones are missing. Never fabricate one to make copy read better; a fabricated detail is worse than an absent one.
- a named artifact the reader can open or run
- the exact version or environment, where it changes the outcome
- an engineering task a reader would recognize from their own week
- an observation kept apart from the inference drawn from it
- a credible counterexample, or the simpler alternative the author considered
- a material limit sitting in the sentence it qualifies
- a reason for a judgment, owned by the author
- a next step the reader can reproduce
- variation that follows from the subject
PostHog's published voice guide argues for much the same list: concrete nouns, directness, candor about limitations (DP-05). That is one company's judgment, with no measured effect.
Hedging that protects the writer
The other common complaint is "wishy-washy": copy so qualified that it never commits to anything. It usually comes from review language leaking into the material. Evidence, verification and approval wording belongs in the review record, and so do qualifiers that protect the writer without informing the reader. The claim rule below protects every hedge that is true and would change what the reader does. It does not protect review residue: move the evidence to the review record and state the capability plainly.
Who is speaking, and to whom
None of these choices makes text sound human by itself. Each depends on the piece.
Instructions usually read best addressed to the person following them: "run", "you'll see". Reference pages and explanations often don't need "you" at all, and forcing it in makes them chatty. Use it where someone is being told what to do.
A company account is a team talking when it reports what the team did: "we shipped", not the company name in the third person. When the subject is how the product behaves, the product can be the subject.
Writing under a person's name can carry opinion, judgment and preference, and those belong to the named author. Prose under a byline in the impersonal third person reads like documentation with a name on it. How personal it gets is the author's call.
A question earns its place when the argument raised it and the author wants the answer. One bolted on to collect replies is bait.
First person is not a license to invent
Never invent experience, anecdotes, opinions, customers, incidents, benchmarks or quotes. That applies to a named founder, a company account, and the vague "one team we worked with". A hypothetical example is labeled as one.
Copy in the first person needs the named author's own input: the detail, the opinion and the reason come from them. It also needs their sign-off on the final wording, and until it has both it stays a draft. A meaningful edit to first-person copy goes back to them as well. Spotting the gap is part of the review ("this paragraph needs the real reason you picked PostgreSQL"). Filling it in on the author's behalf is out of bounds.
Channel policies on AI-assisted writing
LinkedIn has stated its position (HV-18, HV-19):
It's ok to use AI to help you write, but your posts and comments need to represent your voice and your perspectives.
When content appears to be generated by AI and lacks clear perspective, it is less likely to be widely distributed beyond a person's immediate network.
This is LinkedIn's own account of its system, and it hasn't been independently verified. Read the two sentences together. Help with language is allowed when the post is the member's own view, and what LinkedIn says it limits is content that looks generated and has no clear perspective. Neither sentence says AI help alone costs reach. Elsewhere the evidence on how readers react to AI assistance is mixed: a preprint, not peer reviewed, found some assistance raised engagement while lowering perceived authenticity (HV-11), and a review of 47 journalism studies found no consistent trust penalty (HV-12). For a reviewer, "does this say something the author actually thinks?" matters more than any word list.
Hacker News draws a harder line. The comment section of its guidelines says: "Don't post generated text or AI-edited text. HN is for conversation between humans." (HC-16)
The rule is written for comments. Cratis applies it, as its own stricter policy, to everything it posts there: nothing Cratis posts to Hacker News is written or edited by AI, whether title, text or comment. Don't run a voice pass on HN copy. You can help the person check facts and links.
Work in tranches that can be read
Rewriting is not a batch operation. Any body of material large enough to have a detectable voice is too large to rewrite in one pass with judgment, and a fast pass replaces one detectable format with another. Rewrite a tranche, read it, and only then continue.
Where material carries a recorded approval, a rewrite invalidates it. Recording a fresh approval over copy nobody has read makes the record assert something false, after which every downstream check agrees with it. Size the tranche to what its owner will actually read.
04 同仓库更多 Skills
spf13-go
Review Go library APIs, package boundaries, tests, iterators and standard-library choices. Load for broad design or idiom reviews after the repository-owned Go skills.
samber-golang-error-handling
Review Go error creation, wrapping, inspection and logging boundaries. Load when changing caller-visible failures after go-errors-and-context.
samber-golang-context
Design Go context propagation, cancellation, deadlines and request metadata. Load for operation-lifetime changes or context-related leaks after go-errors-and-context.
jetbrains-go-modern-guidelines
Choose version-compatible modern Go syntax and standard-library APIs. Load when modernizing touched Go code after reading go.mod and build constraints.
go-testing
Write and review Go unit, contract, transport, race, fuzz, and deterministic concurrency tests. Use for new behavior, bug fixes, flaky tests, and public API parity evidence.
go-release-modules
Review Go module dependencies, minimum versions, compatibility, semantic labels, release-action tags, and proxy discoverability. Use for release preparation, retractions, and major-version migration planning.