ergopti: Skill for Claude Code

Rewriting a tracked file with a script

A scripted rewrite is the right tool past a few dozen edits. It is also how a whole file gets silently corrupted in one command, so the discipline below is not optional. Every rule here comes from a rewrite that went wrong in this repo.

Never match by line number

Line numbers drift the moment anything above them changes — including your own earlier edits in the same session, and including a concurrent branch merge. Anchor on something stable: a heading, a function signature, a unique marker.

The corollary: if you plan the edit from an agent's report, that report's line numbers are already stale by the time you apply it. Re-derive them, or match on text.

Dry-run first, and make the dry-run informative

The script should be able to run without writing, and print enough to be judged: how many units it matched, how many it will change, how many it did not recognise, and the resulting size. An unmatched unit is the interesting number — it usually means the matcher is broken, not that the file is unusual.

Default unmatched units to keep unchanged. A matcher bug should cost you a missed improvement, never a deletion.

Refuse to write on detected corruption

Put the check inside the script, not in your head:

const mojibake = (result.match(/â€/g) || []).length;
if (mojibake > 0) {
	console.error(`REFUSING TO WRITE: ${mojibake} mojibake sequence(s)`);
	process.exit(1);
}

This exact guard exists because a rewrite of docs/PROJECT_MEMORY.md shipped 212 mojibake sequences into the canonical memory. The corruption entered upstream — the replacement blocks had been extracted with Get-Content without -Encoding UTF8, which decodes as ANSI on PowerShell 5.1 — and the write step copied it faithfully. A rewrite is only as clean as the data you feed it: check the input, then check the output.

Enforce the repository's LF contract

Normalize source text before matching and write LF, as declared by .gitattributes: