crashtestdev/.amplifier/VOICE.md

# Writing Voice Framework & Profile

## Part I: The Framework -- Dimensions of Writing Voice

Writing voice is not a single thing. It's a composite of independent dimensions
that each writer dials differently, and that shift depending on what the writing
is *for*. Generic "tone guidelines" flatten this into "professional but friendly"
-- which is exactly how you get AI slop. Real voice has texture because the
dimensions interact in unexpected ways.

### Person-Stable Dimensions (the writer's fingerprint)

These are relatively constant across everything a person writes. They're the
dimensions that make you recognize someone's writing even without a byline.

**1. Conviction Posture**
How strongly opinions are held and expressed. Ranges from constant hedging
("it might be worth considering...") to full-throat assertion ("this is wrong
and here's why"). Most writers have a resting conviction level that shifts
only under specific pressure.

**2. Intellectual Posture**
The relationship the writer assumes with the reader. Not "reading level" --
it's deeper than that. Options:
- Teaching-down: "Let me explain..."
- Peer-to-peer: "You've probably seen this..."
- Thinking-aloud: "I wonder if..."
- Diagnostic: "The issue here is that..."

Most people have a default. The best writers shift fluidly but have a home base.

**3. Warmth Gradient**
How much the writer acknowledges the reader as a person. "We" vs "one." Asides
about shared struggles vs pure information delivery. Humor is related but
separate -- warmth is about inclusion, humor is about surprise.

**4. Humor Register**
Not "funny or not" -- the *type* of humor. Options:
- Deadpan understatement ("This is fine.")
- Playful escalation ("MOAR!")
- Self-deprecating ("I'm keeping this strange little name")
- Dry observation ("your application starts to look like a sideways mountain")
- Absurdist aside
- None / earnest

**5. Sentence Architecture**
Not just "short vs long" -- the *rhythm*. Some writers build momentum through
increasingly complex sentences that cascade. Others alternate: short punch.
Then the explanation. Some embed parenthetical asides (like this) constantly.
Others never interrupt themselves.

**6. Evidence Instinct**
When making a claim, does the writer reach for:
- Show receipts (links to PRs, npm packages, flame graphs)
- Argument from principle ("the separation of concerns demands...")
- Personal experience ("at work, we found...")
- Authority citation ("as John-David Dalton told me")
- Code that proves the point

This is deeply habitual. Receipt-showers always show receipts. Principle-
arguers always argue from principle. The instinct persists even when the other
approach would serve better.

### Purpose-Shifting Dimensions (changes with the writing)

These dimensions move depending on what the piece is trying to do. A tutorial
and a rant by the same person will differ here while maintaining the same
fingerprint above.

**7. Information Density**
How much per paragraph. Tutorials are sparse -- one concept, one example,
breathe. Technical deep-dives are dense -- three insights per paragraph,
assumes you're keeping up. Manifestos are medium -- big ideas with space
to land.

**8. Formality Register**
Casual first-person ("I found this bug") vs. detached ("the bug was
identified") vs. conversational-authoritative ("What if I told you your
Webpack is doing too much work all this time?"). This shifts with audience
and publication context more than anything else.

**9. Narrative Engine**
What structural device drives the piece forward:
- Problem/solution linear (tutorial mode)
- Problem/enemies (naming adversaries, then defeating them)
- Mystery/reveal ("here's what nobody realizes...")
- Chronological journey ("first we tried X, then Y")
- Argument/counterargument (essay mode)

**10. Reader Model**
Who the writer imagines reading this. Not demographics -- *competence
assumptions*. "You've probably used Webpack" is very different from "Webpack
is a build tool that..." This shifts with purpose but tends to cluster: some
writers always assume competence, others always explain.

---

## Part II: Ken's Voice Profile

### Sources Analyzed

- Blog post: "Localize React without Bloating the Bundle" (2019)
- Blog post: "Speeding Up Webpack Typescript Incremental Builds by 7x" (2019)
- 10+ Amplifier session transcripts (2025-2026)
- Agent delegation instructions and bug reports

### The Fingerprint (Person-Stable)

**Conviction: High, earned**
Ken states opinions as conclusions from experience, not as positions to defend.
"I believe that localization is difficult because it requires excellence in
several pieces of a stack at the same time." This isn't hedging and it isn't
posturing -- it's someone who has done the work and is reporting what they found.
He doesn't say "in my humble opinion" and he doesn't say "anyone who disagrees
is wrong." He says "here's what I found" and trusts you to evaluate it.

In sessions: "I don't want generic voice or ai slop" -- direct rejection
without explanation. He knows what he doesn't want and says so plainly.

**Intellectual Posture: Diagnostic peer**
Ken's default mode is the diagnostician. "The issue here is that Webpack 4
gave toJson a lot more information, but it also regressed the performance
tremendously as a result." He's not teaching you what Webpack is. He's not
wondering aloud what the problem might be. He identified the issue, he's
telling you what he found, and he's trusting you to follow.

The peer part shows in his use of "you" -- not pedagogical ("now you'll
want to") but collaborative ("you would recognize three separate phases").
He treats the reader as someone who would recognize the same thing he did
if they looked at the same data.

**Warmth: Present but understated**
Not effusive. Not cold. Shows up as:
- "Not everyone is as fortunate" (acknowledging others' situations)
- "Let's polish this a little bit" (inclusive, understated scope)
- "Don't worry! It is only one HOC for the entire app" (quick reassurance)
- "Let's name some enemies" (inviting the reader into the hunt)

He warms up through inclusion, not through sentiment.

**Humor: Playful escalation + dry observation**
Two distinct modes that alternate:
- Playful: "why should we humans not demand MOAR? Yes, MOAR speed!!!"
- Dry: "your application starts to look like a sideways mountain"
- Self-aware: "I'm keeping this strange little name until React.createResource()
  becomes a thing maybe in the future"

The humor is never mean, never forced, and never the point. It's a pressure
release valve in otherwise dense technical content. It signals: "I'm a person,
and this should be fun."

**Sentence Architecture: Staccato with cascading explanations**
Short declarative opener. Then a longer sentence that unpacks it. Then evidence.
Then another short sentence that re-anchors.

Example rhythm:
> "This is the big one -- it brought our incremental speeds from 30s to around
> 15s."

One sentence. The claim, the proof, the dash-connected aside. No preamble.

In sessions, even more compressed: "look at [URL] and get me a bundle.md that
includes this thing." Subject, verb, object. Done.

**Evidence Instinct: Receipt-shower**
Ken links to PRs, npm packages, GitHub issues, repos. Every claim comes with
a URL or a code block. "Here's the bug: [link]". "I've published a temporary
fork: [link]". "I've created a repo to demonstrate: [link]".

This extends to sessions: he provides URLs, file paths, device contexts,
exact reproduction steps. He doesn't argue from principle -- he shows you
what he's looking at.

### The Shifts (Purpose-Dependent)

**Blog posts: Enemy-narrative diagnostic**
Both existing posts follow the same engine:
1. Hook that frames the stakes ("What if I told you...")
2. List the enemies or stages (numbered, named, personified)
3. Diagnose each one with specific evidence
4. Show the fix with code
5. Quantify the improvement
6. Brief, personality-forward closing

This is the "war story" structure. Not tutorial, not essay, not rant.
It's "here's what we fought and here's how we won." This works for
the type of content Ken writes -- performance work, tooling decisions,
infrastructure choices -- where the narrative *is* the investigation.

**Sessions: Compressed intent + layered iteration**
In conversation, Ken is extremely compressed. "get me a bundle.md that
includes this thing." No context dump, no over-specification. He trusts
the agent to figure out what "this thing" means from the URL he provided.

When the first pass isn't right, he layers: "well, I'm also going to
need..." "I can confirm that..." "Maybe we should have..." Each message
adds one thing. He doesn't try to specify everything upfront.

**Bug reports: Empirical, multi-observation**
"I can confirm the scrolling doesn't work" -- starts with validation.
Then lists 3-4 related observations in one breath, each with device
context. Then proposes a fix direction. Then adds "also the icons..."
as an afterthought. The bug report is a stream of observations, not
a structured ticket.

### Anti-Patterns (What Sounds Unlike Ken)

- Opening with "In this blog post, we will explore..." (generic framing)
- "It is important to note that..." (filler hedging)
- Explaining things the reader already knows (underestimating audience)
- Excessive qualification ("arguably," "potentially," "it could be said")
- Missing the receipts (claims without links, code, or data)
- Corporate-neutral voice ("we are excited to announce...")
- Ending with a generic summary that restates the intro
- Emoji-heavy prose
- Bullet-point listicles without connective narrative

### The Voice in One Paragraph

Ken writes like a senior engineer at a whiteboard -- he draws the architecture,
points at the problem, shows you the profiler output, and says "see this? that's
what's killing us." He assumes you know what a flame graph is. He names his
problems like enemies in a video game. He shows receipts for every claim -- PRs,
packages, repos, reproduction steps. When the fix works, he tells you the number.
When he's excited, he says MOAR. When he's done, he stops. The writing has
momentum because every sentence either identifies a problem, shows evidence, or
delivers a fix. Nothing exists to fill space.

---

## Part III: Voice Application Rules

### For Writing New Content

1. **Open with the problem or the hook, not the topic.** Not "Today I want to
   talk about caching." Instead: "Our cache was lying to us and we didn't know
   it for six months."

2. **Name the enemies.** Give problems identities. "Enemy #1: stats.toJson"
   is more memorable than "Issue 1: Performance regression in statistics
   serialization."

3. **Show the receipt immediately after the claim.** Claim, then code block
   or link. Not claim, then three paragraphs of context, then evidence.

4. **Assume competence.** Don't explain what React is. Don't explain what
   a build tool does. The reader is a peer who happens to not have looked
   at this particular problem yet.

5. **Quantify the win.** "This brought us from 30s to 15s." Not "this
   significantly improved performance."

6. **One aside per section, max.** The humor and personality live in the
   asides -- "MOAR!", "sideways mountain", "strange little name." But they
   work because they're rare. Two per section and it becomes a comedy act.

7. **End when you're done.** No summary paragraph restating everything.
   No "in conclusion." The last section's fix or the closing thought IS
   the ending.

### For AI-Assisted Writing

When using an AI to draft or extend content in Ken's voice:

- Feed the AI the specific problem, the evidence (links, data, code), and
  the conclusion. Let it connect them. Don't ask it to "write a blog post
  about X" -- that's how you get slop.
- Review for conviction. If the draft says "might," "could," "arguably" --
  those are almost always wrong. Ken knows what he found. State it.
- Check the evidence instinct. Every paragraph should either set up a claim
  or pay it off with proof. If a paragraph does neither, cut it.
- The humor should feel accidental. If it feels constructed, remove it.
  Ken's humor works because it reads like something that slipped out while
  he was genuinely excited.

### For Text-to-Speech

The voice should match the writing's energy:
- Not radio-announcer smooth. Slightly conversational.
- Pauses before evidence blocks (where a reader would shift their eyes to code).
- Slightly faster on the enthusiasm moments ("MOAR speed!!!").
- The read-aloud version should be a *summary narration*, not verbatim -- the
  masterclass site does this well. A spoken version of a code-heavy post needs
  to describe what the code does rather than read variable names.

---

## Part IV: Dimensions Quick Reference

For any new piece of writing, calibrate these:

| Dimension | Ken's Default | Adjustable Range |
|-----------|--------------|-----------------|
| Conviction | High, earned | Never hedge to hedge. Soften only when genuinely uncertain |
| Intellectual posture | Diagnostic peer | Can shift to thinking-aloud for exploratory posts |
| Warmth | Understated inclusion | Can increase for community-facing pieces |
| Humor | Playful + dry, sparse | Turn down for pure reference docs, never turn up past current level |
| Sentence architecture | Short/long alternation | Longer cascades OK for narrative pieces |
| Evidence instinct | Show receipts | Always. Non-negotiable |
| Density | Medium-high | Lower for tutorials, higher for deep-dives |
| Formality | Conversational-authoritative | Never corporate-neutral |
| Narrative engine | Enemy-narrative diagnostic | Can use mystery/reveal or journey for different content |
| Reader model | Assumes competence | Only lower for explicit beginner content, and even then, only slightly |