Make an AI-written guide prove it can be built→
An AI-written how-to is only useful if a stranger can implement it. This release turns that expectation into a handoff, a local trial, and evidence bound to the exact guide that was reviewed.
Field notes · No. 022
Dev log
Senior DevOps Engineer building in public. Shipped features across Local Fitness, Ghostwriter, and more — the tradeoffs behind them, and what broke.
Prove the intended page was built and is actually being served→
Build a complete source-to-route check and a bounded HTTP poller that rejects fallback pages, old revisions, redirects and hanging responses.
Some quality rules only exist across a set→
Every generated image passed review on its own and the set still looked like one template. Here is how to measure a property that no single artifact can violate, and gate on it.
Your README is one directory too high→
npm always ships your README, right up until your repo layout puts it one level above the package directory. Here is how to stage docs at pack time, and the part of this that I could not fix.
The test that passed while checking nothing→
A regression gate built from work you already shipped is only worth having if you prove it can fail. Here is how to build one, and how to check it isn't quietly asserting nothing.
Auditing an AI skill against its own past runs→
Version 0.11.0 of this skill came entirely out of one exercise: asking the model to review the skill's own previous six runs. Here is the four-lens audit loop that produced it, and what the round cost in tokens.
Folding a content repo into the site repo without breaking idempotent publishing→
Moving generated content into a subfolder of the site repo turns every publish push into a deploy. The catch: your publisher's already-published check is full of path assumptions, and missing one silently re-plans your entire archive.
Enforcing a layout contract on AI-drawn images with a DOM geometry gate→
Style-guide prose can ask an agent to draw inside a box; it can't make it happen. How to measure the rendered DOM in headless Chromium and refuse to rasterize any composition that breaks the layout contract.
Encoding the fix into the skill, not just the code: how one agent session backfilled 49 cover images→
devlog v0.8.1 fixed bland, repetitive cover images, but the fix that stuck wasn't in the render code. It was a line added to the skill's own instructions and a machine-checked invariant, which is what let one Claude Code session regenerate all 49 backfilled covers in parallel and get them right the second time.
Turn a Markdown writing contract into a parser-backed check→
Build a complete Markdown structure linter with real section parsing, distinct bibliography links, body citation checks and CLI exit statuses, without pretending it verifies facts or executes examples.
When three releases land on one day, date alone can't sort your feed→
My dev-log feed sorted newest-first by date, which worked until the day I cut three releases before dinner and the newest one rendered at the bottom. The fix is a two-key comparator: date first, version as the tie-break, with the version segments compared as numbers. Here's how to build one that survives v0.10.0.
Give your CLI an import-safe entrypoint→
Separate reusable logic from command-line side effects, preserve existing entrypoints, and test the invocation path that package users actually reach.
Give the agent a plan, not a shell→
I rebuilt this dev log's skill so the LLM stops running twenty hand-rolled bash steps and starts consuming one JSON plan from a tested CLI. Here's the pattern: put everything deterministic in code you can test, and put everything non-deterministic behind a lint gate and a budget-capped judge.
The fallback that pointed at a directory that never existed→
devlog's voice-profile fallback pointed at a path its sibling tool never actually used, so the fallback could never fire and nothing ever errored. A small patch, and a useful lesson about tools that share files by convention.
Building a Claude Code plugin marketplace that survives its own release pipeline→
A plugin marketplace's skill-discovery rule lives entirely in a directory shape, not a manifest field, so it has to be built, lint-checked, and released against that same shape. Here's how to do all three without a CI job that lies to you.
Turning 'cite your sources' into a contract an agent can't quietly ignore→
devlog 0.4.0 rewrote the instructions behind /devlog so every release post has to become a researched, cited implementation guide. The instructions alone don't guarantee it happens, so here's how to turn a soft citation ask into a structured contract and a checker that catches it when the model doesn't comply.
Give your CLI script two lives: a program and a module→
devlog's v0.3.1 test suite needed bin/devlog.js's logic importable without also running its command-line dispatch. Here's the guard pattern that split the two, and the symlink trap that broke it again a few weeks later.
What it takes to treat a git tag as untrusted input→
Separate a Git ref from its validated version and captured commit, then publish one complete release file without an existence-check race.
Filtering a monorepo's git log without trusting the filter→
v0.2.0 let one devlog config serve several projects out of a shared monorepo. Getting there safely is a short lesson in two habits: scoping git history correctly, and treating any value headed for a shell command as input you don't trust yet.
A bare onClick isn't a button: making a shared React toggle keyboard-accessible→
The drop-in React component that renders a dev-log feed toggled each entry with a plain onClick, so every site that copied it inherited a feed keyboard and screen-reader users couldn't operate. Here's how to rebuild that toggle as a real ARIA disclosure control, and the test that proves the keyboard path works.
Turning a personal script into a one-command npx installer→
Making a working personal tool installable by a stranger means declaring a real executable, prompting for defaults instead of demanding a config edit, and verifying the tarball before you trust a publish. Here's what that took, including the two ways npm quietly rejected the first attempt.
