@creator-notes/cnotes 0.26.0 → 0.29.0

package/skills/cnotes/references/humanizer.md

@@ -0,0 +1,267 @@
+# The CreatorNotes humanizer
+
+Load this before you draft, audit, or rewrite **audience-facing prose** that will
+be saved to CreatorNotes: pre-reads, workshop notes, strategy notes, public
+drafts, Slack messages, canvas orientation banners, and the prose body of typed
+notes. Its job is to remove generic model habits so text lands as a real human
+author wrote it, **without corrupting meaning or erasing a legitimate voice**.
+
+Two things this is NOT:
+- It is not a truth checker. The model cannot verify a claim is correct; it can
+  only flag the three defects listed under [The three verifiable flags](#the-three-verifiable-flags).
+- It is not a personal-voice generator. Removing slop creates a quality *floor*.
+  A person's voice is a separate, optional layer (see [Two layers](#two-layers-quality-floor-and-personal-voice)).
+
+---
+
+## First decide: does this text get touched at all?
+
+Classify the task before editing a single word. Getting this gate right matters
+more than any word-level fix, because the failure that hurts is rewriting
+something that should have been left alone.
+
+**Apply the humanizer automatically** — agent-generated prose meant for a reader:
+pre-reads, Slack messages, strategy prose, workshop notes, public drafts, and
+canvas banners an agent wrote.
+
+**Audit first, change only on evidence** — existing authored material: decision
+records, reference guides, and any note carrying many relationships or
+measurements. Read it, list the specific problems, and revise only the notes with
+real defects. Most audits should change *some* notes and leave others untouched.
+
+**Never rewrite silently** — raw capture where the words are the evidence: raw
+transcripts, voice memos, customer quotes, source evidence, legal text, and
+human-authored material where the voice itself is the record. Store these
+unchanged. If a reader needs a clean version, humanize the *derived artifact*,
+never the source.
+
+**Override language wins over all of the above.** If the user says any of these,
+follow the instruction and stop:
+- "Save this as raw capture. Do not humanize it." → store verbatim.
+- "Audit X for AI writing. Do not change anything." → report only, no writes.
+- "Humanize X. Preserve timings, links and questions." → rewrite with the named
+  things held fixed.
+- "Rewrite this in my personal voice." → apply a voice card on top of the floor.
+- "Use the neutral / company voice." → no personal voice, shared-artifact tone.
+
+---
+
+## The four modes
+
+| Mode | What you do |
+|---|---|
+| **Draft cleanly** | Author new prose already free of slop — the audit is baked into the first draft, not bolted on. |
+| **Audit only** | Report defects with locations and no edits. Hand the nuanced findings to the user. |
+| **Rewrite with preservation** | Fix the flagged prose while the preservation gate holds every fact, number, ID, and link fixed. |
+| **Match a voice card** | Apply an optional personal or company voice on top of the clean floor. |
+
+Default to **Draft cleanly** for new prose and **Audit only** for existing
+material. Only rewrite existing notes once an audit has named the specific defect.
+
+---
+
+## The workflow
+
+### New agent-generated prose (draft → audit → preserve → save)
+
+1. **Draft for meaning** and the note-type rubric (`cnotes types show <Type>`).
+   Own the outline yourself before filling it in — see [Structural slop](#structural-slop-own-your-outline).
+2. **Run the anti-slop audit** against the kill-list and moves below.
+3. **Remove high-confidence pattern clusters, not isolated words.** A single
+   flagged word in otherwise clean prose is usually a false positive. A *cluster*
+   (hype adjective + filler verb + rule-of-three in the same paragraph) is real slop.
+4. **Run the preservation check** — verify nothing in the [preservation gate](#the-preservation-gate)
+   changed.
+5. **Save** with a `# h1` title and readable relationship-mention titles.
+
+### Existing notes and canvases (audit → select → version → verify)
+
+1. Read the canvas digest (`cnotes canvas digest <id>`) and the note bodies.
+2. **Audit only.** Identify notes with clear problems; leave clean notes alone.
+3. Create a new version (`cnotes versions create`) **only** for the selected notes,
+   with a change description saying what you fixed.
+4. Replace affected canvas richtext banners separately (text elements have no
+   version history — remove and re-add).
+5. **Verify** numbers, names, IDs, links, mention titles, tables, uncertainty,
+   and canvas layout survived unchanged.
+
+---
+
+## The anti-slop audit
+
+Slop is a bundle of habits, not a list of words. Scrub the vocabulary and a
+symmetrical skeleton still reads machine-built. Fix both.
+
+### The one rule under all of these
+
+When you catch a hit, **do not swap it for a quieter synonym** — a calmer slop
+word is still slop. Replace it with one of three things:
+- a **concrete noun** (the graph, the version, the transcript),
+- a **number with its baseline** ("nine minutes to ninety seconds on the
+  two-thousand-file repo"),
+- an **active verb that names the behavior** ("re-indexes on every edit", "links
+  each claim to its evidence").
+
+If you cannot make the line concrete, the line has no claim. Cut it.
+
+### Words — cut on sight
+
+**A. Hype / greatness adjectives** (grade us instead of describing behavior):
+powerful, seamless, robust, scalable, cutting-edge, revolutionary, game-changer,
+innovative, world-class, best-in-class, effortless, magical, intuitive
+(self-claimed). *Fix:* state the behavior.
+
+**B. AI-slop verbs and nouns** (filler the model reaches for): delve, leverage,
+harness, unlock, unleash, supercharge, streamline, elevate, empower, foster,
+tapestry, journey, landscape, ecosystem, realm, synergy, paradigm shift.
+*Fix:* name the action or the thing.
+
+**C. Slop connective tissue** (announces a transition, carries no information —
+delete the phrase, keep the sentence): furthermore, moreover, additionally, in
+conclusion, it is important to note, it is worth noting, needless to say, aims to
+(→ present-tense verb), when it comes to (→ the subject itself), at the end of the
+day, in today's fast-paced world.
+
+**D. Category cliches** (name the outcome and the pain, not the category): second
+brain, PKM, note-taking app, knowledge base, all-in-one workspace, digital brain,
+smart notes, AI notes, AI-powered notes, "X alternative".
+
+**E. Personal-ban tics** (our own recurring habits): actually, simply, just (as
+filler), really (as intensifier), might, perhaps, kind of, thrilled, excited.
+
+### Moves — a sentence can pass every word check and still be slop
+
+| Banned move | Do instead |
+|---|---|
+| Em dashes in user-facing prose | rewrite the sentence; split it or use a period |
+| Comparison framing ("unlike X", "the only X that") | state what we do; name a shared category truth, no rival |
+| Absolutes (everyone, nobody, always, the only) | state the specific case and let it stand |
+| Antithesis template ("not just X, it is Y") | make the affirmative claim once |
+| Negation-reversal with a clipped echo ("X was not the bottleneck. Y was.") | state the claim by consequence, not as a "Not X. Y." flip |
+| Rule-of-three triples ("Focused. Aligned. Measurable.") | one claim that carries its own weight |
+| Throat-clearing openers ("a thread on", "I want to share") | open with the problem or the payoff |
+| Thread-bro formatting ("1/", "follow for more") | write as prose with a standalone first line |
+| Engagement bait ("comment YES", "drop a fire emoji") | end on the value, not the ask |
+| Numbers with no baseline, date, or source | pair every number with its baseline and where it came from |
+| Both-sides hedge-seesaw presented as a view | commit to a stance and name its cost |
+| Exclamation points in feature copy | a period; the usefulness is the news |
+
+### Structural slop — own your outline
+
+Structure is the deeper tell than vocabulary. A tidy intro, three even sections,
+and a balanced conclusion pattern-match to generated text even after every banned
+word is gone. Write the spine yourself, then let the draft fill inside it. If the
+skeleton is symmetrical, break the symmetry before you touch the words.
+
+### Watch the over-correction
+
+Humanizing fixes meaning and structure. Do not thesaurus-swap a banned word for a
+near-synonym (that trades one tell for another), and do not manufacture fake
+casualness in place of formal prose that was doing real work. Rewrite the sentence
+around the load-bearing fact, or leave it.
+
+---
+
+## The three verifiable flags
+
+These are the only defects a model can flag **without knowing whether the claim is
+true**. A precise-sounding but unsourced number passes every linter, so do not
+pretend to grade truth or calibration. Flag these three, and pair every
+concreteness check with a source check:
+
+1. **Unredeemed abstraction** — a comparative or magnitude word (better, faster,
+   bigger, significant, most, many, soon, a lot) with no number, unit, baseline,
+   and date. Demand the operand: better on which metric, from what baseline to
+   what target, by when.
+2. **Missing falsifier** — on an empirical or decision claim, no statable "this is
+   wrong if X by date D."
+3. **Naked claim** — a load-bearing claim with no linked Fact, Test, or Metric
+   (no supporting relationship mention).
+
+Surface these as questions for the author, not as silent rewrites — forcing a
+number where none exists only mints fake precision.
+
+---
+
+## The preservation gate
+
+Before saving any rewrite, confirm none of these changed. Each row is a real way
+humanization corrupts a note:
+
+- **Numbers, dates, names** — identical to the source.
+- **Negations, uncertainty, scope** — "not", "only", "up to", "we think",
+  "in some cases" carry meaning; do not drop or invert them.
+- **Legal / technical qualifiers** — a hedge that is a legal or technical
+  constraint is not slop. Keep it.
+- **Checklists and structured writing** — deliberate structure is not slop.
+  Do not flatten a checklist into a paragraph.
+- **Relationship mentions** — titles and links intact. `[NOTE-12: Title](relationship:type)`
+  must keep both the display ID and a readable title; never strip a mention to
+  bare text or drop its link.
+- **Tables and layout** — tables, columns, and canvas placement survive.
+- **Voice as evidence** — a customer quote or raw memo keeps its original wording.
+
+When in doubt, keep it and flag it in **Audit only** mode rather than rewriting.
+
+---
+
+## Two layers: quality floor and personal voice
+
+Removing slop creates a shared **quality floor**. It does not create a person's
+voice. Keep the two separate.
+
+### The shared quality floor (always)
+
+The anti-slop audit above. Applies to everyone and every genre. It removes
+corporate fog, fake contrasts, forced triads, and chatbot residue.
+
+### Optional personal voice cards (only when asked)
+
+A voice card is a **local**, **genre-specific** profile built from writing the
+author chose. One universal "sound like me" profile is too blunt: a Slack message,
+a strategy note, a public article, and a technical spec should not sound
+identical. A card can capture directness, sentence rhythm, formality, humour,
+preferred vocabulary, spelling, punctuation, heading style, and how strongly the
+author states opinions. Store it locally by default; share only when the author
+chooses. Never impose one person's voice on every user.
+
+### Shared artifacts use a neutral or company voice
+
+Company-facing documents use a **neutral CreatorNotes voice or a company voice**,
+not an individual's profile. When the author is the team, write in a steady first
+person: attach each opinion to the specific decision or failure that produced it,
+so credibility comes from the work, not from adjectives. A bolt-on "I personally
+believe" in front of a generic claim still reads synthetic — the first person has
+to carry a real detail (a number, a named workflow, a decision and what it cost),
+or cut both the "I" and the claim.
+
+---
+
+## CreatorNotes mechanics (deterministic — always apply)
+
+These are objective and never need judgment. Enforce them on every write:
+
+- **Canvas titles** use the middle dot `·` (U+00B7) as a separator, never an
+  em dash or en dash.
+- **Every note starts with a `# h1`** heading — it becomes the title.
+- **Relationship mentions include a readable title**: `[NOTE-123: Title](relationship:type)`,
+  never bare `NOTE-123`.
+- **No mention syntax inside canvas richtext or list descriptions** — it corrupts
+  the card. Reference notes there as plain display IDs ("see RISK-64").
+- **Richtext stays card-sized** — at most ~3 sentences, one heading; distinct
+  items are N typed notes, not a wall of text.
+- **No placeholder or artifact tokens** — "lorem ipsum", "TODO", "[insert X]",
+  "as an AI language model", or leftover template markers never ship in saved prose.
+- **Valid mention syntax and live links** — no broken links, no malformed mentions.
+
+---
+
+## Restraint is the most important behavior
+
+The measure of a good pass is not the number of edits. It is the willingness to
+leave clean notes alone. A selective pass that fixes the three genuinely-slopped
+notes and leaves nine good ones untouched is a success. A pass that rewrites every
+note because a detector word appeared somewhere is the failure this whole
+reference exists to prevent.
+
+If a note already reads as a real person wrote it, do nothing.