# TrueTraceShorts review/upload reporting rules

Use this when delivering a TrueTraceShorts/AutoShortsBot review package, YouTube private upload result, or post-upload audit summary.

## Render QA pitfalls

- Hard blocker: do not ship renderer-built phone/chat/app screens as final visuals for TrueTraceShorts. Final main visuals must be premium AI keyframes with clear scene descriptions; the renderer may only copy/crop/motion those images and add text-only active-word subtitles. Self-built UI/mockup/PowerPoint-looking visuals are allowed only for internal prototypes, never review-ready deliverables.
- Before creating a new renderer/topic, check existing scripts and post candidates for the theme and format family. If an earlier AI-keyframe workflow exists, extend or adapt it instead of inventing a parallel self-rendered UI workflow.
- Keep the expanded channel concept in scope for each new video: choose `red_flag_short`, `already_clicked`, `spot_the_trap_quiz`, `true_scam_story`, or `scam_breakdown` first; do not default back to repeating an old delivery/red-flag topic unless it is the intended format slot.
- For review-ready videos, describe each premium AI keyframe clearly (what the viewer sees, scam pattern, safety exclusions) before generation; QA the generated images for no real brands/domains/phones/QR/bank/card data before rendering.
- Avoid crossfades between text-heavy phone/app screens; they create ghosting/double text in sampled frames and make subtitles look broken. Use hard cuts or very short non-text transitions instead.
- Do not place scene-explainer microcopy near the subtitle safe zone. If the renderer adds active-word subtitles, reserve the lower third for captions only.
- At QA, inspect frames around long subtitle segments (for example 0:25-style captions). If text exceeds safe margins, keep script/voice/images/timing unchanged and fix only subtitle wrapping, using measured line breaks rather than shrinking everything globally.
- For new candidates whose package lives under `data/post_candidates/<slug>/<version>/youtube_private_upload_package`, run dry-run with an explicit package dir:
  ```bash
  AUTOSHORTS_YOUTUBE_PACKAGE_DIR='data/post_candidates/<slug>/<version>/youtube_private_upload_package' \
    python3 -m autoshorts.cli.youtube_private_upload_dry_run <candidate_id> --version <version>
  ```

## Report format after a render/upload-prep

Always include:

- MP4 media path/link for review when available.
- YouTube title and description.
- TikTok caption/description text, even when TikTok upload is **not** approved.
- Duration, voice/version, video SHA256, posting-pack SHA256.
- Exact approval command for private YouTube upload when upload has not yet happened.
- After upload: Studio link, Shorts link, privacy status, API endpoint used, OAuth scope, thumbnail status, and audit commit if committed.

## TikTok handling

- YouTube remains the primary channel.
- TikTok upload requires explicit user approval.
- Still include a TikTok caption in review/upload reports so the user does not need to ask for it separately.
- Do not create TikTok placeholders or links on the website unless explicitly requested.

## Recovery/no-shame wording

For recovery-oriented formats (`already_clicked`, similar):

- Prefer: `You didn’t do anything wrong. This is designed to make you hurry.`
- Avoid: `You are not stupid.` / `You’re not stupid.` unless the user explicitly requests that wording.
- Also update website copy and package descriptions if the video script changes; old wording lingering on landing pages is a QA miss.

## Natural-language upload approval

If the user says a natural-language approval such as `private upload approved` immediately after one hash-bound review package:

1. Re-open/use the stored package approval command.
2. Run the dry-run gate.
3. Execute upload only if the stored approval command matches the just-delivered package and dry-run is valid.
4. If multiple packages are in scope, ask for the exact approval command instead of guessing.

## YouTube thumbnail failures after upload

See `references/youtube-private-upload-thumbnail-remediation.md`.

- If `videos.insert` returns a YouTube video ID and then thumbnail setting fails, do not rerun the full upload command; remediate only the thumbnail or record it as unset.
- YouTube rejects WebP thumbnails for `thumbnails.set`; use JPEG/PNG in upload packages.
- A `403` on `thumbnails.set` can mean the channel/user lacks custom thumbnail permission. Report the private upload as succeeded and the thumbnail as not set, with manual Studio review required.

## Report tone

Keep the report concise but complete: status first, then links, then descriptions/captions, then audit/QA details. Mention TikTok caption as a text deliverable, not as an upload action.