Skip to content

docs(prompting): document the intent interview and align pages with skill contracts - #2872

Open
WaterrrForever wants to merge 4 commits into
fix/prompt-guide-validation-bugsfrom
miao/prompt-guide-intent-layer-docs
Open

docs(prompting): document the intent interview and align pages with skill contracts#2872
WaterrrForever wants to merge 4 commits into
fix/prompt-guide-validation-bugsfrom
miao/prompt-guide-intent-layer-docs

Conversation

@WaterrrForever

Copy link
Copy Markdown
Collaborator

Stacked on #2109 — targets its branch, since the docs/prompting/ pages only exist there.

What

  • Add "The interview: what the agent asks first" to the prompting overview: the route confirm, the must-have questions, the two run-shape questions (storyboard; automation vs companion) with the four-valid-combinations note, the "just build it" skip, and BRIEF.md as the artifact later sessions resume from.
  • Add a note on the storyboards page separating the plan this page teaches from the interview's storyboard question — that answer changes the review process, not the route.
  • Make BRIEF.md the pipeline guide's Step 3 artifact (step table, project tree, step body, gate, iterating list), and fix SCRIPT.md's mislabeled step in the tree (Step 4, not 3).
  • Correct the workflow one-liners in the setup tables against each SKILL.md contract: general-video leads with its positive identity and companion mode; faceless-explainer keys on invented visuals instead of TTS; talking-head-recut uses its "graphic overlays" trigger term; motion-graphics gains an input side and its transparent-overlay output; music-to-video stops implying images are required. The quickstart mirror is updated in lockstep.
  • Rework the vocabulary page's two video grids: 3-column CSS grid, autoplay muted loops, 16:9 alignment. The old 4-5-column table rendered as unreadable black boxes (dark first frames behind preload="metadata", player chrome covering ~250px-wide videos, ragged cell heights).
  • Rename "companion media pipeline" to "sibling media pipeline" in media-and-audio — companion is now a reserved term.

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).

Test plan

  • Manual testing performed — every edited page verified on a local mint dev: pages render, the new #the-interview-what-the-agent-asks-first anchor resolves from both cross-links, video grids play and align
  • Documentation updated

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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant