Writing a kolu blog post

A kolu blog post is a first-person engineering essay grounded in what actually happened when something was built — the dead-end, the load-bearing decision, the bug that taught the lesson. Its source of truth is the Claude Code session logs that produced the work, not invented marketing copy.

Show the story, don't only tell it. A good post leans on figures over prose: a trajectory chart, before/after cards, a timeline, a flow diagram, a comparison bar, a real screenshot — visualization carrying more of the argument than text. Every figure is grounded in real data (status timestamps, ps output, measured durations); a chart is an argument, never decoration. This applies to every post, not just the obviously visual ones.

Steps

1. Locate the work's sessions. Find the Claude Code session logs behind the feature (they live under ~/.claude/projects/, one directory per working directory). Map them deterministically by tracing PRs → branches → logs, not by keyword hits.

2. Mine them for the story. Read the human/assistant narrative out of the logs and pull out the why behind decisions, the hard-won lessons and dead-ends, the concrete mechanisms, and vivid verbatim quotes. When the effort spans more than a handful of sessions, fan out with an ultracode workflow — one agent per transcript returning structured notes — then synthesize the notes into a single digest, draft from it, and run an adversarial editor pass. The digest is the fact-checked spine; never fabricate numbers, dates, quotes, or PRs.

3. Write it in the author's voice. Use the pg skill (Paul Graham voice) unless told otherwise, and settle the inline house style up front. Match the register of the existing posts; a new post often pairs as a sequel to one. Give it a non-cryptic title. The frontmatter title is a plain, self-explanatory headline that states what happened and carries the payoff — "Making Kolu's macOS e2e CI lane 14x faster", not a slug and not a clever teaser the reader can't decode until they've finished. Let the description tease the concrete hook (the 64 GB leak, the one-character typo). This is a deliberate shift from the older evocative-title posts toward titles that tell the reader up front what they'll learn — apply it to every new post. When a title stays deliberately evocative ("The spacetime of code"), give it an optional subtitle in the frontmatter — one plain line that decrypts the metaphor into what the reader will learn; it renders as a deck under the title.

4. Wire it into the site. Posts live in website/src/content/blog/ under a short, stable slug (the filename is the URL). Use the site's components for callouts, GitHub PR/issue references, and the table of contents; cite the real PRs behind each claim, and give the post a two-level heading outline so the TOC nests — write the headings as plain signposts of each section's point, not teasers, so the contents list reads as the argument in miniature. Link every technology, tool, library, format, and product on its first mention — [Playwright](https://playwright.dev/), [ffmpeg](https://ffmpeg.org/), a CDP method to its own doc page — the way the existing posts do; a named technology with no link is a miss. When content is a sequence of steps or a short enumeration (e.g. two API methods that each fail, two gotchas), use a markdown list or table instead of a dense paragraph — keep the argument in prose, but stop hiding enumerable content in paragraphs (a deliberate post-specific loosening of the pg skill's "don't replace argument with bullets" rule). When you quote something the author literally typed into an agent's CLI prompt box (Claude Code, Codex, etc.) as a turning point, render it with the Prompt component (website/src/components/Prompt.astro) — <Prompt>…</Prompt> — not a plain blockquote, so it reads as a human typing into the agent's input field; see auto-demo.mdx for the reference usage. Balance prose with screenshots and code — host images in the site, don't hotlink.

   Figures: hand-author inline SVG, theme-aware. Draw charts directly as inline <svg> in the MDX (no chart library) — see macos-e2e-lane.mdx for five reference figures. Color every stroke and fill with the site's --color-* CSS custom properties (--color-ink, --color-ink-dim, --color-ink-muted, --color-rule-strong, --color-amber, --color-live-alert, --color-live-lime, --color-void, …; the palette lives in website/src/styles/global.css) so a figure tracks light/dark automatically — never hardcode a hex value. Give each <svg> a role="img" and an aria-label describing the data it shows.

   MDX/SVG gotcha (hard-won on the macOS-lane post). Astro's MDX passes camelCase SVG presentation attributes (textAnchor, fontSize) through literally, and SVG silently ignores them — every label renders at the 16px left-anchored default. Use each attribute's real kebab-case SVG spelling: text-anchor, font-size, font-weight, font-family, stroke-width, fill-opacity. Genuinely camelCase SVG attributes like viewBox stay as-is. Eyeballing misses it — catch it by measuring getBBox() in a real browser against the built site.

5. Verify and ship. Build the site and confirm it renders, then verify every figure in both light and dark themes against the built output with the chrome-devtools MCP — confirm labels are actually placed (getBBox()), not merely present in the DOM — before opening the PR. Run only the CI lane a docs change can touch (the website build plus formatting and lint — see the ci skill).