mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-10 22:20:14 +00:00
fix(skill): w2h enforcement edits — close the 9 shirking patterns from agent debrief
After the audit-fix commit (e47bc6c6) landed clarity fixes, a real test run
revealed that the skill still got skipped at the gates that matter most.
The agent's honest debrief listed 9 distinct patterns where it judged
"deliver fast" over "verify what the skill said to verify."
This commit forces evidence at each of those gates so silent skips are no
longer possible without lying — at which point the gate fails by design.
**Patterns 1, 3, 8 — step-5-build.md**
- Pattern 1: "Read each beat HTML top-to-bottom" gate now requires a
structured evidence block per beat with quoted CSS hex codes, headline
font-size, captured asset paths, GSAP first/last events, and SFX trigger.
"I read it and it looks fine" / "the sub-agent confirmed" are not
acceptable. Snapshots are 3 frames out of 300+ in motion.
- Pattern 3: SFX timestamp computation rule. Every data-start MUST be
computed (beat-local + beat global start = global timestamp), not
estimated by eye. The agent typed `data-start="6.0"` for a storyboard
moment at 5.0s — a 1-second drift, not a rounding error.
- Pattern 8: Recurring sub-agent workarounds must be surfaced under
"Tooling issues encountered" — burying them means the next session
hits the same bug.
**Patterns 2, 6, 7, 9 — step-6-validate.md**
- Pattern 2: WCAG contrast warnings now require per-warning verification
with quoted validator output and opacity check at the sampled timestamp.
Blanket dismissal as "mostly transition-window false positives" is
explicitly forbidden.
- Pattern 6: animation-map.json check added to the DoD checklist —
runs `skills/hyperframes/scripts/animation-map.mjs` and confirms
per-beat event coverage.
- Pattern 7: Audio + motion verification is now a separate DoD item from
snapshot verification. Snapshots are silent stills; you must actually
play the preview and confirm SFX lands at storyboard timestamps within
±0.1s. CLI-only sessions must explicitly disclose this as deferred.
- Pattern 9: Honest disclosure section added — final user-facing summary
MUST end with "What I verified" and "What I did NOT verify" blocks.
"Looks great, ready to ship" with no disclosure now fails the gate.
**Patterns 4, 5 — beat-builder-guide.md**
- Pattern 4: Sub-agent FLAG protocol. Required phrasing for non-blocking
issues is concrete and actionable with line numbers. Forbidden phrasing:
"if X feels too long, you could...", "consider tweaking...", "might
want to...". Main agent must address each FLAG or write a rejection.
- Pattern 5: Spec ambiguity escalation. If the storyboard names a
transition without establishing the start state ("Row 1 transitions
blue → orange" but Row 1's initial color isn't specified), sub-agent
MUST flag it and ask for confirmation rather than guess. Picking an
interpretation silently means the build "looks fine" while diverging
from intent.
3 files changed, +170/-21 (net +149 lines of enforcement language).
Format checks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 4.7
parent
e47bc6c6db
commit
18444decde
@@ -115,6 +115,47 @@ After lint passes, snapshots are taken, and you've fixed every issue you saw —
|
||||
|
||||
So in your report, name the hex codes you used, the captured asset paths you placed, the headline `font-size`, and the GSAP timeline's last `tl.fromTo(...)` timestamp. Brief, concrete, true. If anything diverges from DESIGN.md or the storyboard, say so explicitly — the main agent can decide whether to accept the divergence or send you back to fix it. Surprises caught at this hand-off cost minutes; surprises caught at Step 6 cost iterations.
|
||||
|
||||
### FLAG protocol — required phrasing for non-blocking issues
|
||||
|
||||
When you find any of these, surface them as **FLAGS** in your report, not as conditional suggestions:
|
||||
|
||||
- Visual states that briefly look broken (empty containers, hanging elements, gap moments)
|
||||
- Spec ambiguities you had to resolve by guessing
|
||||
- Linter bugs you worked around
|
||||
- Tween values you changed from the spec because they wouldn't fit
|
||||
|
||||
**Forbidden phrasing:** "if the X feels too long, you could...", "consider tweaking Y", "might want to..."
|
||||
|
||||
**Required phrasing — concrete, actionable, with line numbers:**
|
||||
|
||||
```
|
||||
FLAG: at beat-local t=1.2s the doc card is visible but its inner content is still
|
||||
opacity 0 — a 0.4s empty-panel window.
|
||||
RECOMMENDED FIX: pull title typewriter from 1.6s → 1.4s
|
||||
in compositions/beat-5-name.html line 234.
|
||||
```
|
||||
|
||||
The main agent MUST EITHER apply each FLAG's fix OR write a one-sentence rejection with reason. Silently dropping a FLAG is a verification failure that gets caught at Step 6 (or worse, in the user's preview).
|
||||
|
||||
### Spec ambiguity — escalate, don't paper over
|
||||
|
||||
If STORYBOARD.md gives you a transition or transformation but doesn't establish the **start** state, do NOT guess. Examples of ambiguity worth flagging:
|
||||
|
||||
- "Row 1 transitions from Huly Blue to Huly Orange at 3.5s" — but Row 1's initial color isn't specified
|
||||
- "Headline grows" — but the start size isn't specified
|
||||
- "Cards slide in" — but the off-screen position isn't specified
|
||||
- "Subhead appears after the headline" — but exact timing offset isn't specified
|
||||
|
||||
**Required action:** FLAG the ambiguity in your report verbatim:
|
||||
|
||||
```
|
||||
FLAG: STORYBOARD.md beat 3 says "Row 1 transitions blue → orange at 3.5s" but
|
||||
Row 1's initial color is not specified anywhere. I interpreted Row 1 starts
|
||||
blue and tweened to orange. CONFIRM or correct.
|
||||
```
|
||||
|
||||
The main agent then confirms or corrects before Step 6 advances. Picking an interpretation silently means the build looks "fine" while diverging from intent — and the user only notices in motion.
|
||||
|
||||
---
|
||||
|
||||
## Continuous motion — the most important rule
|
||||
|
||||
Reference in New Issue
Block a user