brief-app-preview

App-Preview Brief — Orchestrator

Production-grade brief for one feature, proven through cropped UI beats from supplied screenshots. Reads the platform spec catalog and turns a feature + flow into a hero brief plus an asset manifest, a crop map, and a produce-video handoff — each producible without follow-up questions.

Core Question: "Could an editor open After Effects (or HyperFrames / Remotion) and ship this brief verbatim, with the result being recognized as a believable, native preview of this specific product on this specific surface?"

Why this skill exists, philosophy, when NOT to use it, the 6 hard gates, and the distinction from brief-shortform: references/playbook.md [PLAYBOOK].

---

Critical Gates — Read First

Non-negotiable constraints before dispatching any agent:

1. Screenshots are required. No invented UI. Every beat references a supplied source file. Missing screenshots → NEEDS_CONTEXT, not a generic video plan.
2. One feature per brief. Multi-feature requests become multiple briefs. The skill rejects "show the whole app" framing — the feature is the contract.
3. Each beat must prove one user-visible action or state change. Hover, idle drift, "establishing" beats fail. Every beat earns its seconds with a verifiable change in the cropped slice.
4. Whole-screen footage is forbidden unless the full screen is the smallest meaningful unit. Default is component / region crop. Full-screen is an exception with a written justification, not a fallback.
5. Captions support the beat; they do not explain the whole product. A caption attached to one beat states what that beat proves — not the feature's marketing pitch.
6. Motion specs must preserve source UI styling: colors, radius, type, spacing. Synthetic glow, invented gradients, recolored components → critic FAIL.

---

Quality Gate

Critic agent verifies before delivery (all five PASS required, max 2 rewrite cycles):

• Screenshot grounding — every beat names a real source file + crop rectangle (or component selector); zero invented UI; brand colors / type / spacing match source
• Component-level focal beats — no whole-screen tours; each beat crops to the region that proves the action; full-screen beats have a written one-line justification
• Beat clarity — every beat proves exactly one user-visible action or state change; idle / hover / "show off the UI" beats fail
• Brand fidelity — motion + caption + pointer specs respect brand/BRAND.md voice + brand/DESIGN.md tokens + brand/CREATIVE-DIRECTION.md motion/pacing direction when supplied, or carry a brand_source: cold-start-hint flag. (The operator screenshots are themselves the realized surface — design the motion against what the UI actually shows; references/_shared/realized-surface-grounding.md.)
• Platform fit — output respects the target surface's hard constraints (App Store policy, onboarding-card autoplay rules, website embed muting, social aspect/captioning); platform-format-agent's hard rules satisfied

Full 5-sub-critic rubric (Grounding / Component Focus / Beat Clarity / Brand Fidelity / Platform Fit) + binary verdicts + Rewrite Routing Table live in agents/critic-agent.md.

---

Before Starting

Per references/_shared/before-starting-check.md [PROCEDURE] — load ICP + BRAND.md context, confirm screenshots are accessible, identify target surface, check brand/DESIGN.md freshness.

Artifact	Source	Required?
Screenshots directory (≥2 per screen/state; resting + interaction + result + optional variant)	Operator-supplied	Hard-required (Critical Gate 1) — NEEDS_CONTEXT if missing
brand/BRAND.md	create-brand	Soft-required — proceeds with brand_source: cold-start-hint flag if missing; critic warns on motion specs that contradict typical brand discipline
brand/DESIGN.md	create-brand	Soft-required — same cold-start handling as BRAND.md; tokens (color hex, radius, type scale) lifted into motion-spec output when present
brand/CREATIVE-DIRECTION.md	create-brand	Optional — house motion/pacing direction; informs beat rhythm + pointer feel when present
research/icp-research.md	research-icp	Optional — informs caption register and feature framing
Prior docs/forsvn/artifacts/marketing/app-preview-brief/[slug]/	this skill	Optional — re-run with --rev=N to preserve prior brief

---

Pre-Dispatch + Mode

Canonical Pre-Dispatch (references/_shared/pre-dispatch-protocol.md). Dimensions: feature name, screenshot inventory, flow order, target surface, brand mode, market. Full read-order + Cold Start (5-question bundled) + hard-block conditions: references/procedures/pre-dispatch.md. Mode resolution per references/_shared/mode-resolver.md; --fast skips Layer 2 (no critic, no platform-format) — does NOT skip Cold Start or Critical Gates 1-6. Session execution profile (single-vs-multi): inherit per references/_shared/execution-policy.md. At brief-binding, bind the video target tool — inherit tool_targets or ask once per references/_shared/tool-target.md; tool-agnostic stays the default.

---

Agent Manifest + Routing

6 sub-agents: Layer 1 intake-validator (hard gate) → Layer 1.5 parallel (flow-slicer, interaction-storyboard, motion-spec) → Layer 2 sequential (platform-format → critic 5-sub-critic gate, max 2 rewrite cycles). One feature × one surface per run. Full per-agent focus + dispatch pseudocode + spawn mechanics + critic routing + single-agent fallback + chain position + skill deference: references/procedures/dispatch-mechanics.md [PROCEDURE]. Load at Layer 1 dispatch entry.

---

Artifact Contract

• Output root: docs/forsvn/artifacts/marketing/app-preview-brief/[slug]/
• Files (4): brief.md · assets.md · crop-map.md · handoff-produce-video.md
• Lifecycle: pipeline — one artifact set per (feature, surface, market); re-run on feature pivot or surface change
• Frontmatter fields (brief.md): type, role, status, decision_state, review_tool, reviewed_at, reviewer, date, slug, feature, surface, brand_mode, market, screenshot_count, beat_count, total_length_seconds, aspect, brand_source, critic_passes[], critic_loop_count
• Body sections (brief.md, 12, in order): TL;DR for the Editor · Feature Promise · Source Inventory · Beat Sequence · Crop / Mask Plan · Interaction Choreography · Motion Spec · Caption Pack · Pointer + Audio Plan · Platform Spec · What NOT To Do · Handoff to produce-video
• Consumed by: produce-video (via handoff-produce-video.md) — emits the runtime scaffolds; never brief-shortform, never publish-social
• Cross-stack contract: schema changes require atomic update of format-conventions.md § "Frontmatter field order" + § "Body section headers (verbatim)" + produce-video's video-brief-schema.md extension for app-preview inputs (WS4 will land that extension)

Full template + frontmatter spec + per-section format rules + crop-rectangle notation + interaction-verb glossary: references/format-conventions.md [PROCEDURE]. The decision_state / review_tool / reviewed_at / reviewer fields are the human-review layer rendered by the forsvn-preview review module. Pipeline default: decision_state: not_required.

---

Anti-Patterns

references/anti-patterns.md [ANTI-PATTERN] — 5 sub-critic clusters + 4 cross-cutting marketing-stack rows. Re-read before any output ships.

---

Durable Rules (protected)

Completion Status

• DONE — all 5 critics PASS within ≤2 cycles. Brief + assets + crop-map + handoff produced; all 4 files written.
• DONE_WITH_CONCERNS — loop cap reached; remaining FAILs surfaceable as warnings. Concerns pinned at top of brief.md.
• BLOCKED — --render / --publish / --auto-run requested (this stack emits briefs; produce-video emits scaffolds; neither calls render engines); critic FAILed twice on Gate 1 or 6; target surface unsupported (only the four canonical surfaces are accepted).
• NEEDS_CONTEXT — screenshots missing (Gate 1); multi-feature request not split; target surface not derivable; brand artifacts AND ICP both absent AND feature framing too thin to proceed.

---

Chain Position

Previous: create-brand (recommended — brand tokens), research-icp (optional — VoC), product team / design team (supplies screenshots) | Next: produce-video consumes handoff-produce-video.md and emits the multi-runtime export bundle; operator runs the chosen scaffold through HyperFrames / Remotion / their AI CLI of choice.

Re-run triggers: feature pivot, surface change, screenshot inventory updated, brand/DESIGN.md tokens updated, operator wants a different surface pass (re-run with --surface=... and a new slug).

---

Worked Example

End-to-end walkthrough + FAIL cycle 2 + --fast variant: references/examples/app-preview-walkthrough.md [EXAMPLE].

References

• references/playbook.md, format-conventions.md, anti-patterns.md
• references/procedures/{pre-dispatch, dispatch-mechanics}.md
• references/_shared/{before-starting-check, manifest-spec, mode-resolver, pre-dispatch-protocol}.md
• Domain catalogs (loaded by craft agents at dispatch): references/{platform-specs, interaction-grammar}.md
• 6 sub-agents in agents/; critic-agent.md holds the canonical 5-sub-critic gate