mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
docs(prompting): approved design for novice-to-capstone guide arc
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Fable 5
parent
559dd0e659
commit
c222b1742c
@@ -0,0 +1,98 @@
|
||||
# Prompt Guide arc restructure — novice → capstone
|
||||
|
||||
Status: approved design 2026-07-22. Owner: Vance. Supersedes the _structure_ of
|
||||
`plans/prompt-guide-expansion.md` (its content and validation rule carry over unchanged).
|
||||
Lands on `fix/prompt-guide-validation-bugs`, amending PR #2109.
|
||||
|
||||
## Why
|
||||
|
||||
Reviewer feedback on the 29-page guide: it reads as a reference manual — "how to do
|
||||
specific things with prompts" — with no story in the hierarchy. The fix: restructure as a
|
||||
progression from novice to advanced where each section builds on techniques learned in the
|
||||
prior one, culminating in the most advanced artifact a reader can build with everything
|
||||
the guide teaches.
|
||||
|
||||
Structure model ("full dissolve"): no standalone by-video-type / by-feature reference
|
||||
sections survive. Every page becomes a chapter at the level where the reader is ready for
|
||||
it, with an entry bridge ("you can now X") and an exit bridge ("next you'll Y").
|
||||
|
||||
## The capstone (design target — everything builds to this)
|
||||
|
||||
A new, public, promo-style film about HyperFrames itself ("write HTML, render video"),
|
||||
~45–60s, 6–8 frames. It is the "final form": the artifact only a reader who has absorbed
|
||||
every level can prompt into existence. Modeled on the internal promo compositions
|
||||
(`videos/team-vault-explained`, `~/src/videos/hyperframes-infra-proposals`) — the proven
|
||||
advanced stack:
|
||||
|
||||
- `frame.md` design system: strict two-color palette discipline, negative list,
|
||||
permanent grid/chrome that rides every frame
|
||||
- Storyboard with narrative arc, VO-paced reveals (each element lands on its spoken cue),
|
||||
persuasion/beat columns, a callback (early motif returns denser late), one breather frame
|
||||
- TTS narration + BGM at the fixed bed level (post-#2110 default)
|
||||
- One generated-artwork hybrid frame (illustration-led → generated raster + code-layer
|
||||
animation), one data-viz frame, one code frame
|
||||
- Matched-motion transition between at least one frame pair
|
||||
- Variables re-skin: default vs overridden render pair
|
||||
- Full `lint` / `check` / render validation; built for real in
|
||||
`~/src/hyperframes-prompt-examples/capstone/`; renders hosted on static.heygen.ai
|
||||
|
||||
The capstone chapter walks brief → design system → storyboard → per-frame build →
|
||||
validate → render, and each step links back to the level that taught it. The finished
|
||||
MP4 is also embedded in the overview intro as the guide's promise ("by the end you can
|
||||
build this").
|
||||
|
||||
## Level structure and page mapping
|
||||
|
||||
Nav: the `Prompt Guide` top-level group's subgroups become levels.
|
||||
|
||||
| Level | Title | Chapters (existing page → new role) |
|
||||
| ----- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| — | Start here | `overview` — rewritten: the arc's map, skill setup, capstone teaser embed |
|
||||
| L1 | Your first video | Workflow rides, one prompt + embedded render each: `product-launch`, `explainers`, `code-and-prs` (gains changelog-video), `captions-and-talking-heads`, `music-and-slideshows`, `motion-graphics` |
|
||||
| L2 | Control | `anatomy`, `specification-dial`, `vocabulary`, `visual-specs`; `examples` becomes the level-end gallery (18 dissections) |
|
||||
| L3 | Life | `motion` (grammar + measured A/B), `transitions`, seeded-motion rule 7 material |
|
||||
| L4 | Substance | Capability chapters framed as "add this to what you have": `code-blocks`, `data-and-maps`, `overlays-and-lower-thirds`, `captions-catalog`, `generated-artwork`, `vfx-and-liquid-glass`, `runtimes-and-3d` |
|
||||
| L5 | Voice & sound | `media-and-audio` expanded with the media-proxy subsystem (see New topics) |
|
||||
| L6 | Scale | `design-systems`, `variables-and-templating` (+ CSS-shadow fix), **storyboards** (new chapter, extracted from internal-promo practice), `editing-existing-videos`, `iterating`, `recreating-references`, `rendering-and-output`, `remotion-migration` |
|
||||
| L7 | Capstone | New chapter as specified above |
|
||||
| — | Appendix | `rules-and-anti-patterns` kept as the consolidated cheat sheet; each rule is _also_ taught in-context at its level |
|
||||
|
||||
Page count: ~30 (29 existing, minus none, plus storyboards + capstone; overview rewritten).
|
||||
Keep page counts out of prose (standing drift rule).
|
||||
|
||||
## New topics (landed on main after the guide was written, Jul 9–22)
|
||||
|
||||
1. **Media proxy subsystem** → L5 chapter section: HEVC/hostile-codec probe, automatic
|
||||
bounded H.264 and alpha-capable authoring proxies, serving from preview/play/static
|
||||
server, baking into published archives, project opt-out, runtime swap of undecodable
|
||||
video (#2585–#2598 range).
|
||||
2. **New lint rules** → taught at the level where each gotcha becomes relevant AND listed
|
||||
in the appendix: seek-order safety, SVG draw-on rules, relative-value second writers,
|
||||
`tl.set` initial hides, cold-seek opacity reveals (#2503, #2612, f3d210066).
|
||||
3. **Composition-structure mandate block** (#2599, 0aaac7aa3) → L2 anatomy context.
|
||||
4. **changelog-video skill** (e96ebd74d) → L1 code-and-prs chapter.
|
||||
5. **Variables no longer shadow authored CSS custom properties** (406894061) → L6
|
||||
variables chapter correction.
|
||||
|
||||
## Validation
|
||||
|
||||
Standing rule unchanged: no prompt ships unverified. Existing 64 renders are reused
|
||||
wherever the prompt text survives the move verbatim. New validation builds required for:
|
||||
the capstone film (full pipeline), the proxy-chapter prompt, new-lint-gotcha examples,
|
||||
and the storyboard-chapter example. Same bar: built exactly as written by a builder
|
||||
agent, lint/check pass, render embedded.
|
||||
|
||||
## Mechanics
|
||||
|
||||
- All work on `fix/prompt-guide-validation-bugs` in worktree
|
||||
`~/src/wt/hyperframes/prompt-guide`; PR #2109 description updated to describe the arc.
|
||||
- `docs.json` nav rewritten to the level groups; Mintlify redirects for any `prompting/*`
|
||||
slug that moves; the existing `guides/prompting` → `prompting/overview` redirect stays.
|
||||
- Renders synced via `scripts/upload-docs-images.sh` (S3, `docs/images/` stays gitignored).
|
||||
- Fix the currently red Format CI check on the branch while in there.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Tier 3 registry-block overhauls (issue #2107) — unchanged.
|
||||
- HeyGenVerse article resync / llms.txt check — post-deploy follow-ups as before.
|
||||
- No behavior changes to skills or pipeline (that was PR #2110, merged).
|
||||
Reference in New Issue
Block a user