# TrueTraceShorts Strategic Spine Refactor V2

Use this reference when implementing or extending AutoShortsBot / TrueTraceShorts after the strategic shift from generic AI tips to hidden digital everyday mechanisms.

## Strategic direction

TrueTraceShorts is not a narrow AI/prompt-tips channel. The channel promise is:

```text
Trace the hidden system. Fix the outcome.
```

The bot should operate as a learning editorial system, not a blind content automaton. It generates hypotheses, tests formats, blocks weak/generic content, documents learning, and only proposes the strongest candidates for human approval.

AI remains an important pillar, but should normally be about 30-40% of the mix, not the whole product.

## Sprint 1 implementation pattern

Prefer a parallel V2 strategic spine rather than breaking existing V1 models immediately:

```text
ContentBriefV2
VideoCandidateV2
StrategyScoreV2
ReviewPackageV2
ExperimentHypothesis
ClaimRisk
AIDisclosureDecision
SeriesRegistry
AudienceNeed
ViewerEmotion
SaturationRisk
HumanTexture
```

Keep the V2 spine side-effect-free: no rendering, no Telegram sends, no platform APIs, no file writes. It should define typed artifacts, validation, scoring, review formatting, and deterministic demo candidates.

## Mandatory VideoCandidateV2 fields

New candidates should require:

- `series_id`
- `audience_need`
- `job_to_be_done`
- `viewer_identity`
- `emotion_before`
- `emotion_after`
- `save_reason`
- `share_reason`
- `follow_reason`
- `search_intent_phrase`
- `saturation_risk`
- `human_texture`
- `claim_risk`
- `ai_disclosure_required`
- `experiment_hypothesis`
- `expected_winning_metric`

Also carry the hard-gate creative fields:

- `first_frame`
- `visible_fail`
- `mechanism`
- `fix`
- `before_after`
- `takeaway`
- `claims`
- `platform_fit`
- `risks`
- `visual_structure`

## Hard quality gates

A candidate must not be renderable if any of these are missing or invalid:

- concrete visible fail
- visible first-frame conflict
- mechanism
- fix/rule
- before/after
- memorable takeaway
- save reason
- share reason
- follow reason
- series fit
- claim risk assessment
- AI disclosure decision
- concrete human texture

Treat `AIDisclosureDecision.UNCLEAR` as a blocker before rendering or posting.

## Anti-AI-slop blockers

Block generic AI-hype hooks/titles and low-value structures, including:

- `Top 5 AI Tools`
- `Make money with AI`
- `This AI tool will change your life`
- `Nobody talks about this`
- `Unlock your potential`
- `You won't believe`
- generic AI hype without a concrete scene
- videos without a concrete example / human texture
- videos without a visible mechanism
- pure slideshow/text-card structures
- generic AI B-roll plus captions without motion-led mechanism reveal

## ReviewPackageV2 required contents

Telegram review packages should be strategic decision artifacts, not just pretty previews. Include:

- Candidate ID
- Version
- Script Hash
- Media Hash, if available
- Series
- Audience Need
- Viewer Emotion Before/After
- Hook
- First Frame
- Visible Fail
- Mechanism
- Fix
- Before/After
- Takeaway
- Save Reason
- Share Reason
- Follow Reason
- Claims
- Claim Risk
- AI Disclosure
- Platform Fit
- Risks
- Experiment Hypothesis
- Expected Winning Metric
- Approval Command

Approval should bind to the exact candidate version and script hash:

```text
APPROVE <candidate_id> <version> <script_hash>
REJECT <candidate_id> <reason>
REVISE <candidate_id> <field> <requested change>
```

## 100-point StrategyScoreV2

Recommended criteria:

- Problem Urgency — 15
- First-Frame Clarity — 12
- Hook Curiosity — 12
- Mechanism Value — 12
- Practical Payoff — 15
- Retention Path — 10
- Share/Save Potential — 10
- Trust/Human Texture — 8
- Series Fit — 4
- Saturation Defense — 2

A high internal score is not a publishing approval. It only means the candidate may proceed to review/render planning.

## Initial V2 series

Use these for first controlled tests:

- `ai_output_autopsy`
- `digital_red_flags`
- `decision_design`
- `workflow_teardown`
- `attention_traps`

Additional allowed series:

- `search_smarter`
- `worklife_systems`

## Demo candidate rule

When asked for sample candidates during sprint work, generate review packages only. Do not create final videos, do not call platform APIs, do not post, and do not mass-produce. Five examples across the core series are enough for validation.

## Testing pattern

Use strict TDD for the strategic spine:

1. Write tests importing the missing V2 module/API.
2. Verify RED as missing import/API or validation failure.
3. Implement side-effect-free models and validators.
4. Run focused tests.
5. Run the full suite.

Minimum tests:

- new required fields
- hard quality gates
- anti-AI-slop blockers
- `ReviewPackageV2`
- approval commands
- `StrategyScoreV2`
- `SeriesRegistry`
- deterministic demo candidates

## Pitfalls

- Do not migrate old V1 objects destructively in the first sprint. Add V2 in parallel, then migrate factories/workflows in later sprints.
- Do not confuse a review package with permission to render or publish.
- Do not allow generic AI-topic candidates to pass just because they contain the word “AI”.
- Do not treat motion as decorative pattern interrupts; motion must explain the mechanism.
- Do not let AI disclosure be a late publishing afterthought. Unclear disclosure blocks earlier.