Add ponytail-keep: marker for code that only looks over-complicated

[franciscoxc]

The gap

ponytail: marks a deliberate shortcut with a known ceiling, so reading one invites the upgrade. There is no marker for the opposite case: code that reached its shape after several rounds against a bug or a platform limit, and now reads like arbitrary complexity because the obvious version silently fails.

That gap isn't neutral in a skill whose whole reflex is "delete what doesn't earn its keep". And marking such code with ponytail: actively makes it worse — the next pass reads it as debt and "upgrades" the bug back in.

The proposal

ponytail-keep: — same vocabulary, inverse semantics:

Marker	Means	On reading it
ponytail:	Deliberate shortcut, known ceiling	Upgrade it when the ceiling bites
ponytail-keep:	Looks complicated, is the only thing that works	Reproduce the symptom before touching it

Two details that make it work rather than become decoration:

It names the symptom, not the rule. // ponytail-keep: with canvasContext the promise never resolves stays verifiable years later — you can check in a minute whether the library fixed it, and simplify with grounds if so. A bare "don't change this" is unfalsifiable and ages into cargo cult.

It fires at a moment, not on a judgement call. "A fix that took more than one attempt is unfinished without its marker" — deliberately shaped like the rule the skill already enforces for tests, because "unfinished" is what turns an extra into part of the job. Without that anchor the rule describes a state ("code that looks complicated"), and states get skipped: the moment the bug finally stops is exactly when relief carries you to the next thing. It also has to be written while the failed attempts are still in context — an hour later you remember the fix but not the symptom, and the symptom is the only part that stays verifiable.

Placement is load-bearing. On the line directly above the odd line, never in a file header. An agent that greps one line and replaces it never pulls a header comment into context; an adjacent one has to be included in the string being replaced. Corollary worth stating: a full-file rewrite drops these silently, which is the nastiest failure mode.

Where it came from

Real cases from a Cloudflare Pages + pdf.js project, all of which read as gratuitous complexity without the note:

// ponytail-keep: pdf.js 6 wants the canvas, not the context. With `canvasContext`
// the promise never resolves and the conversion hangs with no error.
// ponytail-keep: no `capture` on purpose. With the attribute, iOS opens the camera
// directly and you lose "Scan Documents", which is what crops and deskews the page.

That second one is the clearest case for the marker: capture="environment" is literally the attribute designed for photo inputs, so removing it looks like an oversight. It's a matter of time before someone "fixes" it and breaks scanning for every iPhone user.

Scope

• Both sources: skills/ponytail/SKILL.md and AGENTS.md
• The seven adapter copies, propagated so check-rule-copies.js passes
• skills/ponytail-debt/SKILL.md: notes that the colon in the existing grep is what separates them, so the ledger stays clean — no change to the pattern needed
• check-rule-copies.js: pinned as an invariant, so a future reword can't drop it silently
• .openclaw/ regenerated with scripts/build-openclaw-skills.js
• All three READMEs: the command table already documents ponytail: via /ponytail-debt, so a reader who never opens the skill file wouldn't learn the second marker exists

15 lines added, nothing removed.

Tests

check-rule-copies.js passes with all 10 invariants. Full suite has one failure, csv: correct pandas one-liner passes, which fails identically on the base commit on this machine (no pandas installed) — unrelated to this change.

One thing that needs your eyes

The Korean README paragraph was written by someone who doesn't read Korean. It mirrors the English and Spanish ones and carries an HTML comment saying exactly that, asking for review. Leaving README.ko.md alone would have left the translations out of sync; shipping an unreviewable paragraph silently seemed worse than flagging it. Reword or drop it as you see fit.

Open to bikeshedding

The name. ponytail-keep: reuses the project's vocabulary and I verified the debt grep ignores it, but ponytail-why: or ponytail-fought: would work as well.

🤖 Generated with Claude Code