brand-auto-tuner

Brand Auto-Tuner

The third leg of the closed-loop. After outcome_tagger labels articles as winner / mid / loser based on real GSC + AI citation data, this finds the patterns that distinguish winners and suggests brand-guideline tweaks.

When to invoke

• After 10+ articles have outcome tags (run outcome_tagger.py first)
• Monthly or quarterly, as the dataset grows
• After a major content campaign to see what worked
• Before starting a new content campaign (lock in learnings)
• /tuner or /auto-tune (user invokes)

How to invoke

# Single site
python -m scripts._core.brand_auto_tuner --site my-site

# All sites in portfolio
python -m scripts._core.brand_auto_tuner --all-sites

# Higher threshold for noisier datasets
python -m scripts._core.brand_auto_tuner --site my-site --min-per-group 10

Output

Two files per site:

• projects/{slug}/brand-tuner-report-{date}.json — full findings
• projects/{slug}/brand-guideline.diff.{date}.yaml — suggested overlay

The diff is NOT auto-applied. User reviews, then manually merges desired findings into brand-guideline.yaml.

Sample output

━━ Brand tuner: my-fishing-site ━━━━━━━━━━━━━━━━━━━━━━━
  Articles:    47 (winners 12, mid 22, losers 13)
  Confidence:  medium
  Findings:    6
  Output:      projects/my-site/brand-tuner-report-2026-05-19.json
  Diff:        projects/my-site/brand-guideline.diff.2026-05-19.yaml

  Significant patterns:
    🔴 [large ] first_person_pct
        winners have higher first_person_pct (mean 14.3 vs losers 6.2). 
        Consider targeting around 14.3 (band ±15%).
    🔴 [large ] info_gain_marker_count
        winners have higher info_gain_marker_count (mean 3.1 vs losers 1.2). 
        Consider targeting around 3.1 (band ±15%).
    🟡 [medium] tier1_citation_count
        winners have higher tier1_citation_count (mean 4.2 vs losers 2.1). 
        Consider targeting around 4.2 (band ±15%).
    🟡 [medium] format=listicle
        format='listicle' wins more often (rate 67% vs portfolio avg 26%). 
        Bias towards this format.
    🟡 [medium] ai_slop_score
        winners have lower ai_slop_score (mean 18.2 vs losers 31.5). 
        Consider targeting around 18.2 (band ±15%).
    🟡 [medium] format=how-to-guide
        format='how-to-guide' wins less often (rate 12% vs portfolio avg 26%). 
        Avoid this format.