# TrueTraceShorts format-family implementation spine

Use this after the channel strategy expands beyond repetitive red-flag shorts and the user asks to implement the format-family concept in AutoShortsBot and the website.

## Purpose

Keep the channel positioned as digital self-defense for normal people while adding format variety for reach, trust, retention, comments, and search value. Do not abandon the core line:

```text
One screen. One red flag. One safer move.
```

Instead, annotate every planned video with its format role before rendering.

## Format metadata fields

A candidate or planning artifact should carry at least:

```json
{
  "format_type": "red_flag_short | already_clicked | spot_the_trap_quiz | true_scam_story | scam_breakdown",
  "hook_type": "damage_first | identification | quiz | story | counterintuitive | recovery",
  "viewer_state": "not_clicked | already_clicked | helping_family | learning_pattern",
  "cta_type": "follow | save | comment | checklist | share_family",
  "website_target": "/redflags/[slug]/ | /already-clicked/ | /stories/[slug]/ | /quizzes/[slug]/",
  "duration_class": "35-45 | 50-75 | 45-60",
  "evidence_level": "generic_pattern | sourced_case | official_guidance",
  "claim_mode": "educational_pattern | sourced_case_summary | official_guidance_summary",
  "first_frame_scam_label": "READABLE RED LABEL ONLY ON FIRST VISIBLE KEYFRAME"
}
```

## Recommended initial mix

For the next 20-video learning batch:

- 10x `red_flag_short`
- 5x `already_clicked`
- 2x `spot_the_trap_quiz`
- 2x `true_scam_story`
- 1x `scam_breakdown`

Prioritize `already_clicked` first because it has the strongest trust/search/save value and ties naturally to the website recovery hub.

## First 5-video test wave

Use as a canonical starter set:

1. `Already clicked a fake delivery link? Do this now.` — `already_clicked`, `recovery`, `/already-clicked/`
2. `Can you spot the scam in this delivery text?` — `spot_the_trap_quiz`, `quiz`, `/redflags/delivery-sms-trap/`
3. `It started with a fake support popup.` — `true_scam_story`, `story`, `/redflags/fake-support-popup/`
4. `The fake logo is not the trap.` — `scam_breakdown`, `counterintuitive`, `/redflags/delivery-sms-trap/`
5. `Entered your password on a fake page? Do this first.` — `already_clicked`, `recovery`, `/already-clicked/`

## Website requirements

Start with `/already-clicked/` before adding `/stories/` or `/quizzes/` hubs. The recovery hub should include:

- calm no-shame line: `You’re not stupid. This is designed to make you hurry.`
- recovery paths by user state, not scam taxonomy:
  - clicked but entered nothing
  - entered password
  - entered card/payment details
  - downloaded file
  - called fake support number
  - sent money
  - approved login prompt
  - family member clicked
- anchor targets that videos can link to directly;
- clear `Do this first`, `What to avoid`, `When to contact provider`, and `Evidence to keep` sections;
- WebPage + FAQPage JSON-LD where appropriate.

## Visual rules

- Final visuals use high-quality prompted AI keyframes as the main visual layer.
- No self-built PowerPoint/mockup-looking final renders.
- Scam name appears only in the first visible keyframe, inside the depicted screen, in readable red text for YouTube gallery consistency.
- Do not repeat the scam-name label in every later AI image unless the user explicitly asks.
- Renderer adds only subtle motion/crossfades and clean subtitles unless a specific format requires a controlled reveal.

## Implementation pattern

For AutoShortsBot, add the format spine side-effect-free first:

1. Add enum/dataclass or typed model definitions for format metadata.
2. Add deterministic templates and a `build_first_test_wave()` style helper.
3. Add a dry/demo CLI that prints the planned wave and optional JSON.
4. Add tests for mix, field validation, first-frame-label wording, and serialization.
5. Run focused tests and the full suite before any rendering or platform side effects.

For the website:

1. Add/extend `/already-clicked/` as the recovery hub.
2. Add direct guide links from recovery CTAs to relevant red-flag pages.
3. Run build, route check, and browser console QA.

## First `already_clicked` render workflow

When producing the first recovery-format video (or adapting this pattern later), treat the format contract as a render gate, not just metadata:

1. Use a recovery script long enough for the declared duration class. For `duration_class=50-75`, probe the actual audio/render duration and block/rewrite if the first render lands around 35–45s; recovery needs space for immediate steps, what not to do, contact guidance, and evidence keeping.
2. Generate/QA premium AI keyframes before rendering:
   - first keyframe only: red in-screen scam label such as `FAKE DELIVERY LINK`;
   - later keyframes: no repeated scam-name label;
   - no real logos, URLs, QR codes, phone numbers, card/bank data, people/hands.
3. After raw keyframe QA, still inspect real MP4 QA frames with captions. Captions can cover the important screen area even when the underlying image passed.
4. Preserve `format_metadata` in the review package and upload package: `format_type`, `hook_type`, `viewer_state`, `cta_type`, `duration_class`, `website_target`, `first_frame_scam_label`, `evidence_level`, and `claim_mode`.
5. Run the YouTube private-upload dry-run with both `AUTOSHORTS_YOUTUBE_PACKAGE_DIR` and the candidate id, e.g. `python -m autoshorts.cli.youtube_private_upload_dry_run <candidate_id>`; the package directory alone is not enough.
6. Avoid committing generated media and timestamp-only topic-database churn. Commit the reusable render script / spine changes; keep videos, scene images, QA frames, and review packages as runtime artifacts unless the repo explicitly versions them.

## Pitfalls

- Do not implement 10 new hubs before content exists; start with `/already-clicked/`.
- Do not turn stories into unverifiable fake case claims. Use `based on common scam patterns` unless the case is sourced.
- Do not let quiz reveals become ugly red circles/arrows/boards; prefer zoom, crop, image transition, or voice/caption reveal.
- Do not mass-render the first five videos before the format spine and recovery website target exist.
- Do not accept a technically valid render if it violates the declared format duration. `already_clicked` is a help/recovery format; a too-short result is usually a script/pacing problem, not a harmless optimization.