brief-app-preview

name	brief-app-preview
description	Produces production-ready briefs for app onboarding, App Store preview, and feature-demo videos from supplied UI screenshots. Defines the feature promise, cropped UI beats, interaction choreography, captions, motion rules, platform specs, and asset manifest. Use when screenshots exist and the goal is to show a product feature in action. Not for generic short-form social videos (use brief-shortform) or rendering the video (use produce-video).
argument-hint	[feature name] [--surface app-store|onboarding|website|social] [--screenshots path/to/dir]
allowed-tools	Read Edit Write Grep Glob Bash
metadata	{"version":"1.1.0","budget":"deep","estimated-cost":"$2-4"}

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