---
title: VOICE.md — voice & tone
summary: The standard for anything published in Tjakoen's name - cadence, the machine-tells to avoid, the honesty clause, and what a reader meets first.
when: >
  Read this BEFORE writing the first line of prose that carries Tjakoen's byline, and before editing
  existing prose: a note, a blog post, a README, a page, a commit message, release copy, social copy,
  product copy. Don't skip because it is internal, a draft, a one-liner, or "just a README" - the
  voice rules have no off switch, and no em-dash reads better here.
---

# Voice & Tone: how Tjakoen writes

> The standard for anything published in Tjakoen's name (notes, the whitepaper, READMEs, the blog,
> social posts, product copy). If you (human or AI) are drafting prose that will carry his byline,
> match this. It's two things in one: the **how** (cadence, mechanics, the honesty clause) and the
> **what** (the real specifics his voice runs on, the opinions it argues, and the machine-tells it
> refuses). Derived from his own drafts, primarily [`notes/origin-story.md`](/notes/origin-story)
> (marked "my own voice") and [the whitepaper](/notes/whitepaper-one-vocabulary), and everything
> concrete here is drawn from real projects.
>
> **It is a projection of how he already works. Update it when the work changes, not the other way
> around.** The content guardrails below (money vague, no names beyond public info, no student data)
> govern everything here: a specific being *real* doesn't automatically make it *publishable*.

## In one line

**Honest, self-aware, and precise: a smart friend explaining something he actually cares about,
who refuses to bullshit you and refuses to bore you.** Warm but not soft; confident but not
salesy; technical but never jargon-drunk. The through-line on every surface: **no corporate voice,
no hype, no hiding the hard parts.**

## Core principles

1. **Open with a confession or a real stake, not a thesis.** He earns attention by being human
   first. *"I would not describe myself as a fully functional adult."* / *"This note was born of
   pure cheapness."* Lead with the honest, slightly vulnerable truth; the argument comes after.

2. **Concrete over abstract, always.** Name the real tools, cite the real numbers, point at the real
   thing. Abstractions are earned by specifics, never asserted. The fastest way a draft goes
   off-voice is inventing a vague placeholder where a real name belongs. Reach into *The specifics
   bank* below instead.

3. **Opinionated, and says why.** He takes a side and gives the concrete reason: *"I landed on Bun
   for a concrete reason, not the usual hype."* Never hedge into mush. *The opinion stack* below is
   the actual list of stances, so a draft argues **his** side with **his** reasoning.

4. **Intellectually honest about limits.** He names what he has *not* earned yet: *"it needs real
   studies with real people, and I say so plainly."* State the cost, the trade, the unproven claim.
   Honesty is the credibility.

5. **Quirky and light, this is load-bearing, not decoration.** He does not take himself too
   seriously, and the writing shouldn't either. Dry, self-deprecating humor is the *default*
   setting, not an occasional garnish: *"collecting abandoned workspaces like a very tidy hoarder,"*
   *"one chronically disorganized human and one alarmingly tidy AI."* The joke is almost always at
   his own expense, it is understated, and it lands in one clause before he moves on. If a paragraph
   reads earnest and buttoned-up all the way through, it is off-voice: find the wink. Serious point,
   unserious delivery.

6. **Every piece is a small narrative.** There is a turn, a "here is the part that changed
   something," and a callback at the end. Section headers read like story beats, not labels:
   *"Then a class I did not ask for lit the fuse."*

7. **Pragmatic and allergic to ceremony.** He respects people's time and hates fluff: *"I'm not
   going to waste time with slides about what an application is."* Get to the real thing fast, cut
   the throat-clearing, no filler transitions, no restating-the-obvious. If a sentence is just being
   polite, delete it.

8. **Owns his own flaws as part of the story.** He's candid about the unflattering bits:
   procrastinating, over-committing, getting overwhelmed, grading at the last minute. He states them
   plainly, without either drama or humble-brag, usually as the setup for what he did about it. The
   vulnerability is what makes the competence believable.

9. **Credentials are mileage, not medals.** When a piece has to establish that he's competent (and
   sometimes it must, the multiplier thesis depends on it), never list titles bare: a row of clean
   credentials reads as a boast, and he flagged exactly that. Price each item instead: what it cost,
   why he had to, what unglamorous thing it actually consists of. *"I run a team of developers, which
   is mostly reading other people's code and finding the problems politely."* / *"I only built the
   platform because the grading was about to bury me."* And say why the list is there at all (to
   place him on the multiplier, not to impress).

10. **Understate the drama, then bank the lesson.** The big, painful beats land *flattest*. Businesses
   that *collapsed*, a launch that *went nowhere*, a plan that *crashed*: no melodrama, the weight is
   in the fact, not the adjective. And every failure closes with what it bought him, plainly, without
   bitterness or humble-brag: *I don't regret it, I learned a lot.* Same reflex with luck, he names it
   as luck (*I got lucky my first interview was with the CTO*) and never backfills a pure-merit story.
   The through-line is a person who has metabolized his losses into maxims (*you have to be the right
   person before you try the thing*), the way *ten times zero* is a lesson worn smooth. Failure
   stated, lesson banked, move on. Never wallow, never spin.

## Register by surface

Same voice, different dial settings. Contractions are resolved here: this is the single source for it.

| Surface | Contractions | Length | Dial |
|---|---|---|---|
| **Whitepaper / formal docs** | Expanded (*do not*, *cannot*) | Longest, measured | Literary, deliberate. The origin-story cadence. |
| **Blog / notes** | Contract freely (*I'm*, *here's*) | Medium, narrative | Loose, warm, a little irreverent. A vibe-coding blog should *read* like vibe coding. |
| **Guide / outward-facing** | Contract | Medium, structured | Same warmth, no first person. The reader has a decision and a budget, so the thesis lands in sentence one and the skim path carries the argument. Shape owned by [NOTE-STANDARD.md](NOTE-STANDARD.md). |
| **README prose** | Contract | Short, oriented | Get them running fast. Still human (italics not backticks, a wink in the intro) but skip the story arc. |
| **Social posts** | Contract, hard | Very short | One confession or one sharp claim, one specific, done. The pull-quote *is* the post. No thread throat-clearing, no "a 🧵". Lead with the hook, land in one line. |
| **Reference docs** (ARCHITECTURE, CONVENTIONS) | N/A | As long as needed | The one place backticks and literal tokens are correct. Precision over personality. |
| **Code review comment** | Contract | Very short | Ask, don't declare. State the mechanism in plain words, then put the fix as a question the author can say no to. Backticks are correct here, a file and a line have to be exact. The claim and the ask stay visible, the proof folds (see *What a reader meets first*). |
| **Ticket / PR comment** (Jira, a PR conversation) | Contract | Short, grouped | Built to be scanned. A bold line naming who has to act opens it, then short groups under lead-in lines, each a few bullets, with a blank line between groups. Every ticket key is a link. A comment with one thing to say stays one line. See *What a reader meets first*. |
| **Chat / casual** | Contract, typo-tolerant | Whatever | Fast, high energy. Keep its directness and honesty; never import chat looseness into published work. |

**Social, specifically**, it's the origin-story open with the essay amputated. Take the single most
honest or most opinionated line, front it, add one real specific, stop. *"I would not describe
myself as a fully functional adult, and yet I built a design system that lets an AI drive its own
buttons. Vanilla HTML. No framework. Ask me how."* That shape: confession, flex, specific, door
left open.

## Sentence mechanics & rhythm

- **Vary length hard.** A long, winding sentence that carries the idea, then a short one that lands
  it. The short sentence is the punch: *"Prompt and pray."* / *"Real output."*
- **Rule of three & repetition for rhythm.** *"learn its system, fall off that one, and go around
  again."* One deliberate tricolon is rhythm; every list arriving in tidy threes is a machine tell
  (see *Do not sound like the machine*).
- **Avoid em-dashes. A big no-no.** They have become one of the loudest AI tells, so the default is
  none. Use a comma, a period, a colon, or parentheses, or just rewrite the sentence. (This reverses an
  older "em-dash is the signature" stance: the prose reads *more* human without them.) Keep one only
  when nothing else carries a genuine pivot, and never two in a paragraph.
- **Direct address, sparingly.** *"You know the tone."* Pull the reader in at key moments.

## Signature moves

- **The pull-quote.** Lift the single most important line out into a blockquote on its own:
  > I wanted to stay exactly as disorganized as I am, and have the software deal with it.
- **The homey metaphor over the grand one.** Grounded, physical, never grandiose (see *The metaphor
  bank*).
- **The confession-inside-the-confession.** He layers admissions: *"here is a confession inside the
  confession: I am a design-systems person to my core."* Candor, not digression.
- **The callback close.** End by returning to the opening image with a turn: the origin story ends
  handing the wheel to the desk: *"It will be the desk's."* then *"Noted. I'll take it from here."*

Use these as a *repertoire*, not a checklist; see the formula tell below. Draw two or three per
piece; rotate the openers especially.

## The metaphor bank

Homey and physical over grand and abstract. His own, reusable:

- **The piano in the same room:** *"it plays the same piano I do, in the same room, where I can
  watch its hands."* The AI-operability thesis in one image. The gold standard; don't overuse it.
- **Grain vs. clean ink:** machine had a hand in it vs. settled and human. Works literally (the
  type) and as metaphor (a draft, a decision, a claim not yet earned).
- **The tidy AI / the messy human:** *"one chronically disorganized human and one alarmingly tidy
  AI."* The whole partnership as an odd-couple bit; self-deprecation doing structural work.
- **The desk that takes the wheel:** software dealing with his disorganization *for* him, so he can
  stay exactly as disorganized as he is. Autonomy handed to the tool on purpose.
- **Ten times zero:** the multiplier truth, math as punchline.
- **The single write door / one way in:** the intent-based architecture. One door, watched,
  deliberate, not a dozen unguarded side entrances.

New metaphors should feel like these: something you could point at in a room, at his own expense
where possible, never mixed or grandiose.

## Punctuation & formatting conventions

- **No backticks in prose. This is a hard rule.** Backticks are the number-one tell that a machine
  wrote something: humans writing an essay do not wrap `words` in code ticks. In anything meant to
  *read* as human (notes, blog, origin story, README prose, social), write technical terms as plain
  words, in *italics*, or as a real markdown [link](.). **The only exception:** fenced code *blocks*
  of actual code, and hard reference docs where a literal token must be exact (ARCHITECTURE,
  CONVENTIONS, and this standard, for filenames). When in doubt, drop the ticks; looking human wins.
- **Italics for stress**, on the one word that carries the sentence: *is*, *same*, *first*. Not bold
  on every other phrase (a tell).
- **Blockquotes** for (a) pull-quotes and (b) `> *Figure: ...*` placeholders describing a diagram to
  be rendered later.
- **American spelling** (realized, not realised).
- **Frontmatter** on every note: `title`, `subtitle`, `author`, `status`, `type`, `date`,
  `readingTime`, `tags`, `summary`. (The full template, structure checklist, and a runnable
  drafting prompt live in the sibling standard [`NOTE-STANDARD.md`](NOTE-STANDARD.md).)
- **The sign-off boilerplate**, at the foot of published notes:
  > *The [judgment is human](/notes/ten-times-zero). The typing, by design, is not.*

  This footer speaks only to the **content's authorship**, exactly as a repo footer speaks to the
  code's (co-authored, receipts link). It replaces the older *"Written by a human"* line, which
  overclaimed: the AI drafts the prose (that is what this guide is *for*); the human supplies the
  content, the direction, and the approval. The honest split is the point. Link *"judgment is
  human"* to [`notes/ten-times-zero.md`](/notes/ten-times-zero) the way every repo footer links
  its "how I work with AI" receipts (see [`README-STANDARD.md`](README-STANDARD.md)); the flagship
  post itself doesn't self-link and swaps the tail for *"On this one, nearly all of it."*

  **Not in this footer:** *"Rendered by the stack it is about"* and the grain legend describe the
  *page*, not the post, so they live in the site/page chrome footer (rendered once), never per-note.

## What a reader meets first

Twenty-five code reviews went out with the verdict on the last line. Every one of them opened with
my reasoning, so the developer had to walk past two thousand characters of me explaining why I was
right before reaching the sentence that told them whether they could merge. The one part I had
thought to fold away was the evidence table, which is the part nobody needed. That is the whole
lesson, and it is not about code review: **a reader decides whether to read a thing from its first
screen, so the first screen holds what they have to act on, and everything that only proves it folds
behind that.**

The numbers, from two days of real output and therefore a snapshot rather than a standing fact: 25
review bodies, verdict last in 25 of them. Forty-one comments alongside, averaging 694 visible
characters, where the claim and the ask together ran a median of 253. Two of the 41 folded anything
at all. So roughly two thirds of what I was putting in front of people was proof they had not asked
for yet.

The repair is four rules, and they apply to a README, a note, a pull request, a message to a
colleague, anything a person meets in a narrow column on a phone:

- **Front what they do, fold what proves it.** Sort by whether the reader has to act on it, never by
  category or by how hard it was to work out. A test gap that blocks the merge is visible; an
  accessibility finding that deserves its own ticket folds. Both are real, and only one of them is
  today's business.
- **Fix the fold's label, and keep it short.** Those 25 documents used fourteen different labels on
  the fold for two actual kinds of block. A label that changes every time is a label nobody learns,
  so the fold gets opened every time or never, and both are failures. Three labels is a set; fourteen
  is a shrug.
- **Put a count on the label when there is one.** *Also worth doing (3)* tells a reader whether the
  tap is worth it. *Three smaller things, folded* does not, and it is the same number of characters.
- **A hedge is never folded.** This is the honesty clause meeting the layout rule, and the layout
  rule loses. If a claim rests on something I have not run, or on a reading I am not sure of, that
  caveat sits in the visible region next to the claim it qualifies. Fold *"I have not tested this"*
  and a careful finding becomes a flat assertion, which is exactly the overclaim the clause below
  exists to prevent. If the visible region will not hold the claim, the ask and the caveat together,
  the claim sentence is too long. Trim the claim. Never bury the caveat.

And the first line is the only line you are guaranteed. Collapsed views, notification digests and
link previews all show line one and drop the rest, so line one carries the claim on its own. Never
open with setup, and never open with a restatement of the thing the reader is already looking at.

### Ticket and pull request comments

A ticket comment gets read in a sidebar, between two other tickets, by someone deciding whether it
is their turn. A paragraph makes them read all of it to find out. So a comment that carries more
than one thing is laid out for scanning rather than for reading straight through:

- **The action goes on the first line, in bold, with who owns it.** *Needs a check:* when someone has
  to verify something, *Needs the reporter:* when only the person who filed it can answer. This is
  the one place bold is right, because it is a label rather than stress. Nothing else in the comment
  gets bolded, and the ban on bold scattered through every other phrase stands.
- **The rest sits in short groups.** Each group opens with a plain lead-in line that says what it is
  (*What I tried*, *What is still open*), then a few bullets under it. Put a blank line between
  groups, because a group that touches the next one reads as one long list. A group holds as many
  bullets as it has facts: two is fine, five is fine, and three every time is the tidy-list tell
  coming back in through the layout.
- **Every ticket key is a link.** A bare key makes the reader copy it into a search box, which is
  work I could have done once for every reader.
- **A one-line comment stays one line.** *"Fixed in [EDGE-4120](.), back to you."* needs no heading,
  no group and no bullet. Structure is for comments that have more than one thing to say, never a
  costume put on a short one.

What that looks like, for a comment on a pre-prod test ticket:

> **Needs the reporter:** which account were you signed in as when the export came back empty?
>
> What I checked on pre-prod
> - The export runs and fills for an admin account.
> - The same report as a counselor comes back empty, which matches what you saw.
>
> What is still open
> - Whether this is permissions or the date filter. I have not ruled out the filter yet.
> - It may share a cause with [EDGE-4118](.), which reports an empty roster on the same page.

The caveat sits in the visible bullets, next to the claim it qualifies, for the same reason as the
hedge rule above.

**What I have not shown.** Whether folding actually raises the odds of feedback being acted on is
still open on my own numbers: the folded items ran well below the visible ones for adoption before
the change, and the sample since is small. The argument here is that a reader who never reaches the
ask cannot act on it, which is a floor rather than a proof. If the next pass says otherwise, the
problem was volume all along and the fix is writing less, not folding more.

## Figures & visualizations

He loves visuals, so a note should carry them, not lean on walls of prose. The full standard, the
tool-by-job rule, the **tokenized SVG scaffold** (palette as CSS custom properties, one canonical
spec so figures are a family and not one-offs), the type scale, and the render matrix, lives in
[`FIGURES.md`](FIGURES.md). The short version: **quantitative data-viz (bars, timelines, ratios, the
multiplier) is inline SVG built to the scaffold, and so are flows and loops.** A hand-built flow is
the default rather than mermaid, and a mermaid fence that does reach a page has to carry a label
naming what it shows. Early on a figure can be a prose placeholder (`> *Figure: what it shows*`);
render it before publish. Placeholders are a to-do list, not a finished state, don't ship an
all-prose note.

## The specifics bank

Reach into this shelf instead of writing *"a modern typeface"* or *"a recent project."* All real.
(Real ≠ automatically publishable; see the guardrails.)

**Projects (the recurring cast)**
- **TJ's Desk:** his personal site (tjakoen.github.io), a portfolio, a notebook, and a live demo
  of the stack, built on it. E-ink / Swiss-editorial; the flagship of his aesthetic.
- **The AI-operable design system (GRAIN + BATCH):** a docs site that doesn't just *describe*
  components, it lets the AI *drive* them: drivable catalog, build queue, token playground. The
  thesis project.
- **An internal planning document:** the operating doc and deck for his engineering team.
  Swiss-editorial house style, vermilion ember accent. *(Internal; unnamed on purpose.)*
- **A small internal automation:** a Google Apps Script bot posting daily attendance cards to chat,
  logging to Sheets. Homemade-tool energy: small, useful, his. *(Internal; unnamed on purpose.)*
- **The ETA-9130 mock generator:** a self-contained HTML prototype for demo / sales engineering. The
  "I built the whole thing in one file" flex, done straight.

**The stack, by name:** Vanilla HTML and CSS. Bun. Atomic design. Redaction (MCKL). Marked.js for
the living catalog. WebLLM / a small Qwen model for in-browser AI. GitHub Pages. VS Code. And (flown
proudly) Claude. Never *"AI tooling"* when you can say which one.

**The design language (his, and precise)**
- **E-ink / Swiss editorial.** Warm paper, soft near-black ink, no shadows, no gradients, no lift.
- **Grain as meaning, not decoration.** Redaction's degradation grades carry a *semantic* signal:
  grain for AI-generated or in-transit content, clean for settled, human content. The single most
  on-brand idea he has: use it, literally and as metaphor.
- **Atomic, at the atom layer.** Behaviors live where they belong and cascade by inheritance, never
  bolted on per component. He's *"a design-systems person to my core"*; it shows in how he reasons,
  not just how things look.

**The numbers (snapshots; flag them as such):** 150 to 300 students a semester. 16-hour days. 33
commits. Cite real counts; flag when a number is a snapshot rather than a standing fact. The real one
or none.

**The roles (all true, all at once):** Dev Manager and de facto tech lead on his engineering team at
**Career Team**. Software-engineering instructor. Thesis advisor. Interim product lead. The *"one
person wearing four hats"* reality is a genuine recurring stake, honest-open material, never a
humble-brag.

**Naming what he teaches:** *software engineering*, framed as the planning-and-architecture end of
the craft, never *"web development"* or *"web design"*. Those labels box him into the typing, and the
typing is the exact part his whole thesis says is not the value. When the subject needs a gloss, it's
his: less about typing code than about planning and shaping it.

## The opinion stack: what he argues

So a draft takes **his** side with **his** reasoning, not a plausible-sounding stranger's.

| Position | The one-line why (in his logic) |
|---|---|
| **No frameworks.** Vanilla HTML/CSS by choice. | They make you do things their way. He'd rather own the whole surface than rent someone's opinions. |
| **Design before build.** Iterate on paper, *then* type. | Wireframes are pen-and-paper in his course for a reason. The judgment is the work; the code is downstream. |
| **The AI drives the same controls a human would.** No backdoor API. | If the AI operates the *same* slider you do, it's a genuine new modality, not a gimmick. The shared surface is the whole point. |
| **AI is a multiplier, not an addend.** | *Ten times zero is still zero.* You can hand the typing to a machine only because you earned the judgment to catch it lying. Learn the fundamentals *so that* the tool amplifies instead of fooling you. |
| **Fly the AI flag, proudly.** | Yes, he uses Claude, out loud, receipts in hand, and ships real systems while people who sneer at "vibe coding" ship nothing. Never hedged, never a guilty secret. |
| **Small, self-hosted, owned.** One HTML file over a dependency tree; self-host the font over a CDN call. | Fewer moving parts he doesn't control. The homemade tool that does exactly one thing well. |
| **Be the right person first, then try the thing.** | Talent and nerve get you into rooms; they don't keep you there. He spent real money learning that starting things you're not ready for fails on *you*, not the idea. Same law as the multiplier: become worth it first. |
| **The grind is the point (relax ≠ retire).** Sixteen-hour days by choice. | Hard work gets results and he refuses to get complacent; grind now to earn the right to work on what he loves, on his own time. Not busywork for its own sake, a bet with a payoff date. |

If a draft argues the *opposite* of any row, it's off-voice regardless of how clean the prose is. The
two AI stances have deeper roots: the multiplier line is the human-capability precondition under the
augmentation thesis ([[ai-as-augmentation-thesis]]), *"using AI is only powerful if you can be
amazing without it"*, and the flag-flying posture is set out in [[voice-and-ai-positioning]].

## Diction: reach for / avoid (quick pass; full tell-list below)

| Reach for | Avoid |
|---|---|
| plain strong verbs (*build, prove, ship, refuse*) | corporate verbs (*leverage, utilize, empower, unlock*) |
| named specifics (Bun, 120 students, 33 commits) | vague intensifiers (*very, really, incredibly, game-changing*) |
| honest limits (*I have not earned this yet*) | overclaiming (*revolutionary, seamless, effortless*) |
| homey, physical metaphors | grandiose or mixed metaphors |
| "the machine," "the AI," "the desk" (product) | anthropomorphizing hype ("magical AI") |

## Do not sound like the machine

Half the reason this guide exists: **nothing under his name should read like it came out of a
chatbot.** Backticks are the loudest tell (see formatting), but they're one of a family. The machine
has a house style (smooth, balanced, eager, allergic to a rough edge), and every item below is a
fingerprint of it.

**Why a standard at all (the precedent, and the receipt).** This is not a new instinct. Structured
writing standards predate the chatbot by decades: ASD-STE100 (Simplified Technical English, first
issued 1986) exists so an aircraft manual reads the same in every hangar on earth, plain verbs, one
name per thing, no decorative fog. The surprise is that the same discipline lands on a language
model. [A 2026 experiment](https://github.com/woosal1337/blog/tree/main/videos/ep01-the-cure-for-ai-slop)
fed an STE-derived writing skill to Claude and GPT-4 and measured the slop drop by half or more
(roughly 50 to 74 percent) on every model tested, while a banned-word list alone barely moved the
needle. That is this whole guide in one finding: hand the model a *system*, not a blocklist. Two
honest caveats: the number is theirs, not a study of this voice, and STE's cockpit-manual rules
(no contractions, twenty-word cap, one instruction per sentence) are far stricter than a warm voice
wants. We keep the principle, borrow the one rule that fits (see *Nominalizations* below), and drop
the starch.

**A second borrowed source (and what was left behind).**
[no-ai-slop](https://github.com/petergyang/no-ai-slop) (petergyang, MIT-licensed) is a 2026 editing
skill that catalogues generated prose as *shapes* rather than as words, and that framing is what
earned the borrow. This guide had already banned *underscore* and *testament* as vocabulary while
leaving the sentence shapes those words live inside unnamed. Six of its patterns are folded into the
construction tells below (the colon reveal, the superficial-analysis clause, the faux-insight setup,
importance puffery, interpretive metadiscourse, synonym cycling), along with the portability test
further down and the editing pass that follows this section. What was declined matters as much: it
asks for complete sentences in place of dramatic fragments, and it deletes a closing metaphor
outright rather than rewriting it. Both would sand off moves this voice is built on, the hard
variation in sentence length, the callback close, the metaphor bank. Borrow the shapes, keep the
punch.

**Word-level tells (delete on sight):** *delve, tapestry, realm, landscape, navigate* (figuratively),
*underscore, testament, showcase, boasts, robust, seamless, harness, elevate, unlock, empower, foster,
myriad, plethora, ever-evolving, cutting-edge, game-changing.* If a word feels like it came free with
the model, cut it.

**Nominalizations (the verb hiding in a noun):** the machine loves *perform an analysis, provide a
solution, conduct a review, make use of, offer support for.* Every one is a plain verb wearing a
costume. Say *analyze, fix, review, use, support.* If a sentence has a limp verb (*perform, provide,
conduct, carry out, make*) propping up a noun that could just *be* the verb, collapse it. Shorter,
truer, and it drops a machine tell on the way out. (The one ASD-STE100 rule we keep, see *Why a
standard at all* above, because it fits a warm voice instead of fighting it.)

**Construction tells (the real giveaways: they're *shapes*)**
- **"It's not just X, it's Y."** The signature cadence of generated prose. He does not talk like
  this. Kill it every time.
- **"In today's fast-paced world…" / "In the world of…"** Throat-clearing openers. Start with the
  stake, not the scenery.
- **Everything in threes.** *"clean, simple, and effective."* Mechanical when every list is exactly
  three tidy, balanced items.
- **"Not only… but also." / "Moreover / Furthermore / Additionally."** Connective tissue no human
  says out loud.
- **The wrap-up paragraph.** *"In conclusion / Overall / Ultimately, X is a powerful tool that…"* He
  ends on a callback or a punch, never a book report.
- **The eager sign-off.** *"I hope this helps! / Feel free to / Let me know if…"* and *"Certainly! /
  Great question!"* Gone.
- **Both-sides mush.** *"On one hand… on the other hand…"* with no landing. Take the side.
- **Emoji as seasoning.** ✨🚀, no. Chat can be loose; published work stays clean.
- **The colon reveal.** A noun phrase, a colon, then a lowercase drama beat: *"The detail that makes
  it work: a separate agent grades it."* This is a trap the guide sets for itself, because the
  em-dash rule sends every pivot looking for a colon to live in. Rewrite it as a plain sentence. A
  colon introduces a list, a label or a quote; it does not hold suspense.
- **The superficial-analysis clause.** A trailing *-ing* clause that pretends to explain what a fact
  means: *"…, highlighting the team's commitment to better workflows."* Also *underscoring,
  reflecting, showcasing, demonstrating.* The word-tells above catch some of that vocabulary; this
  catches the move. Replace it with the actual consequence: *"…, so a reader finds an old draft
  without leaving the page."*
- **The faux-insight setup.** *"What nobody tells you…" / "The part everyone misses" / "What most
  people get wrong."* Every one of these flatters the writer as the only person in the room who sees
  it, which is the same boast the bare-credential rule bans. Cut the setup and let the claim stand by
  itself.
- **Importance puffery.** *"Stands as a testament to" / "marks a pivotal moment" / "plays a vital
  role" / "solidifies its position."* State the fact and let a reader decide whether it matters.
  *"The launch marks a pivotal moment"* becomes *"The launch is the first thing anyone paid for."*
- **Interpretive metadiscourse.** Prose stepping outside itself to direct the reader: *"This
  distinction matters," "the key point is," "as you can see,"* and a redundant *"in other words."* If
  the point is already clear, delete the aside. If it is not, the repair is a fact, not a nudge.
- **Synonym cycling.** Rotating names for one thing so a paragraph looks varied: *the agent* reviews
  the draft, *the assistant* scores it, *the tool* suggests fixes. One name per thing, repeated. (The
  second ASD-STE100 rule that survives a warm voice, and one this guide had skipped.)

**The formula tell (the trap this very guide creates):** the signature moves are a repertoire, not a
checklist. A piece that completes every move (confession open, wink by paragraph two, one tricolon,
the piano metaphor, callback close) reads as formula by the third post, and formula is a machine
fingerprint no matter how on-voice each ingredient is. Real writers are uneven: sometimes no metaphor,
sometimes two confessions, sometimes an ending that just stops. Draw two or three moves per piece and
leave the rest on the shelf. Rotate the openers: some pieces start mid-problem, some with the
pull-quote, some with a number.

**Em-dashes: a big no-no.** The internet now reads the em-dash itself as an AI tell, and that is the
call here: avoid them. Rewrite with a comma, a period, a colon, or parentheses. His older drafts lean
on them heavily (the origin story especially), so de-em-dashing existing prose is genuine, per-sentence
work, but going forward the default is none. A rare, truly load-bearing pivot can survive; a decorative
one never does. When in doubt, there is no doubt: cut it.

**The tell underneath all the tells:** the deepest fingerprint is **texture, not vocabulary**:
paragraphs all the same length, every point neatly balanced, no rough edge, no real opinion, no joke
at his own expense, nothing that could not have been written about anyone by anyone. The fix is this
whole guide: a confession up front, one genuine stake, a real number, a wink, a sentence that is
*too short*. The test:

> **If a passage is clean, correct, and forgettable, it sounds like AI. Make it his.**

**The portability test, for one sentence at a time.** The texture tell is easy to state and hard to
act on, so here is the per-sentence version. Move the sentence, unchanged, to another person, another
company, another product. If it still reads as true, it was never about this subject and it is
filler. Replace it with a fact, a mechanism, a consequence or a judgment that only survives here.
*"The integration improved efficiency"* travels anywhere. *"The integration cut the deploy from forty
minutes to four"* cannot leave the building.

And the deeper irony, worth saying plainly since he flies the flag: the way you keep AI-assisted
writing from *sounding* like AI is to have the judgment to catch it, the same multiplier truth. Ten
times zero is still zero. The voice is the part the machine cannot supply.

## Editing a draft that already exists

Most of this guide describes writing. Half the real work is the other job: prose already on the page,
his or a model's, that has to come up to the standard. The de-em-dashing backlog in the older drafts
is the standing example, and it is where an over-eager pass does the most damage.

- **Make the minimum effective edit.** Fix the tells, the errors, the repetition and anything
  genuinely hard to follow. Then stop. A strong human sentence stays as it is even when a tidier one
  is available, and a rough draft with a real voice should sound like the same person afterwards.
- **Even tidiness is the failure, not the goal.** A pass that leaves every paragraph the same length
  and every point equally balanced has swapped one machine texture for another. Unevenness is the
  evidence a person was here.
- **Cut in proportion to the actual slop.** Aggressive compression takes the character out along with
  the filler. If a pass removed a third of the words, go back and look at what left with them.
- **Keep the edge.** Blunt phrasing, a self-interruption, an admission that does not flatter him:
  these are the lines most likely to look like problems to a model, and usually the reason the piece
  works at all. They stay.
- **Say what changed, and why.** An editing pass owes a short list of what moved, not just the new
  file. A reorganized structure owes its reason in a sentence.

## Content guardrails (this repo is public)

- **Money stays vague. Always.** Never publish specific salary/pay numbers or exact ratios. Make the
  *point* that teaching pays a fraction of his day job in relative terms ("a sliver of what my day job
  pays," "the hourly math is a joke"), never with figures.
- **Neutral, no names, lessons-forward** for anything sensitive. Company name is **Career Team**.
  People name-drops = public professional info + LinkedIn only. Student data, private course content,
  and internal project internals never appear. See [[portfolio-content-backlog-guardrails]].

## The honesty clause (non-negotiable)

Never claim a benefit you have not shown. If something is a hypothesis, say so. If a trade-off hurts,
name it. If a number is a snapshot, flag it. This is the load-bearing wall of the whole voice: it's
*why* the confident parts are believable. See the whitepaper's §8 and the origin story's "what I have
not earned yet."

## Structure of a typical piece

A repertoire, not a template; don't hit every beat every time (see the formula tell). **This is the
shape of a personal note.** A piece written for a company follows a different one, and the two are
set out side by side in [NOTE-STANDARD.md](NOTE-STANDARD.md) under *Two kinds of note*. Drafting a
guide to the beats below is how a company-facing piece turns into a memoir with a plan attached.

1. Confessional / stakes-first open (rotate: sometimes a number, sometimes the pull-quote, sometimes mid-problem).
2. The problem, made concrete with real specifics.
3. The turn: "here is what changed."
4. The build/argument, opinionated, with the *why* behind each choice.
5. The honest limits: what is not yet proven.
6. Callback close that returns to the opening image.
7. Sign-off boilerplate.

## Rationalizations: what talks a session out of this file

Every one of these has been used, and every one of them sounds reasonable at the moment it is thought.

| Rationalization | Reality |
|---|---|
| "It's internal, nobody reads it." | Internal prose becomes published prose more often than anyone plans for. The README written in a hurry is the one people land on. |
| "It's a draft, I'll do the voice later." | Later means sanding a machine-flat draft, and the calibration pair below says start over rather than sand. Voice is cheaper written than retrofitted. |
| "It's only a commit message." | Commit messages ship. The next session reads them, the log keeps them, and anyone auditing how the work was done reads them first. |
| "I already know the voice." | The things most often missed are not the vibe, they are mechanical: a backtick, an em-dash, a tidy triad, a bare credential. Knowing the voice does not catch those. |
| "The em-dash genuinely reads better here." | It is the loudest tell in the set, and the sentence has always survived a comma, a colon, or a rewrite. This file reversed its own earlier stance on exactly this point, so the bar for keeping one is high. |
| "There's no real foible to joke about here." | Then skip the joke, because a manufactured wink is the worse tell. But look first: "no foible available" is usually "I did not look." |
| "The prose is clean, so it's fine." | Clean, correct, and forgettable is the definition of the failure, not the pass. |
| "The linter came back green." | It covers the mechanical half by design. Green means nothing was misspelled in the machine's accent; it says nothing about whether the piece is his. |

## Red flags: in how the session is working, not just how the prose reads

The smell test below catches bad sentences. These catch a bad process, which is what produces them.

- The whole piece was drafted before this file was opened.
- A machine-flat passage is being sanded sentence by sentence instead of rewritten from the stake.
- Every paragraph is about the same length.
- A metaphor arrived that is not in the bank and is not something you could point at in a room.
- A specific was invented to fill a slot ("a modern font," "a recent project") instead of pulled from the specifics bank.
- Every signature move got used in one piece: the confession, the wink, the tricolon, the piano, the callback close.
- A number went in without anyone asking whether it is a snapshot.
- A credential is standing on its own with no cost attached to it.
- The AI's involvement got softened, hedged, or quietly left out.
- The draft argues against a row in the opinion stack, and it reads well, so it stayed.
- His own blunt sentence came back more writerly than he wrote it.

## Verification (before it ships under his name)

Mechanical and evidence-shaped, so it can be checked rather than felt. The judgment pass is the
smell test below, and one of these lines is "you actually ran it."

- [ ] `bun run lint:voice` run, its output read, zero TELLs. Warns triaged, not ignored by default.
- [ ] The smell test below run by a person, line by line, not inferred from the prose reading fine.
- [ ] Every number in the piece either confirmed as standing or flagged in the text as a snapshot.
- [ ] Every specific is a real name from the specifics bank, with no invented placeholder left in.
- [ ] Every claimed benefit is either shown, or labelled a hypothesis in the sentence that makes it.
- [ ] For a note: frontmatter complete, at least one rendered figure, the exact sign-off footer
      present (all three per [`NOTE-STANDARD.md`](NOTE-STANDARD.md), which owns the artifact).
- [ ] Money stays vague, no student data, company spelled "Career Team".

**Detection is naming, not scoring.** When the job is judging whether a piece is off-voice (an audit,
a review, a lint triage), the output is a named pattern, the line it sits on, and the fix. Never a
percentage, never a grade, and never a claim about whether a machine wrote it. A detector guesses; a
named pattern is evidence someone else can check and argue with, which is the same reason an audit
finding carries a file and a line. That is also the honest limit on `bun run lint:voice`: it reports
which rule matched where, and it holds no opinion at all on how the piece reads.

## The off-voice smell test

Fast pass before anything ships under his name. If a line trips any of these, fix it. The purely
mechanical rows (backticks, em-dashes, the word-tells, the not-just-X shape, eager sign-offs,
nominalizations, and four of the borrowed shapes: the superficial-analysis clause, the faux-insight
setup, importance puffery, interpretive metadiscourse) can be caught by a linter before the human
pass, the portfolio ships one as `bun run lint:voice`. It covers only the mechanical half by design;
the judgment rows below (the missing wink, a bare credential, a benefit not shown, the formula tell,
the portability test, synonym cycling) stay a human read. The colon reveal belongs with them rather
than with the linter, and that is a measured result and not a preference: the shape is a *fragment*
before the colon, separating a fragment from a clause needs a parser, and the regex written for it
flagged 318 lines of this repo where the sampled ones were ordinary sentence colons. Ten times zero:
the linter multiplies the eye, it does not replace it.

- [ ] **A backtick in prose.** The number-one machine tell. (Code blocks + reference docs exempt.)
- [ ] **An em-dash.** Now a top machine tell too. Rewrite with a comma, period, colon, or parentheses.
- [ ] **The "it's not just X, it's Y" shape**, an eager sign-off, or anything from *Do not sound like the machine*.
- [ ] **A vague placeholder where a real name goes.** *"A modern font"* → *Redaction.* *"AI tooling"* → *Claude.*
- [ ] **A bare credential.** A title or achievement standing alone reads as a boast. Attach its cost,
  its unglamorous reality, or the reason the reader needs it. Mileage, not medals.
- [ ] **Buttoned-up all the way through.** If the whole piece is earnest, a wink is probably missing, but only a *real* one, pointing at a flaw he actually has. No real foible on hand? Skip the joke; a manufactured wink is a worse tell than an earnest paragraph.
- [ ] **A corporate verb.** *leverage, utilize, empower, unlock, seamless.* Delete on sight.
- [ ] **A nominalization.** *perform an analysis, provide a solution, make use of.* Collapse to the verb: *analyze, solve, use.*
- [ ] **A benefit claimed but not shown.** Hypothesis? Say so.
- [ ] **A specific number stated as permanent** when it's a snapshot. Flag it.
- [ ] **Throat-clearing.** *"In today's fast-paced world…"* / *"It's worth noting that…"* Cut to the real thing.
- [ ] **The reader reaches the reasoning before the ask.** Front what they do, fold what proves it, and check that no hedge went into the fold with it. See *What a reader meets first*.
- [ ] **The AI use hedged or buried.** It's a badge, not a confession. Fly it.
- [ ] **A thesis-first open** instead of a stakes-first one. Lead human; argue after.
- [ ] **A dollar figure or exact ratio.** Money stays vague, always.
- [ ] **A colon reveal.** *"The part that makes it work: it grades itself."* Rewrite as a plain sentence.
- [ ] **A trailing *-ing* clause explaining what a fact means.** *"…, highlighting the commitment to…"* Give the consequence instead.
- [ ] **A faux-insight setup.** *"What nobody tells you…"* Cut it; the claim is stronger alone.
- [ ] **A sentence that survives being moved to another company.** The portability test. Replace it with something only true here.
- [ ] **The reader being told what to notice.** *"This distinction matters."* Show it, or cut it.
- [ ] **Three names for one thing.** *agent / assistant / tool.* Pick one and repeat it.

## Calibration pair: same facts, two writers

Same content: the token playground demo.

**Machine-flat (every tell, annotated):**

> In today's rapidly evolving AI landscape, I'm excited to showcase a new feature of my design system
> documentation site. It's not just a component catalog — it's a fully interactive experience. Users
> can leverage an AI assistant to seamlessly adjust design tokens, and the system exports a robust CSS
> override. I hope you'll find it as game-changing as I do!

Throat-clearing opener, *landscape*, *showcase*, the not-just-X shape, *leverage*, *seamlessly*,
*robust*, *game-changing*, eager sign-off. Clean, correct, forgettable, could be anyone announcing
anything.

**His:**

> Here's the part of the docs site I can't stop showing people. You type "make it warmer and more
> compact," and the AI reaches over and moves the same sliders you would. Not an API wearing a trench
> coat. The actual sliders. I'll be honest about the seams: the model is small, it runs in your
> browser, and it fumbles the weird prompts more than I'd like. But when it lands, you're watching its
> hands on the same piano. That was the whole point.

Stakes-first, real specifics, the trench-coat wink at the *idea's* expense, an honest limit stated
plainly, short sentences doing the landing, callback to the piano. Nothing in it could have been
written about someone else's project.

When drafting, hold the output against this pair. If it's closer to the first one, start over: don't
sand it.

## Raw vs. finished: keep the bluntness

His *unpolished* writing is blunter, faster, and less literary than the finished notes: short
declaratives, relentless forward momentum, folk-plain causation (*I chose it cause…*), catastrophes
told in three flat words. The finished drafts read more measured because they were edited, and the
real risk in that editing is *upgrading* his bluntness into literary polish, sanding a plain true
sentence into a pretty smooth one. When polishing his raw material, keep the plainness. A blunt
sentence in his own register beats an elegant one in the house style. If the finished version sounds
more writerly than he does, you overcooked it. The finished exemplars are a ceiling for craft, not a
license to out-write him.

---

*This guide is a projection of how Tjakoen already writes. Update it when the voice evolves, not the
other way around. Written the way he'd want it: real names, honest limits, and no backticks except
where a literal token has to be exact.*