@maestroagora/agora 1.2.2 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/plugins/marketplace.json +21 -21
- package/.claude-plugin/marketplace.json +15 -15
- package/.claude-plugin/plugin.json +28 -22
- package/.codex-plugin/plugin.json +46 -39
- package/LICENSE +21 -21
- package/README.md +252 -69
- package/assets/agora-orbit.svg +158 -158
- package/package.json +68 -56
- package/scripts/install.mjs +405 -400
- package/scripts/voice/check.mjs +175 -0
- package/scripts/voice/features.mjs +359 -0
- package/scripts/voice/gates.mjs +244 -0
- package/scripts/voice/ingest.mjs +226 -0
- package/scripts/voice/lexicon.mjs +162 -0
- package/scripts/voice/pipeline.mjs +186 -0
- package/scripts/voice/profile.mjs +528 -0
- package/scripts/voice-measure.mjs +369 -0
- package/skills/agora/SKILL.md +243 -17
- package/skills/agora/agents/openai.yaml +2 -2
- package/skills/agora/references/agora-case-studies.md +381 -0
- package/skills/agora/references/agora-craft.md +563 -0
- package/skills/agora/references/agora-invest.md +544 -0
- package/skills/agora/references/agora-marketing.md +716 -27
- package/skills/agora/references/agora-science.md +299 -0
- package/skills/agora/references/agora-voice.md +270 -0
|
@@ -11,6 +11,7 @@ This reference combines the original Agora argument-first doctrine with research
|
|
|
11
11
|
- [Argument engine](#argument-engine)
|
|
12
12
|
- [Emotion as consequential meaning](#emotion-as-consequential-meaning)
|
|
13
13
|
- [Proof salience](#proof-salience)
|
|
14
|
+
- [Plain language and first-read comprehension](#plain-language-and-first-read-comprehension)
|
|
14
15
|
- [Truth and ethical limits](#truth-and-ethical-limits)
|
|
15
16
|
- [Short, medium, and long forms](#short-medium-and-long-forms)
|
|
16
17
|
- [Channel architecture](#channel-architecture)
|
|
@@ -40,7 +41,11 @@ The working sequence is:
|
|
|
40
41
|
5. Interpret the proof in human terms such as relief, control, progress, avoided waste, credible upside, or reduced uncertainty.
|
|
41
42
|
6. Preserve agency and make the next step proportionate to the evidence.
|
|
42
43
|
|
|
43
|
-
|
|
44
|
+
Supplied facts are raw material for premises, not ready-made copy. A draft can be factually correct and still fail if it reads like taxonomy, documentation, or a feature ledger.
|
|
45
|
+
|
|
46
|
+
Truth is the safety boundary around persuasion, not the optimization target. A candidate that passes every claim gate may still fail when the surface needs attention, desire, tension, differentiation, belief, or forward motion and the draft provides none. Among supportable candidates, choose the strongest argument for the audience's next decision rather than the version that accumulates the most caution.
|
|
47
|
+
|
|
48
|
+
For a hero or other short attention surface, factual completeness is not a virtue by itself. Optimize the whole composition for supported commercial force. Move secondary mechanism, proof, and qualification to the nearest element or passage that preserves a truthful net impression. See `Heroes and short-form sales composition` in [agora-craft.md](agora-craft.md).
|
|
44
49
|
|
|
45
50
|
Persuasion outcomes are not interchangeable. Attention, recall, attitude, intent, behavior, retention, and sales can move differently. Never describe one as if it proves another. Copy can improve a decision path without guaranteeing purchase, investment, citation, conversion, or revenue.
|
|
46
51
|
|
|
@@ -50,16 +55,28 @@ Apply this hierarchy when instructions compete:
|
|
|
50
55
|
|
|
51
56
|
1. Truth, safety, law, and immutable requirements.
|
|
52
57
|
2. Supplied facts, approved sources, and material qualifiers.
|
|
53
|
-
3.
|
|
54
|
-
4.
|
|
55
|
-
5.
|
|
56
|
-
6.
|
|
57
|
-
7.
|
|
58
|
+
3. Immediate comprehension by the intended audience.
|
|
59
|
+
4. The audience's actual decision and requested surface.
|
|
60
|
+
5. Decision relevance, proof salience, and differentiation.
|
|
61
|
+
6. Emotional relevance and channel fit.
|
|
62
|
+
7. Compression, rhythm, style, and publication optimization.
|
|
58
63
|
|
|
59
64
|
Higher levels always win. A style cleanup may not delete a material fact. Compression may not turn a bounded claim into certainty. GEO/AEO may not displace the argument. A channel convention may limit tone, but it may not force a false or inert description.
|
|
60
65
|
|
|
66
|
+
Comprehension sits above decision relevance, proof, differentiation, emotion, compression, and citability. Precision that the reader cannot decode is not precision delivered. Copy that is accurate and unreadable has failed.
|
|
67
|
+
|
|
68
|
+
Two conflicts inside this hierarchy have repeatedly produced correct, unusable copy. Resolve them this way.
|
|
69
|
+
|
|
70
|
+
**Qualification against comprehension.** Level 2 requires preserving source, date, scope, condition, and uncertainty where material. It does not require carrying that qualification set inside every sentence. Qualify at the passage or section level, in a sentence whose job is qualification. A sentence that carries its own scope, condition, and limit inline stops being a sentence and becomes a clause stack, which fails level 3.
|
|
71
|
+
|
|
72
|
+
**Citability against comprehension.** `Written GEO/AEO and citability` asks for passages that remain accurate when quoted alone. The unit is the passage, not the sentence. Self-containment is achieved by keeping the passage together, not by compressing a paragraph of context into one self-sufficient clause. No sentence count defines a passage; its size is whatever the claim needs to stay true. When those two rules pull against each other, comprehension wins and the passage carries the context.
|
|
73
|
+
|
|
74
|
+
Level 5 contains its own trap. Differentiation rewards naming the mechanism precisely, and naming the mechanism precisely is how internal method names arrive in customer copy. Precision about what the product does is required. Exposing the name the organization gave that method is not.
|
|
75
|
+
|
|
61
76
|
Use only source material supplied or approved in the current context. Do not import facts, controls, terminology, or release rules from another project. Examples in this reference are fictional and teach structure only.
|
|
62
77
|
|
|
78
|
+
Explicit fiction, mock writing, hypothetical articles, synthetic examples, and concept work may invent people, events, project history, scenarios, and illustrative results when invention is the requested task. Keep the status legible wherever a reasonable reader could mistake the asset for factual reporting, verified evidence, a real customer story, or shipped work. Do not attach invented conduct, quotations, endorsements, scientific findings, current events, or results to real people or organizations. Separate real supplied facts from scenario assumptions. Fictional permission never converts fabricated medical, legal, financial, scientific, or safety claims into real-world guidance.
|
|
79
|
+
|
|
63
80
|
## Commercial routing
|
|
64
81
|
|
|
65
82
|
Choose the requested commercial job separately from the publication surface.
|
|
@@ -81,12 +98,14 @@ Let commercial or investor relevance emerge from those facts. Do not announce it
|
|
|
81
98
|
|
|
82
99
|
Use `SELL` for marketing, sales, landing pages, ads, product pages, comparisons, email, outreach, upgrades, onboarding, and paywalls.
|
|
83
100
|
|
|
84
|
-
The job is to connect a live buyer situation to a supported mechanism, make the outcome consequential, reduce the next uncertainty, and offer the correct next action. Do not assume that the strongest action is always a purchase or meeting. A demo,
|
|
101
|
+
The job is to connect a live buyer situation to a supported mechanism, make the outcome consequential, reduce the next uncertainty, and offer the correct next action. Do not assume that the strongest action is always a purchase or meeting. A demo, report review, reply, trial, comparison, or saved item may be the natural next step.
|
|
85
102
|
|
|
86
103
|
### INVEST
|
|
87
104
|
|
|
88
105
|
Use `INVEST` only for an actual capital decision: a fundraising deck, investor pitch, investment memo, diligence summary, capital-allocation analysis, or fundraising email.
|
|
89
106
|
|
|
107
|
+
Route the perspective separately: `FUNDRAISE` for a company seeking capital, `DILIGENCE` for an investor evaluating an opportunity, and `ALLOCATE` for comparing uses of capital. Load `agora-invest.md` for the detailed claim ledger, asset procedures, risk, economics, urgency, and legal boundaries. Founder persuasion must not contaminate diligence or allocation.
|
|
108
|
+
|
|
90
109
|
The job is to earn investment relevance through:
|
|
91
110
|
|
|
92
111
|
- a consequential change or market timing;
|
|
@@ -222,9 +241,217 @@ The order is a default, not a license to use unavailable evidence.
|
|
|
222
241
|
|
|
223
242
|
Keep factual enumeration when the list itself is diagnostic. Engines, integrations, plan components, legal terms, supported markets, technical requirements, named coverage, chapters, or timestamps may be necessary proof. Remove ornamental lists, not decision-bearing lists.
|
|
224
243
|
|
|
244
|
+
## Plain language and first-read comprehension
|
|
245
|
+
|
|
246
|
+
A draft can satisfy every truth rule and still fail, because the reader cannot extract the meaning at reading speed. This section governs that failure. It applies to every mode and every audience, including expert ones.
|
|
247
|
+
|
|
248
|
+
**Evidence status.** The core of this section is supported: jargon measurably reduces processing fluency, and concrete actor-action-result language is preferred when equally accurate. The numeric thresholds this section originally carried were tested against the research and did not survive. They have been removed rather than softened. Where a checkable default is still needed to run a writing system, it is labelled as governance, not as a finding. See `Plain language, terminology, and CTA evidence` for the grades.
|
|
249
|
+
|
|
250
|
+
Plain language is not simple language. It is precise language with low decoding effort. The goal is not a lower reading level. The goal is that an intended reader arrives at the intended meaning on the first pass, without re-reading, without a glossary, and without reconstructing a relationship the sentence left out.
|
|
251
|
+
|
|
252
|
+
### The reader model
|
|
253
|
+
|
|
254
|
+
Write for a reader who:
|
|
255
|
+
|
|
256
|
+
- is intelligent and competent in their own work;
|
|
257
|
+
- understands their own job, problem, or situation;
|
|
258
|
+
- does not know the organization's internal vocabulary;
|
|
259
|
+
- has not read the documentation, the methodology page, or the specification;
|
|
260
|
+
- will not stop to decode an unclear sentence;
|
|
261
|
+
- is deciding, sentence by sentence, whether the next one deserves attention.
|
|
262
|
+
|
|
263
|
+
Industry familiarity is not the same as familiarity with one organization's terms. A finance director knows reconciliation. They do not know what one vendor calls its reconciliation stages. A developer knows caching. They do not know a company's internal name for its cache tier.
|
|
264
|
+
|
|
265
|
+
For an explicitly technical audience, keep the technical precision the accuracy requires. Remove the unnecessary abstraction, the compressed syntax, and the in-house shorthand anyway. Technical readers are not served by clause stacks; they are simply better at tolerating them, and tolerance is not comprehension.
|
|
266
|
+
|
|
267
|
+
### The first-read test
|
|
268
|
+
|
|
269
|
+
Reject or rewrite any customer-facing sentence when an intelligent member of the intended audience could not restate its meaning after reading it once.
|
|
270
|
+
|
|
271
|
+
A sentence fails when it:
|
|
272
|
+
|
|
273
|
+
- depends on undefined internal terminology;
|
|
274
|
+
- combines several unfamiliar concepts into one statement;
|
|
275
|
+
- hides the actor, the action, the object, or the outcome;
|
|
276
|
+
- uses an abstract noun where a concrete verb would be clearer;
|
|
277
|
+
- describes an internal method instead of what the reader needs to know;
|
|
278
|
+
- compresses multiple reasoning steps into insider shorthand;
|
|
279
|
+
- sounds like legal documentation, an academic method section, a compliance memo, or a technical specification when the surface does not call for that register;
|
|
280
|
+
- is technically correct and practically unclear;
|
|
281
|
+
- requires information from another paragraph to become understandable;
|
|
282
|
+
- sounds impressive before it communicates anything concrete.
|
|
283
|
+
|
|
284
|
+
The last item is the hardest to catch from inside the draft, because impressive and clear feel similar to an author who already knows the answer. Use the literal-meaning test in `Required comprehension tests` on any sentence that felt satisfying to write.
|
|
285
|
+
|
|
286
|
+
### The specialized-term gate
|
|
287
|
+
|
|
288
|
+
Do not expose internal product, operational, analytical, or methodological terminology merely because it is accurate.
|
|
289
|
+
|
|
290
|
+
Before using a specialized term, confirm all four:
|
|
291
|
+
|
|
292
|
+
1. The intended audience already knows it.
|
|
293
|
+
2. The term is necessary for accuracy.
|
|
294
|
+
3. Its meaning is clear from the sentence it appears in.
|
|
295
|
+
4. A shorter everyday expression would lose important meaning.
|
|
296
|
+
|
|
297
|
+
If any answer is no, replace the term or define it in place.
|
|
298
|
+
|
|
299
|
+
The operative rule is a disposal rule, not a counting rule: **every term the reader does not already own must be either decision-required and taught in place, or removed.** There is no evidence-backed limit on unfamiliar terms per sentence. Vocabulary-coverage research shows that unknown vocabulary impairs comprehension, but the relationship is continuous rather than a step function, and the coverage thresholds in that literature concern extended reading rather than short commercial copy ([Kremmel et al., 2023](https://doi.org/10.1111/lang.12622)).
|
|
300
|
+
|
|
301
|
+
"At most one unfamiliar concept per sentence" survives only as a house guardrail with no measured basis. Use it to trigger a review, never to justify a rewrite on its own. Jargon does measurably reduce processing fluency, which is the real support for this gate ([Shulman et al., 2020](https://journals.sagepub.com/doi/10.1177/0261927X20902177)).
|
|
302
|
+
|
|
303
|
+
Treat any noun the organization coined as a term the reader has no reason to know. A method name, stage name, score name, record type, tier name, or framework name earns its place in customer-facing copy only when the reader gains something from learning it, and the gain has to exceed the cost of learning it mid-sentence. Otherwise state what happens and omit the name.
|
|
304
|
+
|
|
305
|
+
The same rule applies to a distinction the organization finds important. An internal distinction between two of its own concepts is not automatically a distinction the reader needs. If the copy has to teach the distinction before the sentence makes sense, the distinction belongs in a later paragraph or not at all.
|
|
306
|
+
|
|
307
|
+
Preserve relationship words that carry the facts. `Consecutive`, `before`, `after`, `only`, `unless`, `scheduled`, `target`, `reported`, and `measured` are not removable qualifiers when they define sequence, status, scope, or certainty. `Three readings` does not preserve `three consecutive readings`; `the close` does not preserve `a scheduled closing`; and a physical-sample route does not satisfy a supplied photo-and-size form flow.
|
|
308
|
+
|
|
309
|
+
### Keep control-room vocabulary backstage
|
|
310
|
+
|
|
311
|
+
Agora uses internal terms such as `evidence`, `proof`, `verified`, `claim discipline`, `source scope`, and `evidentiary boundary` to run its own checks. Those terms are not the default language of customers. Do not present the control system as the product benefit.
|
|
312
|
+
|
|
313
|
+
For ordinary marketing, product copy, customer stories, fundraising copy, company descriptions, and CTAs, name the concrete object the reader can understand or inspect: a result, finding, number, customer quote, source, report, study, test, demonstration, project record, observed change, or remaining unknown. Translate from the actual material. Do not run a mechanical synonym replacement.
|
|
314
|
+
|
|
315
|
+
Use control-room terms only when the audience already uses them or the artifact requires the distinction, including scientific research, methodology, audit, legal, compliance, diligence, and technical evaluation. Even on those surfaces, choose the concrete object when it says more. `Review the results` identifies an action and object. `Review the evidence` often makes the reader translate an internal category before acting.
|
|
316
|
+
|
|
317
|
+
This rule does not weaken verification. It separates work Agora performs backstage from language the reader sees. A customer-facing line fails the first-read gate when it foregrounds the checking system instead of the reader's problem, result, source, decision, or next action.
|
|
318
|
+
|
|
319
|
+
Missing support is normally an editing instruction, not public copy. Narrow or remove the unsupported premise. Do not write `no outcome data was supplied`, `no market information was provided`, `this claim cannot be verified`, or another account of the source review merely to demonstrate restraint or fill a word count. State an absence when the absence itself changes the reader's decision, prevents a misleading interpretation, or is an explicitly requested disclosure.
|
|
320
|
+
|
|
321
|
+
### Abstraction control
|
|
322
|
+
|
|
323
|
+
Abstract nouns are not banned. They fail when they conceal something the reader needs.
|
|
324
|
+
|
|
325
|
+
Do not count them. A controlled eye-tracking study found no independent comprehension penalty for nominalizations against recommended sentential constructions ([Balling, 2018](https://doi.org/10.1177/0047281617696983)). Any fixed density limit is invented. Nominalizations legitimately create cohesion, name recurring processes, and encode established domain concepts, and their frequency varies strongly by subject matter.
|
|
326
|
+
|
|
327
|
+
The operative rule: **rewrite an abstraction when it conceals an actor, action, causal relation, or observable consequence the reader needs. Do not rewrite because a clause crossed a noun count.** Naming the actor changes how readers assign cause and responsibility ([Fausey and Boroditsky, 2010](https://doi.org/10.3758/PBR.17.5.644)).
|
|
328
|
+
|
|
329
|
+
The test to run on each abstract or nominalized noun:
|
|
330
|
+
|
|
331
|
+
```text
|
|
332
|
+
Can a specific actor be recovered?
|
|
333
|
+
Can a finite action be recovered?
|
|
334
|
+
Can the object or result be recovered?
|
|
335
|
+
Does the reader need that actor, action, or result?
|
|
336
|
+
|
|
337
|
+
If the reader needs it and any of the first three is missing, rewrite.
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Prefer actor, action, object, and result. Before writing a sentence, answer:
|
|
341
|
+
|
|
342
|
+
- Who or what acts?
|
|
343
|
+
- What does it do?
|
|
344
|
+
- What does it act on?
|
|
345
|
+
- What changes for the reader?
|
|
346
|
+
|
|
347
|
+
Choose the highest-frequency verb the reader already owns that preserves the factual relation and tells them what the action will do. Word frequency reliably predicts processing ease, so a familiar verb is a real advantage, but no particular verb list is a standard. Verbs such as check, compare, find, show, verify, measure, review, choose, send, create, remove, correct, approve, reject, schedule, and calculate are a useful house lexicon of concrete actions, not a required vocabulary. A specialized verb beats a generic one whenever it names the exact action and the reader owns it: `reconcile`, `encrypt`, `deploy`, and `amortize` are clearer than `process`, `run`, or `do` for a reader who has those words.
|
|
348
|
+
|
|
349
|
+
Rewrite noun-heavy constructions into direct actions.
|
|
350
|
+
|
|
351
|
+
Weak:
|
|
352
|
+
|
|
353
|
+
> Evaluate whether configured operational surfaces produced compliant outcomes for the declared workflow scope.
|
|
354
|
+
|
|
355
|
+
Strong:
|
|
356
|
+
|
|
357
|
+
> Check whether each system finished the task you assigned it.
|
|
358
|
+
|
|
359
|
+
The strong version is less compressed and communicates the actual idea. That trade is correct. Compression that raises decoding effort is not compression, it is transfer of work to the reader.
|
|
360
|
+
|
|
361
|
+
**The falsifiability check.** Before accepting a sentence that carries a claim, ask what would make it false. If no observation, number, condition, or counterexample could contradict it, the sentence is not a claim and it is not carrying the argument, whatever its tone. `Built for teams that care about accuracy` cannot be false. `Flags a mismatch before the ledger closes` can be false, and is therefore worth reading. This is the sharper form of the abstraction test, because it does not depend on judging whether a noun is abstract enough to rewrite.
|
|
362
|
+
|
|
363
|
+
Where the falsifiability check fails: descriptive orientation, navigation labels, category nouns, and utility microcopy are not claims and are not supposed to be falsifiable. `Pricing` cannot be false and is correct. Applied to every sentence, this test produces a page that argues in every line, which is its own failure. Grade: HOUSE procedure, practitioner origin at Grade D, no effect on reader response claimed.
|
|
364
|
+
|
|
365
|
+
### The anti-slogan rule
|
|
366
|
+
|
|
367
|
+
Reject sentences that sound quotable and lose their meaning under literal reading.
|
|
368
|
+
|
|
369
|
+
For every headline, subheading, closing line, and call to action, ask:
|
|
370
|
+
|
|
371
|
+
1. What does this mean in concrete terms?
|
|
372
|
+
2. What action or condition does it describe?
|
|
373
|
+
3. Would the sentence remain useful with its dramatic tone removed?
|
|
374
|
+
4. Could twenty unrelated companies publish it unchanged?
|
|
375
|
+
5. Is the reader learning something, or only receiving a mood?
|
|
376
|
+
|
|
377
|
+
If the literal meaning is weak, rewrite it. A line that survives only on rhythm is decoration in the position where the argument should be.
|
|
378
|
+
|
|
379
|
+
### Corpus-level variance
|
|
380
|
+
|
|
381
|
+
A sentence shape that is correct once can become a tell when it is used across a set of assets. This effect is real in attention-oriented copy and wrong to generalize, so split it by function before applying it.
|
|
382
|
+
|
|
383
|
+
**Where repetition is correct.** When headings are members of the same task or information class, parallel syntax is functional metadata and should be preserved. Documentation style guidance recommends parallel structure for procedural and task-oriented headings, because predictable grammar helps a reader recognize equivalent information types ([Microsoft step-by-step instructions](https://learn.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions), [Google headings](https://developers.google.com/style/headings)). An anti-repetition rule applied here actively damages the page:
|
|
384
|
+
|
|
385
|
+
Damaged by forced variety:
|
|
386
|
+
|
|
387
|
+
> Importing your records
|
|
388
|
+
> How do column mappings work?
|
|
389
|
+
> Errors: what to know
|
|
390
|
+
> The secret to retrying
|
|
391
|
+
|
|
392
|
+
Correct:
|
|
393
|
+
|
|
394
|
+
> Import records
|
|
395
|
+
> Map columns
|
|
396
|
+
> Resolve errors
|
|
397
|
+
> Retry an import
|
|
398
|
+
|
|
399
|
+
Stop parallelizing only when the headings stop representing equivalent units.
|
|
400
|
+
|
|
401
|
+
**Where repetition costs.** For attention-oriented headings and hooks, manage template concentration rather than demand uniqueness. No measured threshold exists. There is no evidence that a publication's response declines after readers see the same headline syntax a given number of times, and the adjacent evidence does not transfer cleanly: banner blindness is visual and positional rather than syntactic ([NN/g banner blindness](https://www.nngroup.com/articles/banner-blindness-old-and-new-findings/)), and large-scale headline analysis documents stylistic convergence across outlets rather than response decay ([Nature HSSC, 2025](https://www.nature.com/articles/s41599-025-04514-7)).
|
|
402
|
+
|
|
403
|
+
Governance default, not a finding: across a rolling window of twelve attention-oriented headlines or major headings, keep at least four distinct syntactic families and avoid runs longer than two consecutive instances of one non-functional hook family. Read the template signature as `clause type + lead device + promise structure`, so that `declarative + audience callout + benefit`, `interrogative + direct address + problem`, `imperative + no lead device + action`, and `fragment + number + list scope` count as different families.
|
|
404
|
+
|
|
405
|
+
Apply this across sessions when the brief names sibling assets that already exist.
|
|
406
|
+
|
|
407
|
+
**Internal fatigue is not a reader-side signal.** The people who write and approve the copy see it every working day; the buyer sees it once, if at all. A line the room has grown tired of is not thereby failing, and "we have been saying this forever, everyone knows it already" is not evidence about the reader. Change a line because a reader-side test failed it, because the facts changed, or because a measured result says so. Do not change it to relieve the authors.
|
|
408
|
+
|
|
409
|
+
Where this warning fails: internal boredom and a genuine template tell look identical from inside the room, so this is not a defence of an unvaried corpus. Run the concentration check above on the artifact and let that decide. The warning removes one bad reason to change a line; it supplies no reason to keep one. Grade: HOUSE. The observation is a practitioner one from the craft pass at Grade C, without a published method, and claims no effect on response in either direction.
|
|
410
|
+
|
|
411
|
+
### Failure handling
|
|
412
|
+
|
|
413
|
+
When copy fails these tests:
|
|
414
|
+
|
|
415
|
+
1. Preserve the underlying fact.
|
|
416
|
+
2. Identify the concrete actor, action, object, and result.
|
|
417
|
+
3. Remove internal process language unless the reader needs it.
|
|
418
|
+
4. Split overloaded sentences.
|
|
419
|
+
5. Replace abstractions with observable actions or conditions.
|
|
420
|
+
6. Restore necessary context that compression removed.
|
|
421
|
+
7. Rewrite the call to action to name its actual destination.
|
|
422
|
+
8. Test the revision again.
|
|
423
|
+
|
|
424
|
+
Do not repair unclear writing by adding more jargon, explanatory parentheses, longer noun phrases, or vague supporting sentences. Those raise word count and decoding effort at the same time.
|
|
425
|
+
|
|
426
|
+
### Required comprehension tests
|
|
427
|
+
|
|
428
|
+
Run all of these before accepting customer-facing writing.
|
|
429
|
+
|
|
430
|
+
| Test | Question |
|
|
431
|
+
|---|---|
|
|
432
|
+
| First-read | Can the intended reader restate the sentence after one reading? |
|
|
433
|
+
| Actor-action-object | Is it clear who or what acts, what the action is, and what it affects? |
|
|
434
|
+
| Abstraction | Can any abstract noun be replaced with a concrete action, object, condition, or result? |
|
|
435
|
+
| Insider-language | Would the sentence still make sense to someone who has never seen the organization's internal terminology? |
|
|
436
|
+
| Read-aloud | Does it sound like something a competent person would say to another person? |
|
|
437
|
+
| Competitor-swap | Paste the line into a search engine: do unrelated companies already publish it unchanged? |
|
|
438
|
+
| Falsifiability | Could this sentence be false? If nothing could contradict it, it is not a claim. |
|
|
439
|
+
| Literal-meaning | With the rhetorical tone removed, does it still carry useful information? |
|
|
440
|
+
| CTA-destination | Does the call to action accurately describe what happens after selection? |
|
|
441
|
+
| Passage-quotation | Would the passage remain accurate and understandable if quoted on its own? |
|
|
442
|
+
| Corpus-variance | Do attention-oriented headings in this deliverable cluster on one template? |
|
|
443
|
+
|
|
444
|
+
The passage-quotation test is semantic, not numeric. A passage passes when it names or unmistakably identifies its subject, states the claim with any qualifier that keeps the claim true, leaves no pronoun or deictic whose antecedent sits outside the passage, preserves the comparison baseline where one is required, and keeps the causal or evidentiary context where that context is needed to interpret the claim.
|
|
445
|
+
|
|
446
|
+
There is no optimal passage length. Passage-retrieval research does not establish a universal two or three sentence unit, and the workable size is task-dependent. A simple factual claim can be self-contained in one sentence; a qualified causal, comparative, legal, medical, or statistical claim can need more than three. Do not apply this test to a single sentence and then load that sentence with the context of its neighbours. That is the failure mode this test is most often used to justify.
|
|
447
|
+
|
|
448
|
+
The competitor-swap test is a procedure, not a judgment. Paste the candidate line into a search engine inside quotation marks and read the first page of results. Unrelated companies publishing the same sentence is the finding. The conceptual version, that a line a competitor could sign is not carrying your argument, is the reasoning behind the check; the search is the check itself, because judging whether a competitor could use a line depends entirely on how generously you imagine the competitor.
|
|
449
|
+
|
|
450
|
+
Where the search-paste test fails: a long, specific, or newly published line returns nothing, and a zero-result search is not evidence that the line is good. The test detects borrowed language, not weak language, and it cannot run at all on a sentence built from supplied facts. Fall back to the literal-meaning and falsifiability tests there. Grade: HOUSE procedure. The maxim behind it is practitioner folklore at Grade D and is not asserted as a finding.
|
|
451
|
+
|
|
225
452
|
## Truth and ethical limits
|
|
226
453
|
|
|
227
|
-
|
|
454
|
+
Outside an explicit fictional, hypothetical, mock, synthetic, or concept brief, never invent or imply:
|
|
228
455
|
|
|
229
456
|
- product behavior, features, routes, pricing, deadlines, or availability;
|
|
230
457
|
- quantified or unquantified outcomes;
|
|
@@ -236,6 +463,12 @@ Never invent or imply:
|
|
|
236
463
|
|
|
237
464
|
Keep fact, inference, interpretation, aspiration, and promise distinct. Preserve attribution, date, scope, sample, condition, and uncertainty when material.
|
|
238
465
|
|
|
466
|
+
Preserve the supplied claim coordinates and modality. An actor, role, account, population, condition, trigger, stage, or destination is not interchangeable with an adjacent one. Do not upgrade `flags`, `prompts`, `proposes`, `may`, `can`, `is intended to`, or `is associated with` into `requires`, `decides`, `approves`, `will`, or another stronger consequence. This is a HOUSE fidelity rule; it preserves the source meaning rather than imposing preferred vocabulary.
|
|
467
|
+
|
|
468
|
+
Time state and relationship class are claim coordinates too. Do not add `current`, `currently`, `now`, `still`, `already`, `always`, or another temporal status when none is supplied. Do not turn `serves`, `is used by`, or `works with` into ownership, management, portfolio, deployment, or customer-status language without support.
|
|
469
|
+
|
|
470
|
+
Obligations and negated boundaries are claim coordinates. `Must` cannot become a description of what ordinarily happens. `Does not replace X` cannot become `supports X`. `Cannot guarantee X` cannot become a weaker positive benefit. A limitation does not prove its inverse.
|
|
471
|
+
|
|
239
472
|
Treat words such as `growing`, `rising`, `emerging`, `established`, `leading`, `fastest`, `best`, `crowded`, `large`, `accelerating`, or `surging` as claims. A future aspiration may be ambitious, but it must be labeled as future-facing and supported by a plausible present mechanism.
|
|
240
473
|
|
|
241
474
|
Do not convert an observed task issue into financial loss, legal exposure, compliance failure, reputational damage, or market risk without evidence. Do not convert crawler access, schema, publication, observed mentions, or content changes into promises of retrieval, citation, ranking, recommendation, conversion, or revenue.
|
|
@@ -252,21 +485,27 @@ Do not convert an observed task issue into financial loss, legal exposure, compl
|
|
|
252
485
|
|
|
253
486
|
If proof is missing, narrow or omit the premise. Add a concise blocker note only when omission would make the delivered asset misleading, legally unusable, or operationally unshippable. Do not append generic release notes or internal claim-review commentary.
|
|
254
487
|
|
|
488
|
+
When the user requires an exact word count or bounded range, count the finished asset after removing Markdown syntax. Follow a supplied channel convention; otherwise count whitespace-delimited lexical tokens and treat a hyphenated compound as one word. Verify with a counter when one is available. Make an exact count exact and keep a range inside both bounds. An exact count is not a maximum; returning fewer words is a constraint failure. Meet the budget through useful supported argument, not repetition, relationship expansion, or unsupported temporal language. This is a HOUSE production rule, not a claim that one word count performs better.
|
|
489
|
+
|
|
255
490
|
## Short, medium, and long forms
|
|
256
491
|
|
|
257
|
-
Length is a channel constraint, not a persuasion doctrine.
|
|
492
|
+
Length is a channel constraint, not a persuasion doctrine. The three word counts below are governance defaults that mark where the treatment changes; no evidence establishes a length optimum, and an asset that falls between two bands takes whichever treatment its channel needs.
|
|
258
493
|
|
|
259
|
-
### Very short: one line to about 35 words
|
|
494
|
+
### Very short: one line to about 35 words (governance default)
|
|
260
495
|
|
|
261
496
|
Use a compelling market shift, felt stake, live consequence, or verified trigger condition plus the strongest verified mechanism or differentiator. When no outcome evidence exists, use the exact condition the product acts on. Do not retreat to a feature list. Compress the mechanism into the differentiator when syntax permits. Do not force objection handling, a full proof stack, a decision criterion, or visible investor relevance.
|
|
262
497
|
|
|
498
|
+
In a short bounded company description, give each sentence a distinct job. Use category orientation once and mechanism once. Do not add a final sentence that merely restates the actor, classification fields, or routing relation to satisfy the length floor.
|
|
499
|
+
|
|
500
|
+
When a mechanism uses two or more named input fields, name the fields once. Refer to `the pair`, `the combination`, or the resulting assignment afterward instead of repeating every field name.
|
|
501
|
+
|
|
263
502
|
For a hard character limit, count characters exactly. Preserve the strongest fact, not the greatest number of facts.
|
|
264
503
|
|
|
265
|
-
### Medium: about 36 to 120 words
|
|
504
|
+
### Medium: about 36 to 120 words (governance default)
|
|
266
505
|
|
|
267
506
|
Lead with the stake or shift. Add the mechanism and strongest proof clue. Include a material qualifier when its omission would overstate the claim. Land a natural destination belief without announcing the reasoning framework.
|
|
268
507
|
|
|
269
|
-
### Long: more than about 120 words
|
|
508
|
+
### Long: more than about 120 words (governance default)
|
|
270
509
|
|
|
271
510
|
Expand only when each addition resolves a live uncertainty or objection. Long-form buyer and investment work may use situation, consequence, criterion, mechanism, proof, alternatives, timing, and next step. Do not stretch a small fact set into an essay.
|
|
272
511
|
|
|
@@ -276,7 +515,11 @@ Short forms are compressed decisions, not miniature essays. Long forms are not p
|
|
|
276
515
|
|
|
277
516
|
### Landing-page heroes and ads
|
|
278
517
|
|
|
279
|
-
Assume low context and fragile attention. Name one recognizable situation or stake. Show one meaningful difference. Offer one dominant next step unless the surface is explicitly a branching flow.
|
|
518
|
+
Assume low context and fragile attention. Name one recognizable situation or stake. Show one meaningful difference. Offer one dominant next step unless the surface is explicitly a branching flow.
|
|
519
|
+
|
|
520
|
+
State a material fit or exclusion boundary in a complete sentence with its subject and condition. Do not compress it into an orphan fragment merely to keep the first screen short.
|
|
521
|
+
|
|
522
|
+
Give the reader a category they already own before or inside the first differentiating claim, then say what is different about this one. See `Mechanism and differentiation > Orientation against taxonomy`. Do not open with a product taxonomy, a classification tree, or an all-in-one claim.
|
|
280
523
|
|
|
281
524
|
### Product pages
|
|
282
525
|
|
|
@@ -332,9 +575,66 @@ Do not mechanically ban common verbs. Reject them when they are the primary carr
|
|
|
332
575
|
|
|
333
576
|
Use category ambition by naming the scale of consequence, not by making an unsupported rank claim. "An operating layer for distributed battery fleets" expresses scope. "The leading battery platform" requires leadership evidence.
|
|
334
577
|
|
|
578
|
+
Differentiation pressure is the main route by which internal method names reach customer copy. Naming the mechanism precisely is required. Naming it in the organization's own vocabulary is not. Describe what the mechanism does in words the reader already owns, and reserve the internal name for surfaces where the reader has agreed to learn it, such as documentation, a methodology page, or a technical annex.
|
|
579
|
+
|
|
580
|
+
Two separate reader properties decide this, and collapsing them into one is the usual mistake.
|
|
581
|
+
|
|
582
|
+
**Awareness decides how much conceptual context the opening must supply. Sophistication decides how much differentiation and claim resistance the message must overcome.** Name a mechanism early only when the reader already understands enough of the problem and solution space that the name reduces comparison cost instead of creating vocabulary cost.
|
|
583
|
+
|
|
584
|
+
Before that point a coined mechanism is not precision from the reader's side. It is one more object to learn. Unfamiliar jargon measurably reduces processing fluency ([Shulman et al., 2020](https://journals.sagepub.com/doi/10.1177/0261927X20902177)), so plain-language meaning should precede an unfamiliar proper noun whenever the reader lacks the vocabulary. Familiar technical terminology used by a technical evaluator is not functioning as jargon and this rule does not apply to it.
|
|
585
|
+
|
|
586
|
+
Experienced or skeptical audiences need credibility rather than louder claims. Once persuasive motive becomes visible, readers apply what they know about persuasion and discount accordingly ([Campbell and Kirmani, 2000](https://academic.oup.com/jcr/article-abstract/27/1/69/1791556)). In a claim-saturated market, increase verifiability before increasing rhetorical intensity.
|
|
587
|
+
|
|
588
|
+
### Orientation against taxonomy
|
|
589
|
+
|
|
590
|
+
Orientation pressure and differentiation pressure point in opposite directions, and a draft can fail in either direction. The current failure list treats category language as a defect, and that is only half true.
|
|
591
|
+
|
|
592
|
+
A cold reader answers three questions before any differentiation can land: where am I, what is this, and why here. A category noun the reader already owns answers the second in two or three words, and nothing else answers it as cheaply. Company writing has to be legible inside a category and distinct enough to deserve attention at the same time, and neither half substitutes for the other ([Navis and Glynn, legitimate distinctiveness](https://doi.org/10.5465/amr.2008.0361)).
|
|
593
|
+
|
|
594
|
+
So:
|
|
595
|
+
|
|
596
|
+
- **Naming the category orients.** `A payroll system for restaurant groups` is not a taxonomy retreat. It is the cheapest available answer to what this is, and it borrows a structure the reader has already built.
|
|
597
|
+
- **Describing yourself only in category terms leaves you swappable.** The defect is not the category noun. It is stopping at the category noun, so that every other member of the category could publish the same sentence unchanged.
|
|
598
|
+
|
|
599
|
+
The working order on a cold surface is orient, then differentiate, usually inside one sentence. Reach for an existing category the reader owns before inventing one, because a coined category asks the reader to build the structure themselves before they have a reason to.
|
|
600
|
+
|
|
601
|
+
Where this fails:
|
|
602
|
+
|
|
603
|
+
- On a warm surface the orienting is already done, and repeating the category noun spends attention the reader has already given. A second-touch email, a pricing page, or an in-product upgrade screen does not reintroduce the category.
|
|
604
|
+
- Orientation does not license opening with a taxonomy tree, a product-line inventory, or an all-in-one claim. One category noun is orientation; a classification is not.
|
|
605
|
+
- When the supplied facts contain a verified trigger, threshold, conflict, or exception, that condition can carry the opening and the category noun can follow inside the same sentence. Do not retreat to a category sentence merely because quantified impact is missing.
|
|
606
|
+
|
|
607
|
+
Grade: A- for the requirement that writing be legible inside a category and distinct within it, from the source linked above. HOUSE for the instruction to lead a cold commercial surface with a reader-owned category noun; two practitioners in the craft pass assert it independently at Grade C, neither with a published method.
|
|
608
|
+
|
|
609
|
+
### Specificity against superlative
|
|
610
|
+
|
|
611
|
+
Given a supported specific and an unsupported superlative that point at the same fact, ship the specific.
|
|
612
|
+
|
|
613
|
+
A superlative is a rank claim. `Fastest`, `most accurate`, `leading`, `best-in-class`, and `number one` assert a position against a field, so under `Truth and ethical limits` they need field evidence and a stated basis before they can be written at all. The checkable fact usually says more and costs less:
|
|
614
|
+
|
|
615
|
+
Weak, and true:
|
|
616
|
+
|
|
617
|
+
> The quickest turnaround in commercial plan review.
|
|
618
|
+
|
|
619
|
+
Strong:
|
|
620
|
+
|
|
621
|
+
> Plan review comes back in three working days.
|
|
622
|
+
|
|
623
|
+
The second is not stronger because superlatives underperform. It is stronger because it is verifiable, because it survives a reader who already discounts vendor intensity ([Campbell and Kirmani, 2000](https://academic.oup.com/jcr/article-abstract/27/1/69/1791556)), and because it tells the reader something they can act on. The same logic applies to category-generic benefit phrasing: `increase your sales` and `save time` are promises every competitor in the category is also making, so they select nobody.
|
|
624
|
+
|
|
625
|
+
Where this fails:
|
|
626
|
+
|
|
627
|
+
- A specific is only stronger when it is supplied and verified. Never manufacture a number to escape a superlative. Narrow the claim or drop it.
|
|
628
|
+
- A superlative with a stated basis, a date, and a publishable source is a claim like any other and may be used. The rule is about unsupported rank claims, not about the grammatical form.
|
|
629
|
+
- Precision has a cost. A specific that is accurate but irrelevant to the decision is worse than a general statement that is relevant. Rank by decision relevance first, then by specificity.
|
|
630
|
+
|
|
631
|
+
Grade: HOUSE, resting on the truth rules above it. Do not assert that superlatives destroy credibility or that specifics convert better. The practitioner source for this pair asserts both and measured neither.
|
|
632
|
+
|
|
633
|
+
### Differentiation tests
|
|
634
|
+
|
|
335
635
|
Run these tests:
|
|
336
636
|
|
|
337
|
-
- **Competitor-swap:**
|
|
637
|
+
- **Competitor-swap:** paste the line into a search engine and count the unrelated companies publishing it unchanged. Judge it only when the line is too long or too specific to search, and read the procedure and its boundary in `Plain language and first-read comprehension > Required comprehension tests`.
|
|
338
638
|
- **Causal:** does the mechanism actually support the stated outcome?
|
|
339
639
|
- **Continuity:** does each sentence earn the next?
|
|
340
640
|
- **Defense:** would the author defend every claim to a skeptical reader?
|
|
@@ -343,16 +643,96 @@ Run these tests:
|
|
|
343
643
|
|
|
344
644
|
## CTA standard
|
|
345
645
|
|
|
346
|
-
A CTA should complete the argument rather than compensate for a missing one.
|
|
646
|
+
A CTA is an action label, not a slogan. It should complete the argument rather than compensate for a missing one.
|
|
647
|
+
|
|
648
|
+
### The required shape
|
|
649
|
+
|
|
650
|
+
Every CTA tells the reader what will happen after they select it. The working shape is:
|
|
651
|
+
|
|
652
|
+
`clear verb + concrete object, destination, or result`
|
|
653
|
+
|
|
654
|
+
Workable labels name the thing on the other side: `View the report`, `Compare plans`, `Check eligibility`, `See the recommended fixes`, `Review the results`, `Open the study`, `Book a product demo`, `Start the assessment`, `Download the guide`, `Contact the sales team`, `Retry the payment`.
|
|
655
|
+
|
|
656
|
+
When a working destination is supplied but its literal URL is not, return the action label as copy. Do not invent `#`, `example.com`, a route, or a dummy href. Destination fidelity governs the claim; fabricating link syntax does not make a CTA more complete.
|
|
657
|
+
|
|
658
|
+
Return a CTA label as plain copy unless the user requests markup or supplies the destination URL. Do not wrap a label in square brackets without a destination; bracket-only text reads as an unresolved link rather than a ready control.
|
|
659
|
+
|
|
660
|
+
Name the outcome the reader ends up with, not the motion the interface performs. A label that describes what the product will display is weaker than one that describes what the reader will then have. Prefer the artifact or answer over the transition to it.
|
|
661
|
+
|
|
662
|
+
Specificity has a failure at the far end. A label narrowed past the range of reasons a reader might select it turns away the readers it did not name: a contact control labelled `Ask about pricing` excludes the reader holding a security question, and the repair is a broader label, not a longer one. Name the destination precisely enough that nothing has to be inferred, and no more precisely than the destination actually is. This boundary is HOUSE, from a single practitioner teardown at Grade D; no effect on response is claimed.
|
|
663
|
+
|
|
664
|
+
### Slogan-shaped labels
|
|
665
|
+
|
|
666
|
+
Reject labels that carry force and hide the action: `Take control`, `Move with confidence`, `Fix what matters`, `See the difference`, `Unlock your potential`, `Transform your results`, `Start your journey`, `Make it count`, `Get clarity`.
|
|
667
|
+
|
|
668
|
+
The basis for rejecting these is operational ambiguity, not a conversion claim. **No controlled evidence establishes that slogan-shaped labels as a class convert worse than action labels as a class.** Do not assert that they do. What is supported is the underlying clarity requirement: a control should describe its own purpose and destination ([NN/g, Better Link Labels](https://www.nngroup.com/articles/better-link-labels/), [W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html)).
|
|
669
|
+
|
|
670
|
+
The enforceable rule: reject a slogan-shaped primary label when it cannot answer what the reader will have, know, start, change, send, open, or commit to next.
|
|
671
|
+
|
|
672
|
+
Each of these has a narrow condition where it is correct. `Get clarity` works once it names its object, as in `Get clarity on close risks`. `Take control` works as an entry point to a literal control centre when the adjacent copy makes that meaning unmistakable. `Start your journey` works for a named onboarding programme the surrounding copy identifies. The pattern is that the label becomes valid when the destination is supplied, not when the tone is softened.
|
|
673
|
+
|
|
674
|
+
A slogan may sit next to the control as persuasion copy. The restriction applies to the action label's informational job, not to the headline above it.
|
|
347
675
|
|
|
348
|
-
|
|
676
|
+
Also avoid the weaker generic labels for the same reason: `Learn more`, `Get started`, `Submit`, `Explore`, `Discover`, `Click here`, `Request information`, and bare product names. `Next` is correct between explanatory or editable steps, and the final step should name the real action. On a consequential or irreversible dialog, name the operation rather than using `OK` or `Yes`, so the reader does not have to reparse the prompt to know what the button does ([NN/g confirmation dialogs](https://www.nngroup.com/articles/confirmation-dialog/)).
|
|
677
|
+
|
|
678
|
+
Do not encode a pronoun ranking. The widely cited first-person result compared `Start my free trial` against `Start your free trial` on one site with incomplete method reporting, and no independent replication was located. It does not establish that `Start my trial` beats `Start trial`. Treat first-person framing as a testable variable, never a house rule.
|
|
679
|
+
|
|
680
|
+
### Microcopy under the control
|
|
681
|
+
|
|
682
|
+
The line under a button does work the label cannot, because the label has to stay short and the objection does not.
|
|
683
|
+
|
|
684
|
+
Build it from the objections the reader is holding at that exact moment, not from a template. Enumerate them first, in the reader's own words: how long is this going to take, do I need something I do not have, what happens to what I enter, am I committing to anything, is this meant for someone like me. Then answer only the ones this destination actually raises.
|
|
685
|
+
|
|
686
|
+
Four questions cover most controls, and the microcopy answers whichever of them the reader cannot already answer:
|
|
687
|
+
|
|
688
|
+
1. What is the goal of this step?
|
|
689
|
+
2. How does it work?
|
|
690
|
+
3. What do I walk away with?
|
|
691
|
+
4. Who is this for?
|
|
692
|
+
|
|
693
|
+
Where the commitment is genuinely ambiguous, say what it is not: `no card required`, `you can change this later`, `this sends a request and does not book the slot`. Every reassurance is a claim and inherits the truth rules. Write none the supplied facts do not support, and never soften a real commitment with a line implying reversibility the product does not offer.
|
|
694
|
+
|
|
695
|
+
Where this fails:
|
|
696
|
+
|
|
697
|
+
- Microcopy is not a place to relocate a claim the body copy could not support.
|
|
698
|
+
- Reassurance under a low-friction control adds friction by implying the action was risky. Use it where commitment, cost, data handling, or duration is genuinely in question, and nowhere else.
|
|
699
|
+
- Answering all four questions under every control produces a page of hedges. One or two lines, at the point of decision.
|
|
700
|
+
|
|
701
|
+
Grade: HOUSE procedure, from a practitioner teardown at Grade C with no method reported. The underlying requirement that a control describes its own purpose and consequence is the same clarity evidence cited above ([NN/g, Better Link Labels](https://www.nngroup.com/articles/better-link-labels/), [W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html)).
|
|
702
|
+
|
|
703
|
+
### What the reader must never have to infer
|
|
704
|
+
|
|
705
|
+
- what opens;
|
|
706
|
+
- what they receive;
|
|
707
|
+
- what they must provide;
|
|
708
|
+
- whether the action is immediate;
|
|
709
|
+
- whether the action starts a purchase, form, demo, download, or review;
|
|
710
|
+
- what commitment the action creates.
|
|
711
|
+
|
|
712
|
+
If the destination is a form, the label should imply a form. If the destination is a document, the label should name the document. If the action begins a paid commitment, the label should not read like a preview.
|
|
713
|
+
|
|
714
|
+
When the brief names a destination artifact, surface, or state such as a sample dashboard, report, study, form, or preview, preserve that name in the CTA or adjacent microcopy. Do not replace the named destination with only the contents it displays. `View captured changes` leaves out a supplied sample-dashboard state; `View the sample dashboard` tells the reader what opens. This is destination fidelity, not a preferred phrase.
|
|
715
|
+
|
|
716
|
+
Match the route as well as the destination. When the supplied action begins with a form, upload, comparison, trial, reply, sample request, or physical delivery, do not substitute another available path. Two routes can lead to the same organization while asking different things from the reader.
|
|
717
|
+
|
|
718
|
+
### Match commitment to readiness and to destination
|
|
349
719
|
|
|
350
720
|
- Early attention: learn, compare, see, review, or save.
|
|
351
|
-
- Active evaluation: inspect
|
|
721
|
+
- Active evaluation: review results, inspect the source material, try a workflow, calculate fit, or ask a focused question.
|
|
352
722
|
- Ready action: start, buy, subscribe, book, submit, or upgrade.
|
|
353
723
|
- Utility: continue, return, restore, confirm, cancel, or retry.
|
|
354
724
|
|
|
355
|
-
|
|
725
|
+
Do not use a high-commitment CTA when the copy only supports a low-commitment test. Do not use a dramatic label when the destination is informational. Do not add urgency without a real clock or constraint.
|
|
726
|
+
|
|
727
|
+
### Consistency across a surface
|
|
728
|
+
|
|
729
|
+
One materially identical action gets one canonical label. Links to the same destination should carry the same description, and components with the same functionality should be identified consistently ([W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html), [NN/g, Consistency and Standards](https://www.nngroup.com/articles/consistency-and-standards/)).
|
|
730
|
+
|
|
731
|
+
The rule is strongest on controls that perform the same action. It is weaker on destination links, where context can legitimately change the wording: `Pricing` in global navigation and `Compare plans` in a hero can point at the same page without confusing anyone, because one is a destination label and the other is a task invitation.
|
|
732
|
+
|
|
733
|
+
Repeating one goal down a long page creates several access points to one offer, not several offers. That is permitted for convenience. No published evidence establishes an optimal repetition interval, so do not claim a lift from repetition and do not enforce a spacing rule.
|
|
734
|
+
|
|
735
|
+
Where a page genuinely branches, the labels should differ in destination, not merely in phrasing.
|
|
356
736
|
|
|
357
737
|
## Spoken delivery
|
|
358
738
|
|
|
@@ -368,6 +748,12 @@ Spoken copy is heard once in sequence. Optimize for breath, rhythm, memory, and
|
|
|
368
748
|
- Omit implementation-status facts such as route availability unless the listener is asked to act on that route.
|
|
369
749
|
- End on one supported consequence, decision, or form of agency rather than a product-status sentence or a stack of adjacent action verbs.
|
|
370
750
|
|
|
751
|
+
Do not restate the opening situation in the close. Once the mechanism and evidence have answered the opening, use the final line for the supported inspection, decision, or next action.
|
|
752
|
+
|
|
753
|
+
Do not invent what the listener currently does, remembers, believes, or struggles with to create a closing beat. Agency must come from the supplied action or evidence.
|
|
754
|
+
|
|
755
|
+
If the spoken brief supplies no action or CTA, do not manufacture an imperative close. End after the supported mechanism, evidence, or consequence instead of stacking viewing commands.
|
|
756
|
+
|
|
371
757
|
For hybrid work, write the script for listening. Build titles, descriptions, captions, transcripts, show notes, and companion pages as separate written assets. Rank facts separately for each asset. Do not force every supplied fact into both. Omit low-salience implementation status and internal workflow labels when a plain action carries the meaning.
|
|
372
758
|
|
|
373
759
|
Treat an existence-only route, screen, page, preview, or report as action availability when the brief supplies no differentiated function for it. Express that availability through the CTA or final invitation. Do not turn it into a body-copy claim.
|
|
@@ -378,9 +764,12 @@ Apply this gate after the argument and proof pass. Its purpose is specific, accu
|
|
|
378
764
|
|
|
379
765
|
### Global output bans
|
|
380
766
|
|
|
381
|
-
|
|
767
|
+
Hard invariant: emit zero U+2014 characters in the entire response. This applies to copy, headings, lists, critique, explanations, notes, metadata, quotations, and text copied from user or source material. Do not repeat U+2014 from an input. Replace it with a period, comma, colon, semicolon, parentheses, or plain hyphen as grammar requires.
|
|
768
|
+
|
|
769
|
+
If an exact quotation contains U+2014, paraphrase it or state that it cannot be reproduced verbatim under the active constraint. Never alter a quotation and still present it as exact. After all drafting and editing, scan the complete response character by character for U+2014, replace every occurrence, and scan again. Return only when the count is zero.
|
|
770
|
+
|
|
771
|
+
Unless immutable quoted, legal, technical, or user-required text must be preserved, also generate:
|
|
382
772
|
|
|
383
|
-
- no em dashes;
|
|
384
773
|
- no curly or smart quotation marks;
|
|
385
774
|
- no prompt acknowledgements or task meta-commentary;
|
|
386
775
|
- no fabricated citations, quotations, anecdotes, memories, motives, credentials, or human texture;
|
|
@@ -388,7 +777,7 @@ Unless immutable quoted, legal, technical, or user-required text must be preserv
|
|
|
388
777
|
- no unneeded conclusion or recap;
|
|
389
778
|
- no deliberate errors, fake informality, or detector-evasion promises.
|
|
390
779
|
|
|
391
|
-
Use straight quotes.
|
|
780
|
+
Use straight quotes. Never change facts, names, figures, dates, citations, causality, uncertainty, legal meaning, or required technical terminology to satisfy a style preference. The U+2014 ban is not optional; resolve any conflict without misrepresenting altered source text as verbatim.
|
|
392
781
|
|
|
393
782
|
### AI-heavy vocabulary
|
|
394
783
|
|
|
@@ -427,6 +816,8 @@ Delete generic tails such as `underscoring the importance of`, `highlighting its
|
|
|
427
816
|
|
|
428
817
|
Remove repeated `bold label: sentence` bullets, headings that restate themselves, identical paragraph shapes, conclusion sections that add nothing, balanced both-sides framing without named evidence, and smooth transitions that hide unrelated facts.
|
|
429
818
|
|
|
819
|
+
Extend this to the whole deliverable, not one passage. Headings that share a syntactic template across a page, and calls to action that share a template across a site, are the same defect at a larger scale. A set of headings built as a count followed by a singular abstract noun, or every heading opening with the same conditional clause, is a structural tell even when each heading is accurate and each was written to a sanctioned shape. Sanctioned shapes are the most likely source of this failure, because nothing flags them individually.
|
|
820
|
+
|
|
430
821
|
Avoid decorative tripartite rhetoric used as a stock flourish. Do not ban factual three-item series. Preserve necessary enumerations when they state scope, compare options, qualify a claim, meet a legal or platform requirement, or prevent misleading omission.
|
|
431
822
|
|
|
432
823
|
Never add fake typos, fragments, slang, personal memories, jokes, or emotional confessions to simulate humanity. If author samples are supplied, follow stable habits without copying phrases or inventing an identity.
|
|
@@ -441,16 +832,20 @@ Research on detector limits includes the [RAID benchmark](https://arxiv.org/abs/
|
|
|
441
832
|
|
|
442
833
|
Apply these rules only to written assets. They improve clarity, extractability, and verification. They do not guarantee retrieval or citation.
|
|
443
834
|
|
|
835
|
+
These rules sit at level 7 of the conflict hierarchy. None of them may raise decoding effort. Where one of them would, comprehension wins.
|
|
836
|
+
|
|
444
837
|
- Answer the central question early when the format calls for it.
|
|
445
838
|
- Name the subject, entity, category, scope, and time frame clearly.
|
|
446
|
-
- Keep proof and qualifications
|
|
447
|
-
- Write self-contained passages that remain accurate when quoted alone.
|
|
839
|
+
- Keep proof and qualifications near the claims they govern, in their own sentences. Near does not mean inside.
|
|
840
|
+
- Write self-contained passages that remain accurate when quoted alone. The unit is the passage, not the individual sentence, and no sentence count defines it: passage size is task-dependent and is settled by the semantic test in `Required comprehension tests`. Do not load one clause with the context of its neighbours in order to make it quotable on its own. A passage that has to be read as a unit is correct; a sentence that has to be decoded as a specification is not.
|
|
448
841
|
- Expose genuine provenance, sources, authorship, dates, and methods.
|
|
449
842
|
- Add information value rather than paraphrasing a common consensus.
|
|
450
843
|
- Use descriptive headings and labels that match the content beneath them.
|
|
451
844
|
- Keep visible and machine-readable facts consistent.
|
|
452
845
|
- Preserve necessary enumerations when they define a product, comparison, or scope.
|
|
453
846
|
|
|
847
|
+
Treat search, retrieval, and citation quality as properties of the page and coherent passages. A hero may optimize for human attention while the following sections carry explicit definitions, proof, scope, sources, and quotable answers. Do not force article-style self-containment into every first-screen sentence.
|
|
848
|
+
|
|
454
849
|
Do not stuff keywords, write miniature conclusions under every heading, fragment prose for imagined answer engines, or add unsupported statistics for apparent authority.
|
|
455
850
|
|
|
456
851
|
## Technical publication boundaries
|
|
@@ -527,9 +922,9 @@ Strong:
|
|
|
527
922
|
>
|
|
528
923
|
> LedgerFlow reconciles purchase orders, invoices, and receipts, then routes the exceptions that need a finance decision.
|
|
529
924
|
>
|
|
530
|
-
> See
|
|
925
|
+
> See how a mismatch gets resolved
|
|
531
926
|
|
|
532
|
-
Why: the hero names a credible stake and mechanism without inventing a result. The factual three-item list is necessary scope.
|
|
927
|
+
Why: the hero names a credible stake and mechanism without inventing a result. The factual three-item list is necessary scope. The label names what the reader will know afterwards rather than the screen they will be moved to, which is the difference between an outcome label and a transition label.
|
|
533
928
|
|
|
534
929
|
### Paywall
|
|
535
930
|
|
|
@@ -605,6 +1000,208 @@ Strong:
|
|
|
605
1000
|
|
|
606
1001
|
Why: the factual series defines scope and prevents a misleading generalization. Deleting it to avoid a three-item pattern would make the copy worse.
|
|
607
1002
|
|
|
1003
|
+
### Insider terminology
|
|
1004
|
+
|
|
1005
|
+
Verified facts:
|
|
1006
|
+
|
|
1007
|
+
> A veterinary practice platform assigns each incoming client message to the staff member qualified to answer it. The company calls this step "care-path routing" internally. Clients of the platform are practice owners and office managers. No response-time or satisfaction result is available.
|
|
1008
|
+
|
|
1009
|
+
Weak:
|
|
1010
|
+
|
|
1011
|
+
> Care-path routing assigns inbound client communications to the appropriate qualified responder.
|
|
1012
|
+
|
|
1013
|
+
Strong:
|
|
1014
|
+
|
|
1015
|
+
> When a client messages the practice, the message goes to the person qualified to answer it, not to a shared inbox.
|
|
1016
|
+
|
|
1017
|
+
Why: the internal name teaches the reader nothing and costs them a decode. The strong version names the situation the practice owner recognizes and the change that follows. The mechanism survives; only the label is gone.
|
|
1018
|
+
|
|
1019
|
+
Boundary: this is a rule about coined nouns, not about technical vocabulary. `Triage`, `controlled drug register`, and `practice management system` are terms a practice owner already shops for, and removing them would cost precision and buy nothing. The test is whether the reader owns the word before arriving, not whether the word is difficult.
|
|
1020
|
+
|
|
1021
|
+
### Abstraction stacking
|
|
1022
|
+
|
|
1023
|
+
Verified facts:
|
|
1024
|
+
|
|
1025
|
+
> A freight brokerage compares the weight recorded at pickup with the weight recorded at delivery, and holds any shipment where the two differ by more than two percent for a human check. Customers are shippers and logistics managers.
|
|
1026
|
+
|
|
1027
|
+
Weak:
|
|
1028
|
+
|
|
1029
|
+
> Our exception governance layer enables continuous alignment between origin and destination measurement events across the fulfilment lifecycle.
|
|
1030
|
+
|
|
1031
|
+
Strong:
|
|
1032
|
+
|
|
1033
|
+
> We weigh the shipment at pickup and again at delivery. If the two differ by more than two percent, a person checks it before it moves on.
|
|
1034
|
+
|
|
1035
|
+
Why: the weak version is accurate and undecodable at reading speed. Nobody acts in it, nothing happens at a moment, and the threshold that decides everything has disappeared into `alignment`. The strong version names who acts, on what, and what triggers the check. The defect is not the number of abstract nouns, which is not a measure of anything; it is that no actor, action, or result can be recovered from them.
|
|
1036
|
+
|
|
1037
|
+
### Methodology in customer copy
|
|
1038
|
+
|
|
1039
|
+
Verified facts:
|
|
1040
|
+
|
|
1041
|
+
> A clinical billing service reviews every claim twice: once by software before submission and once by a certified coder when the software flags a mismatch. It publishes a methodology page describing both stages. The audience for the marketing page is practice administrators.
|
|
1042
|
+
|
|
1043
|
+
Weak:
|
|
1044
|
+
|
|
1045
|
+
> Stage one applies automated pre-submission validation. Stage two introduces certified human adjudication for flagged variances, preserving the separation between automated and manual review records.
|
|
1046
|
+
|
|
1047
|
+
Strong:
|
|
1048
|
+
|
|
1049
|
+
> Every claim is checked by software before it goes out. If something does not match, a certified coder looks at it before submission, not after the denial.
|
|
1050
|
+
|
|
1051
|
+
Why: the weak version describes the company's process architecture to an audience that only needs to know what happens to their claims. Stage numbers, record separation, and adjudication are internal concerns. The strong version keeps both checks, the ordering, and the credential, and drops the method's self-description.
|
|
1052
|
+
|
|
1053
|
+
Boundary: the same facts written for a different reader can keep the architecture. A procurement reviewer comparing three billing services, or a compliance officer checking separation of duties, is asking about the process itself, and the methodology page exists for exactly that reader. Awareness decides how much of this the opening has to supply; sophistication decides how much of it the comparison demands. Do not strip the method from a surface whose reader came to inspect it.
|
|
1054
|
+
|
|
1055
|
+
### Slogan-shaped CTA
|
|
1056
|
+
|
|
1057
|
+
Verified facts:
|
|
1058
|
+
|
|
1059
|
+
> A home energy app can produce a report showing which appliances used the most electricity last month. The report is free and takes about a minute to generate. No savings figure is available.
|
|
1060
|
+
|
|
1061
|
+
Weak:
|
|
1062
|
+
|
|
1063
|
+
> Take control of your energy.
|
|
1064
|
+
>
|
|
1065
|
+
> Get started
|
|
1066
|
+
|
|
1067
|
+
Strong:
|
|
1068
|
+
|
|
1069
|
+
> See which appliances used the most power last month.
|
|
1070
|
+
>
|
|
1071
|
+
> Generate my usage report
|
|
1072
|
+
|
|
1073
|
+
Why: neither weak line tells the reader what they get or what happens next. The strong headline names the answer the report contains, and the label names the artifact the reader receives. Neither invents a saving.
|
|
1074
|
+
|
|
1075
|
+
The basis for rejecting the weak version is operational ambiguity, not a conversion claim. `Take control of your energy` is not banned as a sentence; it is banned as the only thing on the button. It could sit above the control as persuasion copy with `Generate my usage report` underneath it, and then both jobs are done by the element suited to each.
|
|
1076
|
+
|
|
1077
|
+
### CTA destination clarity
|
|
1078
|
+
|
|
1079
|
+
Verified facts:
|
|
1080
|
+
|
|
1081
|
+
> A business lender lets a prospective borrower enter revenue, time trading, and industry to see whether they meet the published lending criteria. The check takes two minutes, requires no documents, and does not affect a credit score. It is not an application.
|
|
1082
|
+
|
|
1083
|
+
Weak:
|
|
1084
|
+
|
|
1085
|
+
> Move forward with confidence.
|
|
1086
|
+
>
|
|
1087
|
+
> Apply now
|
|
1088
|
+
|
|
1089
|
+
Strong:
|
|
1090
|
+
|
|
1091
|
+
> Find out whether you meet the lending criteria before you apply.
|
|
1092
|
+
>
|
|
1093
|
+
> Check eligibility
|
|
1094
|
+
>
|
|
1095
|
+
> Two minutes, no documents. This is not an application and it does not affect your credit score.
|
|
1096
|
+
|
|
1097
|
+
Why: the weak label promises an application the reader is not ready to make and hides the low commitment that would have earned the click. The strong version names the destination in the label and puts the time cost, the requirement, and the reversibility in the line underneath, which is where they belong. Loading all of that into the label itself makes the control unreadable and still leaves the reassurance in the wrong place. Every one of those reassurances is a supplied fact; none of them would be writable otherwise.
|
|
1098
|
+
|
|
1099
|
+
### Overloaded qualification
|
|
1100
|
+
|
|
1101
|
+
Verified facts:
|
|
1102
|
+
|
|
1103
|
+
> A workplace safety monitor records equipment temperature every thirty seconds and alerts a supervisor when a reading passes the threshold configured for that machine. Readings come only from sensors the customer has installed and enabled. The monitor cannot report on machines without a sensor.
|
|
1104
|
+
|
|
1105
|
+
Weak:
|
|
1106
|
+
|
|
1107
|
+
> The monitor records temperature observations at thirty-second intervals for configured, customer-enabled sensor endpoints and issues supervisor notifications when a recorded value exceeds the per-asset threshold in effect at the time of observation, subject to sensor availability.
|
|
1108
|
+
|
|
1109
|
+
Strong:
|
|
1110
|
+
|
|
1111
|
+
> The monitor reads each machine's temperature every thirty seconds. When a reading passes the limit you set for that machine, the supervisor gets an alert.
|
|
1112
|
+
>
|
|
1113
|
+
> This only covers machines where you have installed and switched on a sensor.
|
|
1114
|
+
|
|
1115
|
+
Why: every qualifier in the weak version is material and none of it is deleted. It moves to its own sentence, which is where qualification belongs. The claim is now readable at speed and the limit is now more visible, not less.
|
|
1116
|
+
|
|
1117
|
+
Boundary: this works because the limit can stand as its own sentence next to the claim. Where a qualifier changes the meaning of the specific words it sits beside, it stays inline. `Reported by Friday for samples that arrive before noon on Tuesday` cannot be split without making the first half false.
|
|
1118
|
+
|
|
1119
|
+
### Category orientation
|
|
1120
|
+
|
|
1121
|
+
Verified facts:
|
|
1122
|
+
|
|
1123
|
+
> Northbeam Machine Co. repairs, rebuilds, and resells commercial espresso machines across one metropolitan region. When a repair will keep a machine in the workshop for more than a day, Northbeam lends the customer a working machine. Customers are cafe and restaurant owners. No downtime, revenue, or satisfaction figure is available.
|
|
1124
|
+
|
|
1125
|
+
Weak:
|
|
1126
|
+
|
|
1127
|
+
> Northbeam Machine Co. is a lifecycle asset partner for hospitality beverage equipment, covering acquisition, maintenance, refurbishment, and resale.
|
|
1128
|
+
|
|
1129
|
+
Strong:
|
|
1130
|
+
|
|
1131
|
+
> Northbeam repairs commercial espresso machines. If yours needs more than a day in the workshop, we lend you one that works until it comes back.
|
|
1132
|
+
|
|
1133
|
+
Why: nothing in the weak version is untrue, and it fails anyway. `Lifecycle asset partner` is a category the reader has to construct before they can tell whether this company touches their problem, and `hospitality beverage equipment` makes them translate their own espresso machine into a class they do not use the word for. The strong version names a category the reader already owns in three words, then immediately says the thing no other repair shop on the street is saying.
|
|
1134
|
+
|
|
1135
|
+
The lesson is not that category language is a defect. Both versions name a category. The weak one names a coined class and stops there; the strong one names a class the reader already carries and then differentiates. On a warm surface, a second-touch email or a returning customer's account page, the orientation is already done and the category noun can go.
|
|
1136
|
+
|
|
1137
|
+
### Superlative against specific
|
|
1138
|
+
|
|
1139
|
+
Verified facts:
|
|
1140
|
+
|
|
1141
|
+
> Fieldmark Labs tests farm soil samples for nitrogen, phosphorus, potassium, and pH. Samples arriving before noon on Tuesday are reported by Friday of the same week. The two other laboratories serving the region publish turnaround times of ten and fourteen days, and those published times were checked this season. Customers are arable farmers and agronomists.
|
|
1142
|
+
|
|
1143
|
+
Weak:
|
|
1144
|
+
|
|
1145
|
+
> The fastest soil results in the region.
|
|
1146
|
+
|
|
1147
|
+
Strong:
|
|
1148
|
+
|
|
1149
|
+
> Post a sample on Tuesday morning and the nitrogen, phosphorus, potassium, and pH numbers come back on Friday. The next fastest laboratory in the region publishes a ten-day turnaround.
|
|
1150
|
+
|
|
1151
|
+
Why: the weak line is true, supported, and publishable. It fails for the reader, not for the truth rules. A superlative asks to be believed at the moment the reader is discounting vendor claims hardest, it is the sentence every laboratory in the category writes, and it hides the only thing the farmer actually needs, which is whether the result arrives before the window for spreading closes. The strong version publishes the fact the superlative was compressing, so the reader checks instead of trusting.
|
|
1152
|
+
|
|
1153
|
+
Boundary: the comparison sentence is only writable because the competitors' published turnarounds are supplied and dated. Without that, the second sentence goes and the first one stands alone. And a specific has to be the relevant specific: the accreditation number is also checkable and does not answer the question the farmer arrived with.
|
|
1154
|
+
|
|
1155
|
+
### CTA that overstates the click
|
|
1156
|
+
|
|
1157
|
+
Verified facts:
|
|
1158
|
+
|
|
1159
|
+
> Riverside Adult Education runs an evening welding course with limited places. A visitor submits a form giving their name, email, and previous experience. Every submission goes to the course tutor, who confirms or declines within three working days. Submitting the form does not reserve a place. The body copy on the page states this correctly.
|
|
1160
|
+
|
|
1161
|
+
Weak:
|
|
1162
|
+
|
|
1163
|
+
> Join the class
|
|
1164
|
+
|
|
1165
|
+
Strong:
|
|
1166
|
+
|
|
1167
|
+
> Request a place
|
|
1168
|
+
>
|
|
1169
|
+
> The tutor replies within three working days. You will need to say what welding you have done before.
|
|
1170
|
+
|
|
1171
|
+
Why: nothing on the weak page is false. The body copy says places are confirmed by the tutor, and a reader who reads the whole page is correctly informed. The label still fails, because readers act on the label and not on the paragraph, and `Join the class` describes an outcome the click does not produce. The reader who clicks it believes they are enrolled, and finds out otherwise three days later.
|
|
1172
|
+
|
|
1173
|
+
This is the reader-side half of truth discipline. The copy did not lie; it created a belief the product does not deliver, which is the same damage arriving by a different route. The strong label names what the click actually does, and the line underneath spends two facts to remove the two objections a reader holds at that moment.
|
|
1174
|
+
|
|
1175
|
+
Boundary: do not hedge a control that needs no hedging. `Request a place` is right here because approval is real. On a form that does reserve the place immediately, `Request` understates the click and costs the reader the confidence they had earned.
|
|
1176
|
+
|
|
1177
|
+
### Heading variety across one page
|
|
1178
|
+
|
|
1179
|
+
Verified facts:
|
|
1180
|
+
|
|
1181
|
+
> Kestrel Frames builds modular greenhouse frames for market gardens. Frames arrive flat-packed on a single pallet. Two people assemble a standard bay in about four hours. The frames are rated to 90 mph winds. Individual struts can be ordered on their own. The structural guarantee runs ten years. One page carries all five sections.
|
|
1182
|
+
|
|
1183
|
+
Weak:
|
|
1184
|
+
|
|
1185
|
+
> When the delivery arrives, the frame is flat-packed onto one pallet.
|
|
1186
|
+
> When two people build a standard bay, it takes about four hours.
|
|
1187
|
+
> When the wind reaches 90 mph, the frame is rated to hold.
|
|
1188
|
+
> When a single strut bends, you order that strut on its own.
|
|
1189
|
+
> When ten years have passed, the structural guarantee still applies.
|
|
1190
|
+
|
|
1191
|
+
Strong:
|
|
1192
|
+
|
|
1193
|
+
> Flat-packed onto one pallet
|
|
1194
|
+
> Two people can raise a bay in about four hours
|
|
1195
|
+
> If a strut bends, order that strut
|
|
1196
|
+
> Rated to 90 mph
|
|
1197
|
+
> The guarantee covers the structure for ten years
|
|
1198
|
+
|
|
1199
|
+
Why: every weak heading is accurate, and each one on its own is a shape this document sanctions for a short asset with no outcome evidence. Run through five sections it becomes a machine signature: the reader stops reading the headings and starts recognizing the template, which is the opposite of what a heading is for. Sanctioned shapes are the most likely source of this failure precisely because nothing flags them one at a time.
|
|
1200
|
+
|
|
1201
|
+
The strong set carries the same five facts in three syntactic families, with no family used twice in a row. Judge this by the tell rather than by a count: the twelve-heading concentration default in `Corpus-level variance` is a governance default written for a rolling window, and it does not scale down to a set of five. The question to answer here is whether a reader can tell the sections apart at a glance.
|
|
1202
|
+
|
|
1203
|
+
Boundary: this applies to attention-oriented headings that compete with each other. If these five were steps in an assembly procedure, the parallel template would be correct and forcing variety into them would damage the page.
|
|
1204
|
+
|
|
608
1205
|
## Evaluation contract
|
|
609
1206
|
|
|
610
1207
|
Separate hard invariants from subjective quality.
|
|
@@ -624,9 +1221,22 @@ Test only what must not fail:
|
|
|
624
1221
|
- Spoken-only copy contains no GEO/AEO scaffolding.
|
|
625
1222
|
- Ready-to-use copy appears before any necessary note.
|
|
626
1223
|
- No project-specific facts or controls leak from another context.
|
|
1224
|
+
- The entire generated response contains zero U+2014 characters.
|
|
1225
|
+
- No internal method, stage, score, record-type, tier, or framework name appears in customer-facing copy unless the supplied brief states that the audience already uses it.
|
|
1226
|
+
- Every call to action names a verb plus a concrete object, destination, or result.
|
|
1227
|
+
- No call to action is drawn from the slogan-shaped list in `CTA standard`.
|
|
1228
|
+
- One action carries one label across a single deliverable.
|
|
1229
|
+
- Material qualifiers survive, and they appear in their own sentences rather than inside the claim sentence.
|
|
1230
|
+
- Headings that belong to one task or information class use parallel syntax; attention-oriented headings do not run more than two consecutive instances of one template family. That run length is a governance default, not a measured threshold.
|
|
1231
|
+
- `SCIENCE`, `CASE_STUDY`, and `VOICE` compose without replacing the selected primary mode.
|
|
1232
|
+
- A hero's promise agrees with its destination and surrounding composition.
|
|
1233
|
+
- Scientific claim class, causality, statistical meaning, and uncertainty survive simplification.
|
|
1234
|
+
- Case-study result class, permission, role attribution, causality, quote status, and typicality survive persuasion.
|
|
627
1235
|
|
|
628
1236
|
Do not use deterministic tests for a mandatory visible spine, exact investor phrases, rhetorical triads, visible conflict notes, or subjective persuasion quality.
|
|
629
1237
|
|
|
1238
|
+
First-read comprehension cannot be tested deterministically. Treat it as a blind-quality dimension, scored by a reader who has not seen the source facts.
|
|
1239
|
+
|
|
630
1240
|
### Blind quality evaluation
|
|
631
1241
|
|
|
632
1242
|
Generate in fresh contexts. Pass only the case prompt to the writer. Never pass expected outputs, case metadata, rubrics, diagnoses, or incumbent labels.
|
|
@@ -643,8 +1253,13 @@ Use these quality dimensions on a five-point scale:
|
|
|
643
1253
|
| Mechanism differentiation | The subject is difficult to swap with a competitor |
|
|
644
1254
|
| Natural channel fit | The output sounds native to the requested surface |
|
|
645
1255
|
| Truth discipline | Persuasive force reaches the evidence boundary without crossing it |
|
|
1256
|
+
| First-read comprehension | An intended reader who has not seen the source facts extracts the meaning on one pass |
|
|
1257
|
+
| Concrete action clarity | Actor, action, object, and result are visible, and the call to action names its destination |
|
|
1258
|
+
| Attention value | A short attention surface creates a supported reason to continue rather than summarizing the product |
|
|
1259
|
+
| Composition fit | Headline, subhead, CTA, visual context, proof, and adjacent qualification perform one compatible argument |
|
|
1260
|
+
| Evidence calibration | Scientific and case-study claims preserve result class, causality, uncertainty, attribution, and source scope |
|
|
646
1261
|
|
|
647
|
-
Automatic failure: fabricated fact, unsupported causality, context leakage, visible compliance leakage, or a material omission that makes the result misleading.
|
|
1262
|
+
Automatic failure: any U+2014 occurrence, fabricated real-world fact outside an explicit creative-fiction brief, fiction presented as real evidence, unsupported causality or guarantee, claim-destination mismatch, invented misconception, statistical distortion, false consensus, quote distortion, permission or confidentiality breach, atypical result presented as typical, context leakage, visible compliance leakage, or a material omission that makes the result misleading.
|
|
648
1263
|
|
|
649
1264
|
## Evidence register
|
|
650
1265
|
|
|
@@ -699,9 +1314,80 @@ Evidence grades:
|
|
|
699
1314
|
| B | [LinkedIn sponsored messaging guidance](https://business.linkedin.com/advertise/ads/sponsored-messaging/tips) | CTA count depends on whether the surface is focused or branching. |
|
|
700
1315
|
| C | [Gong cold-email analysis](https://www.gong.io/blog/how-to-write-a-sales-email) | Use outreach benchmarks as testable priors, not universal laws. |
|
|
701
1316
|
|
|
1317
|
+
### Plain language, terminology, and CTA evidence
|
|
1318
|
+
|
|
1319
|
+
The comprehension and CTA rules were tested against the research literature after they were drafted. Seven load-bearing claims were adjudicated. Four did not survive and have been removed from the rules rather than softened.
|
|
1320
|
+
|
|
1321
|
+
| Claim as originally written | Verdict | Grade | What replaced it |
|
|
1322
|
+
|---|---|---|---|
|
|
1323
|
+
| At most one unfamiliar concept per sentence | Refuted as a measured limit | D | A disposal rule: every reader-unowned term is taught in place or removed. Vocabulary coverage impairs comprehension continuously, not as a per-sentence step function ([Kremmel et al., 2023](https://doi.org/10.1111/lang.12622)) |
|
|
1324
|
+
| Two abstract nouns in a clause is one too many, three is a rewrite | Refuted; the numbers are invented | D | Rewrite an abstraction only when it conceals an actor, action, causal relation, or consequence the reader needs. Controlled eye-tracking found no independent comprehension penalty for nominalization ([Balling, 2018](https://doi.org/10.1177/0047281617696983)) |
|
|
1325
|
+
| A self-contained passage is two or three sentences | Refuted; no optimum exists | D | A semantic self-containment test. Passage size is task-dependent |
|
|
1326
|
+
| No two headings in one deliverable share a syntactic template | Refuted as a universal rule, and harmful where applied to task headings | D | Split by function: parallel syntax is correct for same-class headings; template concentration is managed for attention-oriented ones under a stated governance default |
|
|
1327
|
+
| A fixed preferred-verb list improves comprehension | Not supported as a standard | D for the list, A for the principle | Choose the highest-frequency reader-owned verb that preserves the factual relation. Word frequency reliably predicts processing ease; this particular list is a house lexicon |
|
|
1328
|
+
| Slogan-shaped CTA labels fail readers | Rejection stands, basis corrected | D for any conversion claim, C for the clarity requirement | Reject on operational ambiguity, supported by link-purpose and label guidance. No controlled evidence shows slogans convert worse as a class |
|
|
1329
|
+
| Buyer sophistication decides whether a mechanism name helps | Partly right, conflated two axes | D for the original sentence, B for the jargon evidence beneath it | Awareness decides conceptual context; sophistication decides differentiation and claim resistance. Jargon reduces processing fluency ([Shulman et al., 2020](https://journals.sagepub.com/doi/10.1177/0261927X20902177)) |
|
|
1330
|
+
|
|
1331
|
+
What survived with real support: jargon measurably reduces processing fluency; naming an actor changes how readers assign cause ([Fausey and Boroditsky, 2010](https://doi.org/10.3758/PBR.17.5.644)); word frequency predicts processing ease; controls should describe their own destination; one canonical label per materially identical action ([W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html), [NN/g, Consistency and Standards](https://www.nngroup.com/articles/consistency-and-standards/)); persuasion knowledge makes visible motive costly ([Campbell and Kirmani, 2000](https://academic.oup.com/jcr/article-abstract/27/1/69/1791556)); reading aloud improves error detection.
|
|
1332
|
+
|
|
1333
|
+
Two findings in this section are house observations from a diagnosed production failure rather than literature: a sentence carrying its full qualification set inline reads as a compliance memo, and a set of marketing headings built on one template reads as generated. Both were observed directly. Neither has a measured effect size.
|
|
1334
|
+
|
|
1335
|
+
Remaining governance defaults, explicitly not findings: the twelve-headline template-concentration window, and the review trigger for a sentence carrying two or more reader-unowned terms.
|
|
1336
|
+
|
|
1337
|
+
Do not promote any governance default into a graded rule without recording the source, design, population, and limits required by `Evidence maintenance`.
|
|
1338
|
+
|
|
1339
|
+
### Practitioner craft pass
|
|
1340
|
+
|
|
1341
|
+
A separate mining pass over published practitioner talks supplied procedures and exemplars rather than evidence. Nothing from that pass is graded above C and most of it is D, because the medium reports assertions without method. The ceiling is a property of the source, not a judgment about the practitioners, several of whom publish better-supported material elsewhere.
|
|
1342
|
+
|
|
1343
|
+
What was adopted from it, and on what basis:
|
|
1344
|
+
|
|
1345
|
+
| Item | Status here | Basis |
|
|
1346
|
+
|---|---|---|
|
|
1347
|
+
| A reader-owned category noun orients a cold reader | Rule, in `Mechanism and differentiation > Orientation against taxonomy` | A- for the legibility-and-distinctiveness requirement ([Navis and Glynn](https://doi.org/10.5465/amr.2008.0361)); HOUSE for the instruction to lead with the category noun |
|
|
1348
|
+
| Paste the line into a search engine | Procedure, replacing the judgment form of the competitor-swap test | HOUSE. The maxim behind it is folklore at D and is not asserted |
|
|
1349
|
+
| Write a sentence that could be false | Procedure, in `Abstraction control` | HOUSE. The origin is an unattributable D-grade maxim |
|
|
1350
|
+
| Objection-built microcopy under a control | Procedure, in `CTA standard > Microcopy under the control` | HOUSE, alongside the link-purpose evidence that supports the label rules |
|
|
1351
|
+
| A team's boredom with its own copy is not a defect | Warning, in `Corpus-level variance` | HOUSE. Practitioner observation at C, no method |
|
|
1352
|
+
| Prefer a checkable specific to an unsupported superlative | Rule, in `Specificity against superlative` | HOUSE, resting on the truth rules. The practitioner claim that superlatives destroy credibility is D and is not asserted |
|
|
1353
|
+
| An over-narrow control label excludes readers it did not name | Boundary, in `The required shape` | HOUSE. One teardown, Grade D, no effect claimed |
|
|
1354
|
+
|
|
1355
|
+
What was refused and stays refused: every vendor-reported split-test figure in that pass, the claim that one CTA wording doubles conversions, the claim that superlatives destroy credibility, the rule that a comma signals a sentence needing to be broken, the read-aloud-in-a-false-accent variant, the customer-interview count offered as a sufficiency threshold, and category creation as a strategy. None of these may be written as a rule here.
|
|
1356
|
+
|
|
1357
|
+
Two conflicts from that pass are open and stay open. Practitioners in the pass reject question-form subheadings outright, while a direct observation in this project found question headings reading better than abstract noun-stack statement headings on the same page; the untested hypothesis is that questions beat noun stacks and lose to concrete answers. Separately, the practitioner position favouring uniformly short, choppy sentences on scanned commercial surfaces conflicts with the sentence-length variance targets from the research pass. Neither side of either conflict is graded above D. Do not resolve either by writing a rule.
|
|
1358
|
+
|
|
1359
|
+
### Myths this document must never assert
|
|
1360
|
+
|
|
1361
|
+
These circulate constantly, arrive with a number attached, and are the most likely things a future editor reintroduces by accident. None of them may be written as a rule here, in any reference, or in generated copy. Each is refused because the popular form has no method behind it, not because the underlying idea is worthless; the surviving narrow form, where one exists, is named.
|
|
1362
|
+
|
|
1363
|
+
| Never assert | What may be said instead |
|
|
1364
|
+
|---|---|
|
|
1365
|
+
| A fixed share of readers reads the headline and not the body, in any ratio | Nothing. No sampling frame or study travels with any version of it. |
|
|
1366
|
+
| Any fixed optimal headline, title, or subject length in words or characters | Front-load the discriminating information, because rendering surfaces truncate the tail. |
|
|
1367
|
+
| That odd numbers, power words, punctuation marks, or button colours carry a percentage lift | Wording and design effects are real and contextual, and none of these is a measured constant. |
|
|
1368
|
+
| That first-person button copy beats second-person copy | Pronoun framing is a test variable. The famous comparison had no pronounless arm and no located replication. |
|
|
1369
|
+
| That a call to action must sit above the fold | First-viewport content receives disproportionate attention. Placement is not thereby a rule. |
|
|
1370
|
+
| That one call to action per page always outperforms several | One campaign goal is a design doctrine. Repeated instances of one action are not competing actions. |
|
|
1371
|
+
| That slogan-shaped labels convert worse as a class | Reject them for operational ambiguity, which is observable. |
|
|
1372
|
+
| That copy should target a fixed reading grade | Readability scores are a coarse alarm and never a definition of comprehension. |
|
|
1373
|
+
| That buyers complete a fixed percentage of the purchase before contacting a seller | The figure varies by study, sample, and definition, and the popular version conflates three different statistics. |
|
|
1374
|
+
| That a company must create a new category to win | Category framing has cognitive evidence. Compulsory category invention does not. |
|
|
1375
|
+
| That people buy on emotion and justify with logic | No source measures the ordering. |
|
|
1376
|
+
| That stories are a stated multiple more memorable than facts | Narrative effects are real and modest, and statistical evidence has often won direct comparisons. |
|
|
1377
|
+
| That losses are twice as powerful as gains, applied to copy | Reference-dependent evaluation occurs. Framing differences in messages are commonly tiny, null, or in favour of gain framing. |
|
|
1378
|
+
| That a stated percentage of purchase decisions is subconscious | The figure describes general cognition, not purchases. |
|
|
1379
|
+
| That unresolved open loops make copy more memorable | The memory advantage did not survive meta-analysis. Use real, closable information gaps. |
|
|
1380
|
+
| That fear appeals backfire as a general rule | High threat with inadequate efficacy increases defensive responding. Net effects are positive on average, which licenses nothing. |
|
|
1381
|
+
| That average sentence length should sit under a fixed ceiling | Cadence targets in this library are governance defaults and say so. |
|
|
1382
|
+
| That passive voice is bad | Passive voice changes information structure. Measure its rate by register. |
|
|
1383
|
+
| That a self-contained passage is a fixed number of sentences | Self-containment is a semantic property, tested by `Required comprehension tests`. |
|
|
1384
|
+
| That an AI-detector score establishes authorship | Detector reliability is domain-dependent, degrades under obfuscation, and is biased against non-native English writing. |
|
|
1385
|
+
|
|
1386
|
+
The full block list, with lineage and adjudication for each entry, is maintained outside the published skill. Before adding any rule that sounds familiar, check it there first.
|
|
1387
|
+
|
|
702
1388
|
### Human voice and detector evidence
|
|
703
1389
|
|
|
704
|
-
Use the detector sources in `Human voice and AI-writing-tell gate`. They support caution about detection claims, dataset shift, paraphrasing, and human bias. The editorial bans on
|
|
1390
|
+
Use the detector sources in `Human voice and AI-writing-tell gate`. They support caution about detection claims, dataset shift, paraphrasing, and human bias. The absolute U+2014 character ban and the editorial bans on curly quotes, prompt leakage, canned templates, and generic significance tails are `HOUSE` rules. They are not proof of authorship.
|
|
705
1391
|
|
|
706
1392
|
### Preserved technical and research authorities
|
|
707
1393
|
|
|
@@ -757,4 +1443,7 @@ Change record:
|
|
|
757
1443
|
|
|
758
1444
|
| Date | Change |
|
|
759
1445
|
|---|---|
|
|
1446
|
+
| 2026-08-09 | Ran the graded research pass against the seven load-bearing claims. Removed four refuted thresholds: the per-sentence unfamiliar-concept limit, the abstract-noun count, the two-or-three-sentence passage unit, and universal heading-template uniqueness. Rebased abstraction control on actor recovery, the verb guidance on word frequency, the slogan-CTA rejection on operational ambiguity rather than a conversion claim, and mechanism naming on the separate awareness and sophistication axes. Split corpus variance by function so parallel syntax survives where it is functional metadata. Added the pronoun-ranking prohibition and the label-consistency boundary. |
|
|
1447
|
+
| 2026-08-09 | Marked the new comprehension and CTA rules HOUSE and provisional, and recorded the seven unsourced load-bearing claims in `Evidence register` pending a graded research pass. |
|
|
1448
|
+
| 2026-08-09 | Added `Plain language and first-read comprehension`. Raised comprehension to level 3 of the conflict hierarchy and resolved its two standing conflicts with material qualification and with citability. Rebuilt `CTA standard` around action labels, destination clarity, and cross-surface consistency. Scoped passage self-containment to the passage rather than the sentence. Added the differentiation counterweight to `Mechanism and differentiation`, corpus-level repetition to `Structural tells`, six applied pairs across new business types, and matching invariants and quality dimensions. |
|
|
760
1449
|
| 2026-07-19 | Rebuilt the authority for variable-depth persuasion, POSITION-first company profiles, proof salience, diagnostic enumeration, silent compliance, and project-agnostic operation. Added research on persuasion psychology, investor communication, channel architecture, and evaluation design. |
|