docs(prompting): document the intent interview and align pages with skill contracts - #2872
docs(prompting): document the intent interview and align pages with skill contracts#2872WaterrrForever wants to merge 6 commits into
Conversation
|
Reviewed against the current Two things need a rebase, both caused by commits that landed on the base branch after you branched (you're based at 1. Conflict in
|
| Line | Currently | Should be |
|---|---|---|
| install commands (2×) | npx skills add heygen-com/hyperframes |
append --full-depth |
/hyperframes-cli row |
init, lint, preview, render, doctor |
add check |
| core-skills table | 8 rows | add /hyperframes-keyframes |
| workflow list | 10 workflows | add /figma |
Two of these matter beyond tidiness:
--full-depth— without it,skills addfetches the skills.sh registry blob, which lagsmainby hours. A user following the quickstart gets stale skills.check— the motion chapter now states that bothlintandcheckmust pass before rendering, and callscheck"the step people skip and regret". The quickstart teaching the dev loop without it contradicts that directly.
Clean
No design.md references reintroduced (base renamed those to frame.md), no skill-count claims to drift, /figma survives in overview.mdx, and nothing in your copy restates the motion rules that were rewritten on the base branch — so the rebase should be conflict-free after the one file above.
Reviewed with Claude Code.
|
Follow-up against the current stacked base ( Additional adjustments
After the rebase, please run the normal formatting and docs validation/broken-link checks. The current PR checks are from the unreconciled head and mostly skipped, so they do not validate the eventual merged result. |
general-video leads with its positive identity and companion mode; faceless-explainer keys on invented visuals instead of TTS; talking-head-recut uses the 'graphic overlays' trigger term; motion-graphics gains its input side and overlay output; music-to-video stops implying images are required.
Replace the 4-5 column table hack with a 3-column CSS grid, switch demo clips to autoplay muted loops (no black poster frame, no player chrome over tiny videos), and align cells at 16:9.
The guide taught prompt shapes but never prepared readers for the conversation that follows: the intent interview, the two run-shape questions (storyboard, automation vs companion), the just-build-it skip, and BRIEF.md as the resumable artifact. Add that section to the overview, a disambiguation note on the storyboards page, and free up 'companion' as a reserved term in media-and-audio.
Step 3 (Strategy & Messaging) listed no output while describing exactly what BRIEF.md now captures. Name the artifact in the step table, project tree, step body, gate, and iterating list, and fix SCRIPT.md's step label in the tree (Step 4, not 3).
The quickstart drifted from docs/guides/skills.mdx, CLAUDE.md, and the prompting overview — it had never been updated when those surfaces were: - `--full-depth` on both install commands, with the reason inline. Without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours, so a reader following the quickstart installs stale skills. - `check` in the `/hyperframes-cli` row, and a validate step in the manual dev loop, which went preview → render with no gate at all. The prompting overview calls `check` "the step people skip and regret" and states both `lint` and `check` must pass before rendering. - `/hyperframes-keyframes` in the core-skills table (8 rows → 9). - `/figma` in the optional-workflow list (10 → 11). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2c38e65 to
d3b0430
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Rebased onto Conflict resolutions
One thing I did beyond your list, flagging it so you can veto. The ease gallery (6 clips, the first one on the page) wasn't in the conflict, so leaving it as-is would have left three galleries on one page in two different layouts. I converted it to the same grid, with the same base playback attributes and Run-shape wordingQualified as suggested, and I verified the claim against quickstart.mdx — one correction to the framingAll four items are picked up, in their own commit. But they aren't base-branch changes this PR predates: Also beyond the literal ask: Option 2's manual dev loop went preview → render with no validation step at all, which contradicts "the step people skip and regret" harder than the Validation
|
miga-heygen
left a comment
miga-heygen
left a comment
There was a problem hiding this comment.
PR #2872 Review: document the intent interview and align pages with skill contracts
Overview
A clean follow-up to #2109: 79 additions, 27 deletions across 6 docs files. Three workstreams: (1) document the opening interview and run-shape questions, (2) fix drifted workflow one-liners against the actual SKILL.md contracts, (3) fix the vocabulary page video grids that rendered as black boxes.
1. Workflow one-liner corrections — verified
Spot-checked each corrected description against the on-disk SKILL.md:
/faceless-explainer: SKILL.md says "every visual is invented (typography, abstract graphics, diagrams, data-viz) rather than captured. There is no URL, no website capture, and no real assets." The new one-liner ("no URL, no footage → faceless explainer — every visual invented") matches exactly. The old one ("Arbitrary text → faceless explainer with its own TTS narration") led with TTS, which is a side effect, not the identity./motion-graphics: SKILL.md confirms "Can render to MP4 or transparent overlay" and lists input triggers ("a logo / stat / tweet / brief"). Both now reflected in the one-liner. Good./graphic-overlays(listed as/talking-head-recut): SKILL.md opens with "Package an existing talking-head / interview / podcast video by layering timed, designed GRAPHIC OVERLAY cards" — the new one-liner uses "graphic overlays (kinetic titles, lower-thirds, PiP)", which matches the trigger term. The old "designed graphic cards" was vague enough to confuse with the caption-style workflow./music-to-video: The old one-liner ("A music track + your images") implied images were required input. The new one ("your images optional, cut on the beat") is correct — the music is the required input, images are supplementary./general-video: Now leads with its positive identity ("multi-scene pieces, reels, montages, remixes") and names companion mode. Clean.
One pre-existing note (not a regression from this PR): the overview table uses /talking-head-recut as the slash command, but the actual skill directory on disk is graphic-overlays. This naming mismatch was inherited from #2109. Worth a follow-up to align — or confirm an alias exists in the router.
2. Video grids — correct fix
The old <table><tbody><tr><td>... layout gave each video cell no intrinsic sizing, producing the "tiny black boxes" Miao described. The CSS grid replacement is clean:
repeat(auto-fit, minmax(200px, 1fr))— responsive 3-column at desktop, collapses gracefully on mobile.aspectRatio: "16 / 9"+objectFit: "cover"— forces the right shape even before the video loads.display: "block"— eliminates the inline baseline gap below video elements.#t=0.1fragment preserved on all URLs — shows a first-frame thumbnail instead of a black poster.- All 18 clips keep the same playback attributes (
controls muted loop playsinline preload="metadata").
The same grid pattern is applied consistently to all three galleries (easing, camera, marker). No visual regression risk.
3. Interview section — well-scoped
The new "The interview: what the agent asks first" section documents:
- The route-confirm → must-have questions → run-shape questions flow
- The storyboard/automation-vs-companion 2×2 with all four combinations valid
- The four routes that skip both questions (
/motion-graphics,/slideshow,/embedded-captions,/talking-head-recut) — correctly scoped - The "just build it" skip pattern
BRIEF.mdas the resumable artifact (not the chat)
The section is placed correctly — after the "two prompt shapes" section and before the recommended workflow, so readers understand the conversation before they hit the build steps.
4. BRIEF.md pipeline integration — clean
All five touchpoints updated consistently:
- Step table: Step 3 artifact column now reads
BRIEF.md - Project tree:
BRIEF.mdadded,SCRIPT.mdrelabeled from Step 3 → Step 4 - Step body: output line updated
- Gate: now names the file (
BRIEF.md exists) - Iterating list: new bullet for intent changes
The pipeline page now has a single source of truth for what Step 3 produces.
5. Quickstart alignment — needed
Four corrections, two of which are correctness:
--full-depth— without it, readers install stale skills from the registry blob. Correctness.checkstep added to the manual dev loop — the overview page calls it "the step people skip and regret" while the quickstart hadpreview → renderwith no gate. Correctness./hyperframes-keyframesin core table — aligns with overview. Tidiness./figmain workflow list — aligns with overview. Tidiness.
6. "companion" → "sibling" rename — correct
media-and-audio.mdx renames "companion media pipeline" to "sibling media pipeline" — freeing "companion" as a reserved term for the run-shape concept. One-word change, no content drift.
Verdict
Approve. Every workflow one-liner correction is verified against the actual SKILL.md contract. The video grid fix is a clean CSS upgrade. The interview section fills a real documentation gap (the intent layer) without overreaching. The quickstart alignment fixes two genuine correctness issues. CI clean (docs-only, relevant checks pass).
— Miga
miguel-heygen
left a comment
miguel-heygen
left a comment
There was a problem hiding this comment.
Additive exact-head stamp at d3b0430e.
I audited all six changed MDX files against the current skill contracts and the intent/brief references. The interview text preserves the two independent run-shape questions and all four combinations, the four skip-both routes match their route files, and the BRIEF.md lifecycle is consistent across the overview, storyboard, and seven-step pipeline. The quickstart additions match the CLI contract (check covers runtime, layout, motion, and WCAG contrast), and the workflow one-liners match their SKILL.md descriptions.
The vocabulary layout rewrite preserves all 18 source URLs and every playback attribute while adding a responsive 16:9 grid. git diff --check is clean, Mintlify validation and broken-link checks passed, and every current-head check is terminal. The visible cancelled Format entry is from duplicate CI run 12029, cancelled by concurrency; run 12030 reran the same exact head and Format succeeded.
One correction to the existing review: the claimed /talking-head-recut versus graphic-overlays naming mismatch is not present at this head. skills/talking-head-recut/SKILL.md exists, declares name: talking-head-recut, and the router uses the same route, so no follow-up is needed for that point.
Verdict: APPROVE
Reasoning: The docs now reflect the shipped interview, workflow, pipeline, validation, and gallery contracts without introducing a source or rendering inconsistency; exact-head CI has a successful replacement for the cancelled duplicate run.
— Magi
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Docs-only change, six files. I read all six in full at this head plus the sources they compress: every workflow SKILL.md frontmatter, all ten skills/hyperframes/references/routes/*.md entries, references/intent-interview.md, hyperframes-core/references/brief-contract.md, and the three catalog surfaces (docs/guides/skills.mdx, README.md, CLAUDE.md).
Additive to @miga-heygen's and @miguel-heygen's reviews — two items neither covered, plus an independent read on the graphic-overlays question.
Strengths
docs/prompting/overview.mdx:120is the claim I expected to be the weak point, and it holds exactly. Four routes carryRun-shape: neitherin the router's own entries —routes/motion-graphics.md:10,routes/slideshow.md:10,routes/embedded-captions.md:11,routes/talking-head-recut.md:11— and they are precisely the four named, with the reasons lifted near-verbatim from those files ("the deliverable is a navigable deck, not a rendered video"; "the footage is untouched; there is no storyboard to review"). Same for the rest of the section: the two questions matchintent-interview.md§(a)/(b), the "just build it" line at:126matches the signal that locksflow: automation, storyboard: no, and theBRIEF.mdfrontmatter keys at:128match the carry-away table (workflow,flow,storyboard,message, thenaudience/lengthamong the registry fields). Prose that quotes its source of truth is prose that doesn't silently drift.docs/prompting/vocabulary.mdxfixes the cause, not the symptom. The old markup put awidth: 100%video inside a shrink-to-fit<td>, so the percentage had no definite width to resolve against and the cells collapsed. The grid gives each track a definite size (minmax(200px, 1fr)) and a definite height (aspectRatio: 16 / 9) — no force-sizing involved. Verified at this head: zero<table>and zero<td>left on the page, 18 videos, 18 with#t=0.1, 18 carryingcontrols muted loop playsinline preload="metadata", zeroautoPlay— the base's playback contract preserved on all of them, not only the twelve that conflicted. I also probed the clips (ease-power2-out,ease-sine-inout,camera-push-in,camera-orbit,marker-highlight): all 960×540, soobjectFit: "cover"against a 16:9 box crops nothing. And the deployed preview servesgrid-template-columns:repeat(auto-fit, minmax(200px, 1fr)), so the style survived MDX rather than only compiling.docs/quickstart.mdx:16and:225-231are correctness, not tidiness, and both match their sources:checkis inskills/hyperframes-cli/SKILL.md's command list (which also recordsvalidate/inspect/layoutas deprecated aliases for it), and the--full-depthrationale is near-verbatim fromdocs/guides/skills.mdx:29.
on the suggested graphic-overlays follow-up
Independently checked and it does not reproduce, converging with @miguel-heygen: graphic-overlays appears zero times in the repo tree at this head, the directory is skills/talking-head-recut/, and the router's entry is references/routes/talking-head-recut.md. /talking-head-recut in these tables is already correct — no follow-up needed.
nit — the fix is right, but the mechanism that produced the drift is untouched, so it will recur
docs/guides/skills.mdx:114 states the contract: the one-liners come from each SKILL.md frontmatter description, and "the same catalog lives in the README's ## Skills section and the repo CLAUDE.md; all three surfaces are kept in sync when a skill is added or renamed."
I checked all three at this head, and each already carried the corrected wording for every one of the five — /faceless-explainer, /talking-head-recut, /motion-graphics, /music-to-video, /general-video (docs/guides/skills.mdx:87-94, README.md:83-90, CLAUDE.md:23-30). That is why the drift was isolated to the two tables this PR fixes: docs/prompting/overview.mdx:51-63 and docs/quickstart.mdx:26-32 carry the same catalog content but are not named in that sync set, so nothing brings them along when a description changes.
One clause added to that paragraph naming the two prompting-guide tables would close it. Cheap, and it is the difference between fixing this instance and fixing the class.
nit — one input dropped from /music-to-video
The corrected cell at docs/prompting/overview.mdx:63 reads "A music track (or a video's audio)". The skill's own description carries a third input — a track generated from a mood brief — which is the one that lets someone with no audio at all take this route, and the same clause that makes "a complete video needs zero assets" true. README.md:88 and docs/guides/skills.mdx:92 compress it out the same way, so this is consistency with the catalog rather than a new gap; the page that just fixed a contract inversion in this same cell is the natural place to gain it.
note on re-verifying the run-shape claim
The discussion here cites references/route-briefs.md. At this head that file is an eleven-line "moved" pointer and the Run-shape lines live in references/routes/<workflow>.md. The claim is correct — I verified it in the per-route files — only the citation is stale, and it will send the next reader to a stub.
CI
Terminal-green at d3b0430e6a7ab18e1a06a68a0a86e71896c0d710: 23 successes, 48 skipped by the docs-only path filters, zero failures. The single non-success entry is a cancelled CI run superseded by a later CI run on the same SHA that concluded success. Docs, CodeQL, regression, preview-regression, Player perf, and Windows render verification all concluded success. The block on this PR is the reviewer gate, not a check.
Verdict: APPROVE
Reasoning: Every load-bearing claim in the diff checks out against the skill sources it compresses, the gallery fix addresses the cause and preserves the playback contract on all 18 clips, and CI is terminal-clean at this exact head. Both nits are non-blocking, and the more valuable one is about preventing recurrence rather than about this diff.
— Rames Jusso
…-video input Follow-up on the two review nits from #2872. `/music-to-video`'s SKILL.md names three inputs — an audio file, a video to pull audio from, or a track generated from a mood brief. Every compressed copy of that description carried only the first two, and the third is the one that makes "a complete video needs zero assets" true. Fixed on all eight surfaces that state it, so no surface is now more correct than its siblings: the prompting overview and quickstart setup tables, docs/guides/skills.mdx, the README catalog, root CLAUDE.md + AGENTS.md, both CLI project templates, and the router's own routes/music-to-video.md Input line (whose Interview must-haves already listed all three). The drift was structural, not accidental: the sync set declared in docs/guides/skills.mdx and in CLAUDE.md's "Skill catalog maintenance" named four surfaces and never the two setup tables, so those two were free to rot while the declared four stayed correct. Both declarations now name them, and both say the set applies to a *changed contract* — a reworded description — not only to an added or renamed skill. skills-manifest.json regenerated for the touched route file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Both non-blocking nits from @jrusso1020's review are now fixed in Nit 2 —
|
…-video input Follow-up on the two review nits from #2872. `/music-to-video`'s SKILL.md names three inputs — an audio file, a video to pull audio from, or a track generated from a mood brief. Every compressed copy of that description carried only the first two, and the third is the one that makes "a complete video needs zero assets" true. Fixed on all eight surfaces that state it, so no surface is now more correct than its siblings: the prompting overview and quickstart setup tables, docs/guides/skills.mdx, the README catalog, root CLAUDE.md + AGENTS.md, both CLI project templates, and the router's own routes/music-to-video.md Input line (whose Interview must-haves already listed all three). The drift was structural, not accidental: the sync set declared in docs/guides/skills.mdx and in CLAUDE.md's "Skill catalog maintenance" named four surfaces and never the two setup tables, so those two were free to rot while the declared four stayed correct. Both declarations now name them, and both say the set applies to a *changed contract* — a reworded description — not only to an added or renamed skill. skills-manifest.json regenerated for the touched route file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
56f2357 to
7608fa8
Compare
|
CI is green on 1. Note also why this PR reached those jobs at all: Amended rather than stacked a fixup, since it was a defect in that commit. The whitespace-only fix is the entire delta between Why I missed it locally: I'd run 2. Green on
|
miga-heygen
left a comment
miga-heygen
left a comment
There was a problem hiding this comment.
Re-review: v2 — catalog drift fix
The new commit closes the music-to-video description drift across all 8 surfaces that state it:
| Surface | Updated |
|---|---|
AGENTS.md |
✓ |
CLAUDE.md |
✓ |
README.md |
✓ |
docs/guides/skills.mdx |
✓ |
docs/prompting/overview.mdx |
✓ |
packages/cli/src/templates/_shared/AGENTS.md |
✓ |
packages/cli/src/templates/_shared/CLAUDE.md |
✓ |
skills/hyperframes/references/routes/music-to-video.md |
✓ |
All surfaces now include the third input: "one generated from a mood brief." Wording varies by context (the setup tables compress, the route file is detailed) but the semantic is consistent — a complete video needs zero supplied assets.
The real fix is structural, not editorial: the sync set declaration in CLAUDE.md's "Skill catalog maintenance" section AND docs/guides/skills.mdx's "Source of truth" now name the two setup tables (overview + quickstart) as part of the sync set, and both state the set applies to changed contracts — not just added or renamed skills. This is what prevents the next drift.
skills-manifest.json regenerated for the touched route file. Hash changed only for hyperframes (the skill that owns the route). Consistent.
Still approve. Clean SSOT follow-through.
— Miga
miguel-heygen
left a comment
miguel-heygen
left a comment
There was a problem hiding this comment.
Exact-head v2 stamp at 7608fa899.
The previously approved head d3b0430e6 remains an ancestor, so I audited the new nine-file delta. The contract text now matches skills/music-to-video/SKILL.md:3,31 across all eight surfaces that state the input: root AGENTS.md:22, root CLAUDE.md:28, README.md:88, docs/guides/skills.mdx:92, docs/prompting/overview.mdx:63, both CLI templates at line 15, and skills/hyperframes/references/routes/music-to-video.md:3. All include file/video/mood-brief generation, preserving the zero-supplied-assets route.
The recurrence fix is correctly structural: CLAUDE.md:50 and docs/guides/skills.mdx:114 now include the prompting setup surfaces in the sync set and explicitly cover changed contracts, not only add/rename events. The CLI templates remain byte-identical, skills-manifest.json regenerates in sync with only the owning hyperframes hash changed, and git diff --check is clean.
Current-head CI is terminal: 41 successes, 5 intentional skips, zero pending or failed checks. The remaining GitHub block is the reviewer gate.
Verdict: APPROVE
Reasoning: The v2 delta closes both the specific music-input omission and the maintenance-rule gap that allowed the catalog surfaces to drift, with exact-head validation clean.
— Magi
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Re-review of the delta since the previously approved head — nine files, both nits. I read the delta in full and re-derived the surface population from a fresh checkout of this head rather than from the change list.
Additive to @miga-heygen's and @miguel-heygen's re-reviews: a correction I owe on my own prior comment, the sweep that actually licenses the "all eight" claim, one completeness check neither stated, and one new finding.
Correction to my previous review
My graphic-overlays note said the string appears zero times in the tree. That was wrong, and you're right to push on it — there are 12 occurrences across 5 files: packages/cli/src/commands/skills.test.ts (8), packages/cli/src/commands/skills.ts:719, packages/cli/src/utils/skillsManifest.ts:422, docs/changelog.mdx:2524, releases/v0.7.8.md:25. I confirmed each is a deliberate reference to the rename: the two source hits are prune-logic comments explaining why a renamed skill's stale bundle would otherwise linger, the test hits use the old name as the canonical renamed/unknown-skill fixture, and the last two are the historical changelog and release entries.
The conclusion is unchanged — skills/talking-head-recut/ is the directory, its frontmatter is name: talking-head-recut, there is no skills/graphic-overlays/, so /talking-head-recut in the tables is correct — but it stands on the directory and frontmatter, not on an absence I asserted without measuring.
What I verified on the delta
- The completeness claim is real, and here is what licenses it. Rather than confirm the eight changed rows, I swept the tree for the old two-input shape (
audio file, or video to pull audio from,or a video's audio,music track (or a): zero remnants. Every surface that states the input now states three, and the propagated wording matchesskills/music-to-video/SKILL.md'sdescription:in both directions, including the "zero supplied assets" clause that the third input is what makes true. - The amended contract has no unamended sibling. This is the check that decides whether nit 1 actually closed:
AGENTS.mdcarries the workflow list but no maintenance/sync declaration of its own, so the contract exists in exactly two places —CLAUDE.mditem 1 anddocs/guides/skills.mdx"Source of truth" — and both were amended. HadAGENTS.mdheld a third copy, this would have reproduced the original bug inside its own fix. - The new cross-link resolves.
/prompting/overview#one-time-setupmatches the## One-time setupheading atdocs/prompting/overview.mdx:29. - Both templates are still byte-identical (verified by hash, not by reading).
- Scoping the sync set to a changed contract, not just add/rename, is the better half of this fix. A reworded
description:was exactly the event both declarations failed to cover, and it is the event most likely to recur.
One factual note on the nit-2 accounting
The eight fixed surfaces don't include docs/quickstart.mdx, though the comment lists it. Its workflow skills are a bare inline enumeration at :32 with no per-workflow descriptions, so there was nothing there to correct — the count is right, the attribution is off by one file. Worth saying only because it cuts the other way for nit 1: quickstart.mdx does belong in the sync set, since its core-skill table at :22-31 compresses those descriptions and can drift on its own.
Also worth noting for the record that docs/prompting/music-and-slideshows.mdx:31 already carried all three inputs before this PR. The prose page that explains the workflow was correct; only the compressed one-liners were wrong. That is the drift direction your diagnosis predicts, and it is the strongest evidence the diagnosis is right.
New finding — the same failure class survives two items below the one you fixed
CLAUDE.md maintenance item 3 has two stale pointers, not one. You flagged skills/hyperframes/references/workflow-catalog.md; item 3 also sends readers to references/route-briefs.md "when the route asks questions." Both are now # … (moved) stubs, and both contracts live under references/routes/<workflow>.md.
So the numbered list this PR just corrected at item 1 still misdirects at item 3, on both of its pointers, in the same failure class — a maintenance rule outliving the layout it describes. Since you offered: yes, please fold it in. It is two path corrections in a file this PR already edits, and it closes the item that would otherwise send the next person doing exactly this task to two stubs. Non-blocking either way — if you'd rather land this as-is, the follow-up is equally fine, and a re-stamp after one more push is cheap.
CI
Terminal-green at 7608fa89904a856ca3433fbd8134b253fce49a2f, read at this head rather than carried over: 41 success, 5 skipped, and zero non-success entries. All seven workflow runs at this SHA are completed/success. Docs is on attempt 2, which matches the account of the re-run after the timed-out validate job — the passing attempt is the one attached to this head, and no cancelled or timed-out entry remains. The block is the reviewer gate, not a check.
Thanks for handling the CI self-correction the way you did. Retracting your own "green" claim and naming the cascade — one misaligned table cell taking down four checks through a skipped-parity gate — is more useful than a clean report would have been, and the unpinned-formatter detail is the part that will save someone else the same hour.
Verdict: APPROVE
Reasoning: Both nits are addressed at the class level rather than the instance, the completeness claim survives an independent old-shape sweep with zero remnants, the amended contract has no unamended sibling copy, and CI is terminal-green at this exact head. The item-3 finding is non-blocking and the author has already offered to take it.
— Rames Jusso
5 participants
Rebased onto
mainafter #2109 merged (6c185f252). Now targetsmaindirectly — thedocs/prompting/pages this PR edits landed with that merge.What
BRIEF.mdas the artifact later sessions resume from. The run-shape paragraph is scoped to the routes that actually apply them —/motion-graphics,/slideshow,/embedded-captions, and/talking-head-recutareRun-shape: neitherinroute-briefs.mdand are named as skipping both.BRIEF.mdthe pipeline guide's Step 3 artifact (step table, project tree, step body, gate, iterating list), and fixSCRIPT.md's mislabeled step in the tree (Step 4, not 3).repeat(auto-fit, minmax(200px, 1fr)), 16:9, collapses on narrow screens). The old 4-5-column tables rendered as unreadable black boxes. All 18 clips keepmain's deliberate playback behavior —controls muted loop playsinline preload="metadata"plus#t=0.1first-frame thumbnails, no autoplay on multi-clip galleries.docs/quickstart.mdxwith the skills catalog:--full-depthon both install commands (with the reason inline),checkin the/hyperframes-clirow plus a validate step in the manual dev loop,/hyperframes-keyframesin the core table,/figmain the workflow list.Why
The intent layer (
BRIEF.md,flow,storyboard) is the front door of every skills run, but the guide never prepared readers for it: no page explained the interview, companion vs automation, or the file that makes a brief resumable. The catalog one-liners had also drifted from the SKILL.md descriptions they compress — including one that inverted a contract (music-to-video requires zero user assets).The quickstart drift is separate and older: it had never been updated when
docs/guides/skills.mdx,CLAUDE.md, andREADME.mdgained--full-depth,/hyperframes-keyframes, and/figma. Two of the four items are correctness, not tidiness — without--full-deptha reader installs skills that lagmainby hours, and a dev loop taught withoutcheckcontradicts the overview calling it "the step people skip and regret."Test plan
@mdx-js/mdx— 0 failures/packages/cli#*anchors matchorigin/mainexactly, no new ones introduced#the-interview-what-the-agent-asks-firstresolves from both cross-links (storyboards.mdx,guides/pipeline.mdx)