--- name: ugc-edit-workflow description: Edit real creator footage (raw UGC clips) into finished UGC ads or Meta ads. No AI generation. Audits the footage, analyses the script if given, finds winning ads to use as edit references, builds hook variants and cutdowns in HyperFrames, runs /review rounds, and exports Meta-ready 9:16 and 4:5 files. Use for any "turn these clips into an ad" request. --- # UGC Edit Workflow — raw creator clips to finished ads Input: real footage a creator shot (phone videos, b-roll, product close-ups), optionally a script, optionally app or product assets. Output: finished ads, usually one main cut plus hook variants and cutdowns, reviewed by the owner and exported for Meta and TikTok. Nothing is generated; every frame comes from the creator's footage or the owner's assets. Modules this file calls when needed: - `~/.claude/skills/app-ugc-ad-editing/SKILL.md` — HyperFrames edit rules, captions, audio, dual-export QA. Phase 5. - `review/SKILL.md` — `/review`, `/review done`. Phase 6. - `treg` skill — only for reference research (ad libraries); it is the only paid step, and small. - `~/.claude/skills/aiugc-video-workflow/upscale/README.md` — optional free 2x upscale when a creator shot in 720p or lower. ## Standing rules 1. **Brief first.** At the start and at each phase, tell the owner in a few lines what you are about to do, why, and what you need from them. Then work. 2. **Rights before cuts.** Confirm the owner holds usage rights for paid ads on this creator's footage, music and any third-party material. Record it in `ASSET_MANIFEST.md`. No rights, no edit. 3. **Truth.** Captions say what the creator actually says. Product UI comes from real recordings or screenshots. Claims only from the approved list. A creator's experience is theirs; never caption or re-voice them into a claim they did not make. 4. **Keep the human.** The creator's delivery is the asset. Trim dead air and false starts; never cut so tight they sound robotic. Preserve their light and colour unless a correction is clearly needed. 5. **Preserve everything.** Raw clips untouched; edits non-destructive in HyperFrames; every version kept. 6. **Say what you checked.** Audio you cannot hear is reported as unchecked. ## Phase 0 — Tools (once per session) HyperFrames (`npx hyperframes --version`), ffmpeg and ffprobe, whisper-cli for transcription, Python with OpenCV for contact sheets. Treg signed in only if reference research is wanted. Report what is present. ## Phase 1 — Intake Ask for everything in one message, with what you already know filled in: - **Footage:** the raw clips (folder or links). Phone originals preferred, not re-compressed exports from a chat app. - **Script or brief:** the script the creator was given, if any; otherwise the one promise, audience, CTA and any must or must-not claims. - **Product proof:** app recordings, screenshots, product shots, from the asset library (`config/apps.yaml`) or supplied by the owner. - **Brand:** logo, colours, font, caption style preferences, end card if one exists. - **Rights:** confirmation that the creator contract covers paid usage, for how long, and on which platforms; music licence. - **Placements and quantity:** Meta Reels and Stories, Feed, TikTok; how many pieces (main cut, hook variants, 15 s cutdown) and by when. Write `BRIEF.md` and `ASSET_MANIFEST.md`. Create the campaign folder `campaigns//-edit/` with `raw/`, `edit/`, `edit-4x5/`, `work/`, `refs/`. ## Phase 2 — Footage audit and selects 1. **Inventory:** every clip with duration, dimensions, frame rate, orientation, audio present, camera (front or rear), and a one-line description. `ffprobe` for specs, a contact sheet per clip (one frame every 2 s) for content. 2. **Transcribe** all spoken clips with whisper. Save `TRANSCRIPT.md` with timestamps per sentence and per take. 3. **Selects log** (`SELECTS.md`): for each line of the script (or each idea the creator spoke), list the takes with time ranges and a score 1 to 5 for delivery, eye contact, audio cleanliness, framing. Mark the best take per line, usable reactions, gestures, pauses, b-roll, product moments and anything unusable (noise, blur, notifications on screen). 4. **Hook candidates:** list every sentence or visual that could open the ad (a confession, a result, a question, a surprising action, the product in use). Score each for how fast it lands. You need at least two. 5. **Problems to solve in the edit:** gaps (a line never delivered cleanly), continuity breaks (outfit, light), noise, shaky sections. Note how each will be handled (jump cut, b-roll cover, caption, punch-in) or whether a pickup from the creator is needed. Tell the owner now if something is missing; do not discover it at the gate. 6. Fix technical basics on copies in `work/`: level audio to about -16 LUFS, denoise lightly if needed, stabilise only shots that are hard to watch, rotate and conform frame rates. Original clips stay untouched. ## Phase 3 — Script analysis and edit references **If a script was provided**, analyse it before touching references: the angle (problem, demo, discovery, objection, comparison, routine), the promise, the proof type, the emotional beat, the CTA, the claims (sourced or not), and the structure (hook, problem, solution, payoff, CTA). Note where the footage covers each beat and where it does not. Rewrite nothing; this is a map. **Then find winning ads that match that angle and structure** to use as edit references, not as scripts: - Owner's own reference library first (asset portal references). - Meta Ad Library through Treg (say the price first): search the app's category and competitors, sort by days running; you only ever see survivors, so longevity is a signal, not proof. Filter to ads with the same angle and format (talking creator, demo, voiceover b-roll). - TikTok and Instagram organic search for the same pain or feature, for pacing and caption style only. Shortlist 3 to 6: platform, advertiser, days running or views, length, angle, format, caption style, one line on why it matches. The owner picks **one edit reference**. Download it to `refs/`, logged as study material. **Measure the reference:** cuts (`ffmpeg select='gt(scene,0.28)'`), mean shot length, when the hook lands, when the product first appears, caption style (position, size, how many words per card, emphasis), music role, CTA timing, end card. Write `EDIT_PLAN.md`: our beats mapped onto the reference's rhythm, with the selected takes per beat. **With no script and no reference preference**, infer the angle from what the creator actually said (the transcript is the script) and search references for that angle. ## Phase 4 — Edit map and variants - **Structure:** hook (1 to 3 s), problem or context, product proof, payoff, one CTA. Use only beats the footage supports. - **Length:** the natural length of the usable delivery; typically 15 to 30 s for Reels and TikTok, a 15 s cutdown for Feed. Do not pad. - **Hook variants:** plan 2 to 3 openings from the hook candidates, same body. Vary the first frame as well as the line (a reaction, a text card, the product in hand). Name `-H1`, `-H2`, `-H3`. - **Cutdowns:** a 15 s version from the same timeline when the delivery allows, keeping hook, one proof, CTA. - **One variable per variant** (hook, caption style, CTA, length) so results can be read. - Write the map into `EDIT_PLAN.md` with source clip and time range for every shot. Share it with the owner in the phase brief; adjust before building. ## Phase 5 — HyperFrames edit (editing module) - Cut on thoughts, phrases and reactions, not on a timer. Jump cuts and punch-ins (5 to 15 %) to hide trims and add variety; no shake, parallax or constant zoom. - Product proof as a real screen recording insert or a phone-mockup recording, held long enough to read. Composite into a phone in the footage only when the creator is actually holding one and the real screen is unusable. - **Captions:** burned in, matching the transcript word for word, brand font, dark pill or the brand's caption style, 3 to 6 words per card, one or two emphasised words. Keep them off the mouth and the UI. **Safe zones:** Stories UI covers roughly the top 14 % and bottom 20 %; Reels roughly the top 14 % and bottom 35 %. Captions and CTA sit inside the safe band for the tightest placement you export to. - **Sound-off first:** the ad must make sense muted (captions plus visuals), and still reward sound-on. - Audio: creator voice first, at about -16 LUFS; music ducked under speech (carve); 1 s tail; no clipping, no gaps. - CTA and end card from approved assets; logo small and late unless the brand wants it early. - Two editable compositions: 9:16 project, 4:5 reframed by hand per shot. Export an `.srt` as well. ## Phase 6 — Gate, then owner review rounds Gate: `hyperframes check` clean; exact dimensions; duration; no black or frozen frames; a frame from every shot; captions match the transcript; captions and CTA inside safe zones for every placement; audio level and tail; both ratios checked separately; no unlicensed music; the creator never captioned into a claim they did not make; a frame-by-frame look at every cut point for flash frames. Then `/review` with the main cut. On `/review done`, apply notes, reply on each, re-render, next round. Repeat until a round closes with no open notes and the owner confirms. Variants and cutdowns follow in their own rounds once the main cut is locked. ## Phase 7 — Output menu, export, final folder Ask with a checklist, defaults ticked: - [x] Main cut 9:16 · 1080x1920 · captions (Reels, Stories, TikTok) - [x] Main cut 4:5 · 1080x1350 · captions (Feed) - [ ] Hook variants H2, H3 in both ratios - [ ] 15 s cutdown in both ratios - [ ] No-caption versions (for platforms that add their own captions) and `.srt` files - [ ] 1:1 · 1080x1080 - [ ] Free 2x upscale first, when the source is 720p or lower - [ ] Raw selects copied alongside Encode for Meta: H.264 High, AAC, MP4 faststart, source frame rate preserved (never force 24 to 30), 1080 wide, under 4 GB. Verify every file (dimensions, duration, codec, no black or frozen frames). Deliver to `///` with only the ticked outputs, named `____[_H2|_15s|_nocap].mp4`, `_superseded/` for earlier versions. Send the files in chat, open the folder, show a short spec table. Hand over `EDIT_PLAN.md`, `SELECTS.md`, `TRANSCRIPT.md`, `ASSET_MANIFEST.md`, `QA_REPORT.md`, `REVIEW.md`, both editable projects, and a closing brief: what shipped, which variant differs by what, and one line on what could be tested next. **Uploading to Meta (note for the owner):** Advantage+ creative enhancements can alter the asset after upload (text position, music, cropping, visual touch-ups). Suggest turning off the enhancements that change text or music so the reviewed cut is what runs. ## Required records `BRIEF.md`, `ASSET_MANIFEST.md` (with rights), `TRANSCRIPT.md`, `SELECTS.md`, `EDIT_PLAN.md`, `QA_REPORT.md`, `REVIEW.md`, `DECISION-LOG.md` (reference research cost, if any).