When agent-instruction docs drift from upstream spec
· 7 min read
A few days ago helmdeck shipped a hardening pass on its hyperframes.compose pack — the one that asks an LLM to write the HTML/CSS/JS for an animated video composition, then hands the result to a renderer. Part of that pass was a brand new "best practices" guide at docs/reference/packs/hyperframes/best-practices.md. The pack's tier-aware system prompt referenced it from the prompt itself: "for richer guidance on visual hierarchy, pacing, type-on-screen rules, color choices, and the GSAP transition patterns that play well with HyperFrames, see the best-practices guide at <URL>."
The doc covered:
- Timeline coverage (visible to the operator as the blank-screen bug we'd just closed)
- "One focal element per ~3 seconds"
- Minimum font size of ~60px at 1080p
- Minimum read time of 1.5 seconds
- A "3-second rule" for visual change
- "No more than 2 elements animating simultaneously"
- A 3-5 color palette ceiling
- GSAP transition patterns
It read authoritatively. It made specific numeric claims. Tier A/B models would fetch it and use it as a reference.
It was almost entirely made up.