fix: purge AI slop from judgment essay, add voice linting pipeline
- Killed 16 em-dashes (Claude fingerprint, 15.9/1000 words -> 0) - Replaced all clause-dash-elaboration patterns with periods, colons, restructuring - Removed 'The One-Sentence Version' section (restated the intro, voice anti-pattern) - Broke tricolon at lines 56-58 (too-clean parallel structure) - Collapsed 'How to Actually Help' listicle into connective prose - Added receipt link for ~100x inference cost claim - Heading dashes replaced with colons (Tradesman Analogy, Excellence vs Functional) New tooling: - scripts/lint-voice.sh: mechanical anti-slop linter (em-dashes, trigger words, hedging, filler, receipts, sentence uniformity) - .amplifier/skills/voice-check/SKILL.md: LLM-as-judge voice authenticity check (8 dimensions against VOICE.md profile) - .amplifier/AGENTS.md: standing rule requiring both checks before any publish 🤖 Generated with Amplifier Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
This commit is contained in:
Ken
@@ -0,0 +1,151 @@
|
||||
# Blog Architecture: Crash Test Dev
|
||||
|
||||
## What We're Building
|
||||
|
||||
A blog for lessons, patterns, and writing. Elegant like the Amplifier Masterclass
|
||||
site. Read-aloud feature. No AI slop. Ken's voice throughout.
|
||||
|
||||
## Reference: What the Masterclass Does Right
|
||||
|
||||
The masterclass site (anderlpz.github.io/amplifier-masterclass/) achieves its
|
||||
elegance through:
|
||||
|
||||
- **Three-font stack**: Serif body (Source Serif 4), sans headings (Inter), mono
|
||||
code (JetBrains Mono). The serif/sans pairing is the single biggest quality signal.
|
||||
- **18px base, 1.75 line-height**: Generous reading. Feels like a printed essay.
|
||||
- **Muted color palette**: Cool lavender-grey background (#F4F5F9), body text in
|
||||
secondary grey (#5C5E6E) not black, muted steel blue accent (#3E5C8A).
|
||||
- **720px reading column + 840px breakout**: Prose narrow, code/diagrams wider.
|
||||
Creates visual breathing rhythm.
|
||||
- **Pre-recorded narration**: OpenAI TTS voices (Fable, Nova, Alloy), 3 choices,
|
||||
with full transport controls, scrubber, speed selection, auto-advance.
|
||||
- **Progressive disclosure**: TOC pill, drawer, inline term definitions, xref
|
||||
hovers, scroll-driven diagram revelation.
|
||||
- **Zero framework bloat**: Hand-crafted HTML/CSS/JS. Every pixel intentional.
|
||||
|
||||
## Tech Decision: Astro
|
||||
|
||||
**Current stack (Gatsby 2)**: Dead framework. React 16. gatsby-theme-blog 1.0.
|
||||
Not worth upgrading -- better to start fresh.
|
||||
|
||||
**Recommended: Astro**
|
||||
- Same framework the masterclass uses for its component rewrite
|
||||
- Ships zero JS by default. JS only where explicitly needed (audio player, TOC)
|
||||
- Markdown/MDX content with frontmatter. Content-first architecture
|
||||
- Built-in code highlighting (Shiki), image optimization, RSS
|
||||
- Minimal deps: just astro + typescript, like the masterclass
|
||||
|
||||
**Why not Next.js/Remix**: Over-engineered for a blog. Ken's content doesn't
|
||||
need server-side rendering or API routes. Static generation + islands is the
|
||||
right fit.
|
||||
|
||||
## Design Approach
|
||||
|
||||
Inspired by the masterclass but adapted for a multi-post blog (not single-page
|
||||
document):
|
||||
|
||||
### Typography
|
||||
| Role | Font | Why |
|
||||
|------|------|-----|
|
||||
| Body prose | Lora or Source Serif 4 | Serif signals "read this slowly" |
|
||||
| Headings, UI | Inter | Clean, modern, tight tracking |
|
||||
| Code | JetBrains Mono or Berkeley Mono | Monospaced with personality |
|
||||
|
||||
### Color
|
||||
Warm variation on the masterclass palette:
|
||||
- Background: warm paper (#F4F2ED or similar) -- not cool lavender
|
||||
- Surface: white cards
|
||||
- Text: near-black (#1A1815), secondary grey for body
|
||||
- Accent: deep blue or muted violet (Ken's existing blog uses #007acc)
|
||||
- No dark mode initially (the masterclass explicitly chose this)
|
||||
|
||||
### Layout
|
||||
- 650-720px reading column, centered
|
||||
- Code blocks break wider (840-900px)
|
||||
- Generous vertical spacing between sections (64px+ for h2 breaks)
|
||||
- Fixed minimal nav at top (site title, optional TOC pill for long posts)
|
||||
|
||||
### Content Structure
|
||||
```
|
||||
/ Index -- list of posts, most recent first
|
||||
/posts/[slug] Individual post pages
|
||||
/patterns/[slug] Technical patterns (shorter, reference-style)
|
||||
/lessons/[slug] Longer lesson-format pieces
|
||||
```
|
||||
|
||||
Frontmatter:
|
||||
```yaml
|
||||
---
|
||||
title: "Speeding Up Webpack Typescript Incremental Builds by 7x"
|
||||
date: 2019-08-16
|
||||
type: post | pattern | lesson
|
||||
tags: [webpack, typescript, performance]
|
||||
audio: true # triggers TTS generation
|
||||
summary: "One-sentence hook for the index page"
|
||||
---
|
||||
```
|
||||
|
||||
## Read-Aloud Feature
|
||||
|
||||
### How the Masterclass Does It
|
||||
- Pre-generated MP3s per chapter using OpenAI TTS API
|
||||
- 3 voice options (Fable, Nova, Alloy)
|
||||
- Script files that are spoken-word summaries, NOT verbatim text reads
|
||||
- Full transport controls (play/pause, skip, scrub, speed, voice select)
|
||||
|
||||
### Our Approach
|
||||
Same pattern, adapted for blog posts:
|
||||
|
||||
1. **Generate at build time or on-demand**: For each post with `audio: true`,
|
||||
generate a narration script (spoken-word summary, not verbatim) and run
|
||||
it through OpenAI TTS.
|
||||
|
||||
2. **Narration script generation**: Use the VOICE.md profile to write
|
||||
spoken versions. Key rules from the masterclass:
|
||||
- Don't read code blocks aloud. Describe what they do.
|
||||
- Don't read URLs. Say "I've linked the PR in the post."
|
||||
- Keep the conversational energy. This should sound like Ken
|
||||
explaining it to you at a whiteboard.
|
||||
|
||||
3. **Audio player component**: Minimal pill in the nav area. Click to
|
||||
expand transport controls. Single voice initially (can add multiple
|
||||
later).
|
||||
|
||||
4. **Per-post, not per-section**: Unlike the masterclass's per-chapter
|
||||
audio, blog posts are short enough for single-track narration.
|
||||
|
||||
### TTS Pipeline
|
||||
```
|
||||
content/posts/my-post.md
|
||||
--> narration-script generator (strips code, converts to spoken prose)
|
||||
--> OpenAI TTS API (voice: "fable" or "nova")
|
||||
--> public/audio/my-post.mp3
|
||||
--> referenced in post frontmatter
|
||||
```
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Phase 1: Foundation
|
||||
- New Astro project in this repo (replace Gatsby)
|
||||
- Design tokens (CSS custom properties, no Tailwind)
|
||||
- Base layout, typography, color
|
||||
- Markdown/MDX content pipeline
|
||||
- Migrate 2 existing posts
|
||||
|
||||
### Phase 2: Polish
|
||||
- Audio player component (pill + transport)
|
||||
- Generate narration for existing posts
|
||||
- Index page design
|
||||
- Code block styling (breakout width, optional filenames)
|
||||
- RSS feed
|
||||
|
||||
### Phase 3: Content Types
|
||||
- Pattern pages (shorter, reference-style)
|
||||
- Lesson pages (longer, progressive disclosure)
|
||||
- Cross-references between related content
|
||||
|
||||
### Phase 4: Advanced
|
||||
- Scroll-synced TOC for long posts (like the masterclass)
|
||||
- Inline term definitions (if building a technical vocabulary)
|
||||
- Reading progress indicator
|
||||
- Multiple TTS voices
|
||||
Reference in New Issue
Block a user