Skip to content

docs: multi-page Prompt Guide + text corrections from validation#2109

Open
vanceingalls wants to merge 8 commits into
mainfrom
fix/prompt-guide-validation-bugs
Open

docs: multi-page Prompt Guide + text corrections from validation#2109
vanceingalls wants to merge 8 commits into
mainfrom
fix/prompt-guide-validation-bugs

Conversation

@vanceingalls

@vanceingalls vanceingalls commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Two bodies of documentation work from the prompt-guide campaign:

1. Prompt Guide expansion (7 commits)

The single guides/prompting page becomes a top-level Prompt Guide nav section with 29 pages:

  • Fundamentals — overview, prompt anatomy, 18 verified examples, the specification dial, vocabulary (keyword → render grids), iterating, rules & anti-patterns
  • Making it look good — visual specs, the six-rule motion grammar (with a measured A/B: frozen 211KB render vs alive 2.5MB), when to generate artwork, recreating references from text alone
  • By video type — product launch, explainers, code & PRs, music & slideshows, captions & talking heads, motion graphics
  • By feature — transitions, captions catalog, overlays & lower-thirds, code blocks, data & maps, VFX, rendering & output, editing existing videos, media & audio, variables & templating, runtimes & 3D, design systems

Every published prompt was validated: built exactly as written by a builder agent, passed lint/validate, rendered, and frame-checked (~40 validation builds, 100% pass; every failure became a page fix before publishing). 64 renders are embedded next to their prompts, hosted on static.heygen.ai (S3; docs/images/ stays gitignored, synced via scripts/upload-docs-images.sh). Old URL redirects: /guides/prompting → /prompting/overview.

2. Text corrections from the validation campaign

  • hyperframes-core SKILL.md — "First-pass lint gotchas": root element needs data-start="0"; initial states via gsap.fromTo, never CSS transform + tween on the same property.
  • docs/concepts/compositions.mdx — data-composition-src resolves relative to the project root, not the referencing file.
  • gsap-transforms-and-perf.md — createElementNS SVG has no reliable center pivot; draw at local (0,0) inside a positioning <g>.

Behavior fixes from the same campaign are in #2110; Tier 3 block bugs tracked in #2107.

Test plan

  • All ~40 validation builds pass lint/validate/render exactly as written
  • All 64 embedded S3 URLs verified serving (206, video/mp4)
  • docs.json parses; nav + redirect verified on local Mintlify dev server
  • Polish pass: every fact on the new pages re-verified against source code

🤖 Generated with Claude Code

@vanceingalls vanceingalls mentioned this pull request Jul 9, 2026
Merged
7 tasks
@vanceingalls vanceingalls force-pushed the fix/prompt-guide-validation-bugs branch from 40d3095 to 745168e Compare July 9, 2026 18:59
@vanceingalls vanceingalls changed the title fix(skills): resolve prompt-guide validation findings across skill pipelines docs(skills): text corrections from prompt-guide validation Jul 9, 2026
@vanceingalls vanceingalls force-pushed the fix/prompt-guide-validation-bugs branch from 745168e to 6fba438 Compare July 10, 2026 00:40
@vanceingalls vanceingalls changed the title docs(skills): text corrections from prompt-guide validation docs: multi-page Prompt Guide + text corrections from validation Jul 10, 2026
vanceingalls and others added 8 commits July 9, 2026 22:21
@vanceingalls @claude
docs(skills): text corrections from prompt-guide validation
e7a6cb0 
Documentation-only updates surfaced by the prompt-guide validation
campaign. The behavior fixes from the same campaign are in a separate
PR (pipeline fixes); Tier 3 block bugs are tracked in #2107.

- hyperframes-core SKILL.md: new "First-pass lint gotchas" subsection —
  the root composition element must carry data-start="0"
  (root_composition_missing_data_start), and initial states belong in
  gsap.fromTo, never a CSS transform paired with a GSAP tween on the
  same property (gsap_css_transform_conflict). Both were guaranteed
  first-build lint failures for agents writing compositions cold.
- media-use SKILL.md: "Weak local-model defaults" row corrected — local
  Kokoro TTS is the free default with HeyGen as the paid upsell (was
  described backwards), and bg-removal runs via the hyperframes CLI.
- docs/concepts/compositions.mdx: document that data-composition-src
  paths resolve relative to the project root, not the referencing file.
- gsap-transforms-and-perf.md: runtime-created SVG (createElementNS)
  has no reliable center pivot — draw geometry at local (0,0) inside a
  positioning <g> so scale/rotation pivot on the shape's middle.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls @claude
docs(prompting): expand prompt guide into top-level multi-page section
383dd35 
Splits guides/prompting into a Prompt Guide nav group (overview + Fundamentals
+ Making it look good, 11 pages) with a redirect from the old URL. Applies
research-validated upgrades: beat content formula, before/after prompt rewrites
with engine rationale, single-variable iteration moves, absolute-target
calibration, camera/depth/pacing vocabulary, prerequisites gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls @claude
docs(prompting): add by-video-type and by-feature prompt guide pages
816f580 
Adds 18 pages completing the Prompt Guide expansion (phases 2-4): six
video-type pages seeded by the verified example prompts, and twelve
feature pages giving prompting guidance for surfaces the docs implied
but never covered (transitions, caption styles, overlays, code blocks,
data/maps, VFX, rendering/output, editing existing videos, media/audio,
variables, runtimes/3D, design systems). All block/component/skill names
grounded against the catalog and skills; render pairing deferred.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls
docs(prompting): strip title-duplicate headings from guide pages
a5ed39d
@vanceingalls @claude
docs(prompting): validate prompts and embed renders across the guide
0aebbc2 
Runs validation builds for the primary prompt on every new feature page
(all pass lint/validate/render) and applies the fixes they surfaced:
lower-third exit-length note, block-adaptation framing on the anatomy
technique slot, code-typing per-character wording, caption-component
demo-content note, map determinism/merge-at-source notes, device-mockup
demo-UI expectation, variables img clarification. Embeds 29 unedited
renders next to their prompts (HeyGenVerse-hosted), including a
default-vs-overridden pair demonstrating variables.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls @claude
docs(prompting): serve guide renders from static.heygen.ai
702a6bb 
Moves all 28 example/validation renders to the docs' canonical media
host (s3://heygen-public via scripts/upload-docs-images.sh) and points
every embed at static.heygen.ai instead of HeyGenVerse asset URLs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls @claude
docs(prompting): polish pass — verify facts against sources, fix stal…
99ff79b 
…eness

Five-way review of the section against docs.json, catalog pages, and
skills. Fixes: stale /hyperframes-media skill row (real name /media-use)
plus missing music-to-video and slideshow workflow rows; caption
identity misattributions (keynote/documentary are scene-embedded, stomp
carries no rail); prompts violating the guide's own ambient-idle rule;
grounded keying rationale (u2net_human_seg); broken forward references;
nested-backtick code spans; brand casing and frontmatter dash
consistency throughout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls @claude
docs(prompting): complete plan — variant validation, vocab clips, wor…
2f958d1 
…ked specs, measured motion

Validates 16 more published prompts end-to-end (variants across every
video type, caption styles, overlays with proven alpha, code diff and
highlight, edit verbs against the real attribute map, a generated-avatar
talking-head through embedded-captions, a presented slideshow deck) and
fixes every prompt flaw the builds surfaced. Adds keyword-to-render
grids for the easing, camera, and marker vocabulary; two more worked
visual specs with renders; a measured before/after pair proving the
motion grammar (frozen frames vs all-alive, 211KB vs 2.5MB); before/
after render pairs on editing and generated-artwork pages; and proof
renders on the overview.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vanceingalls vanceingalls force-pushed the fix/prompt-guide-validation-bugs branch from b4005a7 to 2f958d1 Compare July 10, 2026 05:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@vanceingalls