No Scripts for Frontmatter Edits

One wrong line in a script becomes a thousand broken docs, and every site and vault that reads them breaks at once. Agents edit by hand.

Path
reminders/No-Scripts-for-Frontmatter-Edits.md
Authors
Michael Staton
Augmented with
Claude Code on Claude Opus 5.5 (1M context)
Tags
Reminder · Tree-Wide · Frontmatter · Normalization-Sweep · Guardrail

No Scripts for Frontmatter Edits

When you need to change frontmatter on more than one doc, don’t write a script for it. Brief an agent to open each doc, read it, and edit it by hand.

Why

Small errors in a script become huge errors downstream. Astro, Obsidian, and every other tool that reads these docs process them as a set: content collections, roll-ups, ingesters, the publisher. A script repeats its one mistake on every file it touches, so a bad regex, an unquoted colon, or a YAML library re-serializing a block doesn’t break one doc. It breaks the build, the vault, or the publish for all of them, and the damage is spread across hundreds of diffs nobody will read.

An agent editing by hand fails differently: one doc at a time, visibly, and it sees what it’s editing. A multi-line lede: that a parser would flatten, a key a script didn’t know about, a value that only makes sense once you read the doc: the hand edit notices; the script doesn’t.

What’s allowed

  • Reading, by any means. Inventories, the survey scan, grep, git log for dates, uuidgen and /dev/urandom for IDs the agent then pastes in.
  • Verifying, by any means. A read-only scan after the edits, and the agent reading its own git diff in full.
  • Editing, by hand only. The Edit tool, one doc at a time, frontmatter lines only.

A large sweep is parallel agents, one per repo, each editing by hand. Slower than a script; much cheaper than repairing a tree.

What this doesn’t cover

Tools that already exist and copy docs without rewriting them (refresh-corpus.sh, pnpm rollup:sync) aren’t frontmatter edits. Generated files nobody hand-authors (survey.json, build output) aren’t either.

The stronger version

This reminder only works if it’s loaded when the mistake is about to happen. If it keeps getting missed, make it a hook: a Claude Code PreToolUse check on Bash that refuses in-place writes (sed -i, perl -i, redirection, python/node scripts) aimed at *.md under context-v/ or changelog/.

  • [[Check-The-Substrate-Before-Reasoning-On-Top-Of-It]]
  • ai-labs/context-vigilance-kit/context-v/plans/Retrofit-Every-Repo-to-OKF-Then-the-Kit-Frontmatter.md (decision 8)
  • context-vigilance skill: references/frontmatter-spec.md, the directed-sweep rules