The National team is going full-time on TrendHunter. Read this before working in the console for the first time—the shape of the work changed, even though the surfaces look familiar.
What's actually different:
data-keywords is a private dashboard at data-keywords.pierce.tools.
Strategists open it before they commit any team capacity to a topic, and it answers the question:
should we pursue this keyword space, and if so, how?
Each opportunity gets a verdict (High Opportunity, Worth Testing, Monitor, or Skip), a recommended article, a strategic context, and—once articles publish—automatically tracked outcomes that flow back in so the system gets smarter over time. (Monitor applies to Trend-Hunter-pipeline trends that sit below the search-demand floor: velocity-validated by the trend system but with no proven search demand yet—neither pursue nor skip.)
It exists so editorial decisions stop being made by gut alone and start being made with the structured signal of search demand, difficulty, authority, audience fit, and revenue potential standing right next to the gut.
| Role | Primary lens | What they do |
|---|---|---|
| Content strategist | Today's briefs | Daily triage—Keep / Skip / Defer |
| Content team lead | Beach | Weekly mix planning per collection |
| Exec / strategist | Gap map | Monthly portfolio review |
| Anyone post-publish | Decisions | Capture article outcomes (PV, position, headline grade) |
| New team member | Docs | Read this. Then ask questions. |
The console uses a handful of recurring terms—KD, CPC, volume, head/mid/long-tail, T1/T2/T3, persona, eCPM. Every glossary entry below assumes these are unfamiliar. Read this once and the rest will make sense.
What it is. Estimated number of times a search query is typed into Google per month, globally or per country. SEMrush calls it "volume." When the console shows vol 12,000 it means about 12,000 searches per month for that exact query.
Why it matters. Volume is the demand side of the keyword. No volume = no audience. High volume = lots of audience, but probably also lots of competing publishers.
Source. SEMrush phrase_fullsearch endpoint at brief-pull time. Refreshes monthly for Kept briefs.
What it is. SEMrush's 0–100 score for how hard it is to rank on the first page of Google search results for a given keyword. 0 = trivial (you'll rank if you publish anything competent). 100 = effectively impossible (Wikipedia, NIH, and the New York Times own page 1, and they're not letting go).
How it's computed (under the hood). SEMrush combines: (1) authority of the domains currently ranking, (2) backlink counts of the current top-10 results, (3) on-page content depth, (4) topical-cluster strength, (5) some proprietary weighting. Operators don't need to compute it—SEMrush returns it as a finished number.
Practical rules of thumb.
What it is. What advertisers pay Google, on average, for a single click on a paid ad against this keyword. Reported in US dollars by SEMrush.
Why it matters here. We don't run paid ads—we use CPC as a commercial-intent signal. High CPC means advertisers see commercial value (e.g., people who search "best mattress for back pain" are about to spend money). High CPC keywords usually translate to higher organic ad revenue too, because the same advertisers are buying programmatic display next to our articles.
{/* docs-link: every cross-anchor link in this lens is aSame blurbs surface via the (?) icon next to each lens title in the console. Click to pop a panel with the same content, in case you forget mid-flow.
{b.body}
{b.useWhen}
A flat list, sorted with undecided High Opportunity briefs first, then Worth Testing, then Skip. Decided briefs sink to the bottom but stay visible. The daily driver—open it, work top-down, hit the bottom, you're done.
The left rail is your filter surface: trend search, decision state, verdict, collection, and the optional persona-fit overlay (off by default).
Header has: a sort picker (primary + optional secondary key), a "focus on top 15" toggle (off by default—you see the full inventory), and the (?) help bubble.
Briefs grouped by TH Collection (Mind & Body / Experiences / Everyday Living). Within each collection, three difficulty rails:
The lock isn't bureaucracy—it's the system saying "you don't have the authority to win these yet, spend that effort on the rail you can win."
Production-mix tracker at the top shows progress against the 60% Ready / 30% Building / 10% Earned target.
Volume × difficulty quadrants. Where a brief lands tells you what to do with it.
Use it monthly+ for strategic review. Is the brief inventory shape-right? Are there empty quadrants signaling under-investment?
Every decision lands here automatically—kept, skipped, or deferred. After an article ships, re-open the brief and fill in the outcome form (page views, final position, headline grade). Those numbers feed the Phase-5 learning loop that recalibrates the engine.
Decisions persist across browsers, devices, and team members. Sync indicator in the footer (● decisions synced) confirms the worker is alive.
The closed brief shows you everything you need to triage in one horizontal scan:
Click a brief or hit Enter on a focused tile to open the drawer. Layout:
Every section heading has a (?) bubble explaining what's shown and how it's computed.
Three decision buttons, plain meaning:
You can change your mind by clicking another action. Decisions persist server-side instantly (sync pill in footer confirms)—no need to remember to save.
Outcome capture (PV, position, headline grade) appears once a brief is Kept. Filling these in feeds the Phase-5 calibration loop.
The engagement pill on a brief tile shows up two ways: full color (live data) or faded with a small asterisk (proxy estimate). It's not a styling glitch—it tells you whether the number is observed or estimated. This is one of the more easily-missed signals; learn to read it.
Meaning. McClatchy has already published one or more articles whose keyword space matches this brief. Engagement metrics are pulled from ARTICLE_ENGAGEMENT_SIGNALS in Snowflake (Amplitude-derived) and joined to those matched articles. Numbers reflect actual reader behavior: time-on-page, pvs/session, scroll depth.
How to read it. Trust the score directly. A live engagement of 72 means real readers spent real time engaging. Higher = stronger.
Meaning. No published McClatchy article matches this brief's keyword space yet—most V5 briefs are greenfield. The engagement pill in this state is a directional placeholder, derived from function(KD, persona-fit, content-type). It's a guess, not an observation.
How to read it. Use it for relative ordering across briefs, not as ground truth. A proxy 60 vs a proxy 40 still tells you the first looks more promising—but both could land elsewhere when the article actually publishes.
Mixing live and proxy signals lets the operator triage greenfield briefs without losing the comparative shape. The fade + asterisk make the data quality visible at a glance—you can never accidentally treat a proxy as live, but you also don't lose the signal entirely just because no article exists yet.
Once a McClatchy article publishes whose keywords overlap this brief's keyword cluster, the daily Layer-7 cron picks it up and the pill flips to live on the next page load. No operator action—happens automatically within ~24 hours of publication.
The Engagement signal panel inside the drawer shows the same source flag, but with full per-metric breakdown. When live, you see actual time-on-page numbers per matched article. When proxy, you see the derivation reasoning (KD-X, persona-fit-Y, content-type-Z → score).
Three orthogonal mechanisms for narrowing a long list. Filters cut briefs out, sort reorders what remains, focus mode caps the count. Combine freely.
Each filter is independent and they AND together—Collection=Mind & Body + State=undecided + Verdict=High Opportunity shows the intersection of all three.
| Filter | Values | What it does | Implications | Revert |
|---|---|---|---|---|
| Trend search | Free-text | Text match against topic + recommended article + keyword labels | Soft filter: matched briefs highlight, unmatched dim but stay visible. Doesn't actually remove briefs—useful for "find this one quickly" without losing your place in the queue. | Clear the search box (X icon or empty the field). |
| Decision state | any · undecided · kept · skipped · deferred | Filter by what you've already done with the brief | Default = any. Set to "undecided" for daily triage. Set to "kept" before a refresh week. Set to "skipped" to revisit rejection rationale during a calibration cycle. | Set back to "any" or use the lens's reset chip. |
| Verdict | all · high opportunity · worth testing · monitor · skip | Filter by computed verdict | Useful when you only have time for High Opportunity work today. Note: verdict is recomputed at runtime against current cohort, so a brief's verdict can shift between sessions if cohort composition changes. | Set back to "all." |
| Collection | all · Mind & Body · Experiences · Everyday Living | Filter to one TH Collection | Use for collection-specific weekly planning. The Beach lens is collection-grouped natively; this filter is most useful in Today's briefs and Gap map. | Set back to "all." |
| Persona fit | any · high · medium · low | Filter by persona-fit level vs current persona | Only visible when Persona overlay is ON (off by default, toggle in the operator panel). When on, set to "high" to see only briefs that resonate strongly with Curious Optimizer (or whichever persona is active). | Set back to "any"—or turn the overlay off entirely if you don't want persona-fit influencing triage. |
Sort has a primary key + optional secondary tiebreaker key. Each has its own asc/desc toggle. Default sort uses the lens's native triage ordering (verdict → vol for Today's briefs).
Sort dimensions:
The secondary tiebreaker only kicks in when primary values tie—useful when many briefs share a tier or verdict.
Default: off. Strategists see the full inventory of briefs (~43 V5 + intake). Toggle on to cap the visible queue at 15 (intake first, queue fills the rest).
Use when: the inventory is overwhelming and you want a "top 15 to triage today" surface. Pairs well with sort=default and decision-state=undecided.
Revert: toggle off to see the full inventory again. Toggling does not delete or modify any briefs—purely a display cap.
Common filter combinations and what they surface. Use these as starting points; tune as needed.
State=undecided · Verdict=any · Collection=any · Focus mode=on
Shows the next 15 briefs you haven't decided on yet, with the strongest opportunity at the top. The daily-driver default.
State=undecided · Verdict=high opportunity · Focus mode=off
Surfaces every undecided High Opportunity brief—these are the candidates worth committing to so they enter the monthly SEMrush refresh scope.
State=skipped · Verdict=any · sort=primary tier · sort=secondary volume
Surfaces every brief I've skipped, sorted by tier then volume—useful for a calibration-cycle review of "did I skip too aggressively?"
Collection=Mind & Body · State=any · sort=tier asc · sort=volume desc
All Mind & Body briefs, easiest tier first, highest volume within tier—the production-mix planning view. Better in Beach lens (which already groups by collection + tier rail).
Trend search="creatine" (or whatever keyword)
Soft-highlights matching briefs without filtering the rest out. Useful when you remember a topic but not the brief title.
Persona overlay=ON · Persona fit=high · Verdict=high opportunity · State=undecided
Shows undecided briefs that both score well by formula AND match persona vocabulary strongly. The "no-brainer" set.
State=any · sort=projected revenue desc
Sorted by max-pub theoretical revenue. Read with caution—projection assumes the article ranks at expected position, and ETRP found composite scores are uncorrelated to anti-correlated with actual PV.
Each sort dimension has a different "shape" of brief at the top. Knowing what surfaces helps you pick the right one.
| Sort | What sits at the top (desc) | What sits at the top (asc) | Best paired with |
|---|---|---|---|
| default | Undecided High Opportunity, highest volume | Skipped briefs, lowest volume | Daily triage with state=undecided |
| tier | T3 (long game; rarely useful) | T1 first—this is the natural use | Production-mix planning in Beach lens |
| volume | Highest-demand head/midtail keywords | Smallest-volume longtail | "What's the biggest opportunity by raw demand?" |
| KD | Hardest first (KD 80+, mostly auto-skip) | Easiest first—natural Beach Ready-now ordering | "What can we win this week?" |
| CPC | Highest commercial intent—health-wellness, financial-services dominate | Lowest commercial intent—entertainment, food | "Where's the ad money?" |
| engagement | Live high-engagement (real reader behavior) or strong proxy | Faded proxies and weak live signals | "What do readers actually finish?" |
| persona fit | High-fit Curious Optimizer briefs | Low-fit (not for this persona) | Persona-led editorial targeting |
| projected revenue | Highest theoretical upside (vol × CTR × eCPM) | Smallest projection | Caveat: projection ≠ outcome (per ETRP) |
| cluster opportunity | Richest sweet-spot clusters (10+ keywords with vol≥500 AND KD≤29) | Thinnest clusters | Cluster-scale content commitments |
Every operator action in the console is reversible. Here's how to undo each one.
Open the brief drawer and click any other action button. Decision overwrites are instant—the new state is written to D1 and the previous one moves to the audit log (decision_history). To fully clear a decision (return to undecided): there's no UI button currently; operator can DELETE via API:
{`curl -X DELETE \\
-H "X-Auth-Token: $WRITE_TOKEN" \\
https://data-keywords-decisions.pierce-williams.workers.dev/decisions/`}
Audit log retains the full history; the live decisions row is removed.
Open the brief drawer, scroll to the outcome capture form, edit values, save. Old values move to decision_history; new values become live. There's no "delete outcome only" path—clear all decision data via API DELETE if needed.
Open the brief drawer, click the TVE control, set to "off." The flag is part of the decision row; saving rewrites it. Audit log retains prior TVE state.
Click the filter chip's X, or set the dropdown back to "all" / "any." Filters are session-only—they don't persist across page reloads.
Toggle off in the lens header. Display-only setting, doesn't modify briefs.
Open the operator panel (⚙ icon top-right), toggle the overlay off. Overlays change which pills appear on the tile and which panels appear in the drawer. Disabled overlays don't influence sort or filter availability.
If something feels deeply wrong: open browser devtools console and run localStorage.clear() followed by hard-refresh. This wipes session UI state (filters, overlays, sort selections) but does NOT touch decisions—those live in D1, separate from browser state.
Verdicts aren't operator-mutable. They recompute every page load against the current cohort. To override a verdict in practice, ignore it and Keep / Skip on your own judgment—your decision and rationale are the highest-signal feedback the engine gets and feed Phase-5 calibration.
Small circles next to most labels. Click to pop a panel with: what this is, how it's computed, an optional caveat note. Click outside or hit Esc to close.
These exist on:
Same content surfaces in this Docs lens too—single source of truth in util.js, can't drift between surfaces.
Click Keep / Skip / Defer → the decision is written to a D1 database running on Cloudflare. It persists across browsers, devices, and team members. Multiple operators can click concurrently without conflicts.
The footer pill confirms sync state:
Audit trail: every change is appended to a decision_history table. Operators can query "who decided what when" via the worker; technical-spec section has the queries.
~/Downloads/, then ingest script.etrp · 30/50/20 · 75/10/10/5 · cuts refined with a date. If it's missing, the Pages deploy may not be current.window.BRIEFS is undefined, data/briefs.js failed to load. Network tab → check that file is loading.curl https://data-keywords-decisions.pierce-williams.workers.dev/healthThat brief got a High Opportunity verdict from the formula, but no portfolio pub ranks in the top 50 of any of its keywords. KD is also moderate-to-high. Translation: opportunity surface is real, but you'd be entering against entrenched competitors with no existing authority. Recommended path: publish a few longtail-niche articles first, earn a top-50 ranking somewhere, then scale up. Stage the bet rather than going in cold. Click the (?) next to the badge for more.
Should be fixed by the container-query CSS update (2026-04-29). If you still see this, hard-refresh. The drawer auto-stacks vertically when the brief container is narrower than 720px.
MSN platform reach is sourced from a weekly Tarrow XLSX export, not the daily Snowflake feed. When the latest Tarrow upload is missing, MSN data won't appear. The other off-O&O platforms (Apple News, SmartNews, NewsBreak, Yahoo) come from Snowflake daily and aren't affected.
No published articles match this brief's keyword space yet, so the live engagement data doesn't exist. The console falls back to a proxy derived from KD + persona-fit + content-type as a directional placeholder. The proxy clears automatically when articles ship and TRACKER_ENRICHED has matches.
Footer shows running spend against the 250K monthly cap. Monthly refresh on the 1st burns ~3K per Kept brief. With 0 Kept briefs, monthly cron is a no-op. With ~10 Kept briefs, ~30K monthly burn—comfortable headroom.
Yes, always. The verdict is a recommendation, not a gate. You can keep a Skip or skip a High Opportunity brief. Both decisions feed the engine equally; overrides with rationale are the highest-signal feedback we have.
The verdict is opportunity-surface assessment, not PV prediction. ETRP analysis on 1,062 historical articles found scoring is uncorrelated to anti-correlated with actual PV outcomes. Use the verdict to identify where to attack; execution + angle + timing determine hit rate.
In a Cloudflare D1 database, written on every click. Cross-browser, cross-device, cross-team-member. See .
Pierce Williams, Director of Content Standards & Pipeline Quality at McClatchy. Slack #data-keywords for questions / feedback / bugs.
Operator (Pierce) adds it to the seed list in scripts/pull_th_v5.py and runs the script. The new brief appears with full SEMrush data on next page load. See .
Briefs you haven't actively Kept aren't in the monthly refresh scope. Click Keep on briefs the team is committing to—they'll be auto-refreshed on the 1st of each month. Briefs you Skip or Defer never refresh until you un-do that decision.
Five distinct systems, glued together via daily/monthly crons + a real-time worker.
{`┌─────────────────┐ reads on load, ┌──────────────────────┐
│ Console │ writes on click │ Decisions Worker │
│ (CF Pages) │ ──────────────▶ │ (CF Worker + D1) │
│ React + Babel │ │ pierce-williams. │
│ CDN, no build │ ◀────────────── │ workers.dev │
└────────┬────────┘ bootstrap state └──────────┬───────────┘
│ │
│ reads window.BRIEFS │ /decisions/kept
▼ ▼
┌────────────────┐ daily ┌─────────────────────────┐
│ docs/data/ │ ◀─────────── ─ │ GitHub Actions cron │
│ *.js (briefs, │ bot commits │ daily 8:13am Dallas │
│ outcomes, etc) │ │ monthly 1st 8:13am │
└────────┬───────┘ └────────┬────────────────┘
│ │ uses
│ via snowflake-tracker-sync ▼
▼ ┌──────────────────┐
┌─────────────────┐ │ Snowflake │
│ TRACKER_ENRICHED│ ◀───────────────│ MCC_PRESENTATION │
│ ARTICLE_ENG_SIG │ └──────────────────┘
└─────────────────┘ ┌──────────────────┐
│ SEMrush API │
│ 250K units/month │
└──────────────────┘`}
| File | Source | Refresh cadence | Cost |
|---|---|---|---|
briefs.js | SEMrush phrase_fullsearch + phrase_kdi + phrase_organic | Manual (initial seed) + monthly cron (Kept briefs only) for competitors + ourPos | ~3K credits / Kept brief / month |
brief-outcomes.js | Snowflake TRACKER_ENRICHED | Daily 8:13am Dallas | $0 SEMrush |
gsc-authority.js | Snowflake SEARCH_ANALYSIS_RPT (WEB, 28d window) | Daily 8:13am Dallas | $0 SEMrush |
engagement-signals.js | TRACKER_ENRICHED + ARTICLE_ENGAGEMENT_SIGNALS | Daily 8:13am Dallas | $0 SEMrush |
author-authority.js | TRACKER_ENRICHED + ARTICLE_ENGAGEMENT_SIGNALS (author-grouped) | Daily 8:13am Dallas | $0 SEMrush |
brief-revenues.js | TRACKER_ENRICHED v2.7 (BURT_INTELLIGENCE_REV joined) | Daily 8:13am Dallas | $0 SEMrush |
outlet-ecpm-live.js | TRACKER_ENRICHED v2.7 (BURT-derived per-domain eCPM) | Daily 8:13am Dallas | $0 SEMrush |
tarrow-syndication.js | Manual XLSX from Top Stories 2026 Syndication gsheet | Weekly (operator export) | $0 SEMrush |
verdict-thresholds.js | ETRP calibration script | Phase-5 (≥3 months of decision data) | ~36K credits per ETRP run |
compounding-curves.js | ETRP Step 1 Snowflake pull | Quarterly (when ETRP re-runs) | $0 SEMrush |
| D1 decisions | Operator clicks (Keep / Skip / Defer / outcome capture) | Real-time | $0 (D1 free tier) |
{`data-keywords/
├── docs/ # Cloudflare Pages site root
│ ├── index.html
│ ├── css/styles.css # all styling
│ ├── data/
│ │ ├── briefs.js # window.BRIEFS—single source of truth
│ │ ├── verdict-thresholds.js # ETRP-validated weights + cuts
│ │ ├── compounding-curves.js # historical curves from ETRP Step 1
│ │ ├── brief-outcomes.js # Layer 0 daily output
│ │ ├── gsc-authority.js # Layer 6 daily output
│ │ ├── engagement-signals.js # Layer 7 daily output
│ │ ├── author-authority.js # Layer 9 daily output
│ │ ├── brief-revenues.js # Layer 10 daily output (live BURT)
│ │ ├── outlet-ecpm-live.js # daily live BURT eCPM (replaces static)
│ │ ├── tarrow-syndication.js # Layer 8 weekly manual
│ │ └── worker-config.js # decisions worker URL + shared bearer (CF Access gated)
│ │ # (decisions.js placeholder + briefs-v3-archive.js moved to docs/_archive/ on 2026-05-04)
│ └── js/
│ ├── util.js # everything: helpers, scoring, registries
│ ├── brief.jsx # brief tile + drawer + LensHelp
│ ├── lenses.jsx # all 5 lenses + command palette
│ ├── docs.jsx # this file
│ ├── tweaks-panel.jsx # operator tuning panel
│ └── app.jsx # app shell + state
├── scripts/ # Python pull / processing scripts
│ ├── pull_th_v5.py # full V5 SEMrush pull
│ ├── backfill_competitors.py # phrase_organic top-10 per kw
│ ├── backfill_positions.py # phrase_organic top-50 per kw → ourPos
│ ├── ingest_tarrow_syndication.py # weekly XLSX → tarrow-syndication.js
│ ├── precompute_brief_outcomes.py # Layer 0
│ ├── precompute_gsc_authority.py # Layer 6
│ ├── precompute_engagement.py # Layer 7
│ ├── precompute_author_authority.py # Layer 9
│ ├── precompute_brief_revenue.py # Layer 10 (live BURT $/brief)
│ ├── precompute_outlet_ecpm.py # daily live BURT eCPM
│ ├── analyze_skip_patterns.py # weekly skip-rationale analysis
│ ├── generate_drift_report.py # weekly drift report
│ ├── extract_compounding_curves.py # weekly curve refresh
│ ├── repull_weak_briefs.py # multi-seed re-pull for weak briefs
│ └── check.sh # quality gate
├── calibration/ # ETRP recalibration pipeline
│ ├── PIPELINE.md
│ ├── STATUS.md
│ └── scripts/
│ ├── 00-check-credits.py
│ ├── 01-pull-snowflake.py
│ ├── 02-tag-content-types.py
│ ├── 03-outcomes-confounds-keywords.py
│ ├── 05-semrush-pull.py
│ ├── 06-fit-ensemble.py
│ ├── 07-cv-validate.py
│ ├── 11-commit.py
│ └── recalibrate.py
├── workers/decisions/ # Cloudflare Worker (D1 + REST API)
│ ├── src/index.js
│ ├── schema.sql
│ ├── wrangler.toml
│ ├── package.json
│ └── README.md
└── .github/workflows/
├── learning-loop.yml # Layers 0/6/7/9 daily
└── monthly-semrush-refresh.yml # Kept briefs refresh on 1st of month`}
Cloudflare Worker bound to a D1 database. Single source of truth for operator decisions.
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | none | Liveness |
| GET | /decisions | none | Full decisions map |
| GET | /decisions/kept | none | Brief IDs with action='keep' (used by cron) |
| GET | /decisions/:briefId | none | Single decision |
| POST | /decisions/:briefId | X-Auth-Token | Upsert decision |
| DELETE | /decisions/:briefId | X-Auth-Token | Clear |
{`CREATE TABLE decisions (
brief_id TEXT PRIMARY KEY,
action TEXT, -- 'keep' | 'skip' | 'defer' | null
ts INTEGER, -- epoch ms of last update
note TEXT, -- operator rationale
tve TEXT, -- 'rising' | 'flat' | 'declining' | null
outcome_pv INTEGER,
outcome_position INTEGER,
outcome_headline_grade TEXT,
updated_by TEXT
);
CREATE TABLE decision_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
brief_id TEXT NOT NULL,
ts INTEGER NOT NULL,
action TEXT,
-- ... (full audit log; append-only)
);`}
{`# View current decisions
curl https://data-keywords-decisions.pierce-williams.workers.dev/decisions | jq
# Just kept brief IDs (what cron reads)
curl https://data-keywords-decisions.pierce-williams.workers.dev/decisions/kept | jq
# Audit log—last 50 changes
wrangler d1 execute data-keywords-decisions --remote \\
--command "SELECT * FROM decision_history ORDER BY ts DESC LIMIT 50"
# Tail worker logs
wrangler tail`}
Three SEMrush API endpoints used. Each call costs units that count against the 250K monthly cap.
| Endpoint | Cost | Used by |
|---|---|---|
phrase_fullsearch | 20 units / line returned (40 results = 800 units) | Initial brief seeding (volume + CPC + intent per keyword) |
phrase_kdi | 50 units / keyword (15 keywords = 750 units) | Initial brief seeding (KD score per keyword) |
phrase_organic | 10 units / line returned (10 results = 100 units; 50 results = 500 units) | Competitor + ourPos backfill |
| Script | Replaces or merges | Cost per brief | Use when |
|---|---|---|---|
pull_th_v5.py | Full replace (briefs.js) | ~1.5K (fullsearch + kdi) | Initial seeding, adding new TREND_UNITS, refreshing vol/KD drift |
backfill_competitors.py | Merge in place | ~500 (phrase_organic top-10 × 5 keywords) | Refresh competitor domains |
backfill_positions.py | Merge in place | ~2.5K (phrase_organic top-50 × 5 keywords) | Refresh ourPos (portfolio rankings) |
repull_weak_briefs.py | Merge in place | varies | Multi-seed re-pull for briefs whose initial seed underperformed |
{`--scope=all # default: refresh every brief in briefs.js
--scope=kept # cron default: query worker, refresh only Kept briefs
--scope=brief:ID,ID,... # ad-hoc operator-targeted refresh`}
Pre-flight discipline: validate seeds in SEMrush Keyword Magic Tool before any new pull. Bad seeds waste ~800 units per phrase_fullsearch call.
Five-layer learning loop. Each layer is a Python script that runs on a schedule, reads from Snowflake, writes to a JS file the console picks up on next page load.
| # | Layer | Cadence | Output | Snowflake table |
|---|---|---|---|---|
| 0 | Brief outcomes | Daily 8:13am | brief-outcomes.js | TRACKER_ENRICHED (180d) |
| 1 | Drift report | Mon 8:17am | reports/drift.md | (reads decision history) |
| 2 | Skip-pattern analysis | Mon 8:17am | reports/skip-patterns.md | (reads decisions + outcomes) |
| 3 | Recalibration trigger check | 1st 9:17am | workflow signal | (reads decision count) |
| 4 | Compounding-curve refresh | Mon 8:17am | compounding-curves.js | TRACKER_ENRICHED (180d, ETRP cohort) |
| 6 | GSC authority | Daily 8:13am | gsc-authority.js | SEARCH_ANALYSIS_RPT WEB (28d) |
| 7 | Engagement signals | Daily 8:13am | engagement-signals.js | TRACKER_ENRICHED + ARTICLE_ENGAGEMENT_SIGNALS (90d) |
| 8 | Tarrow syndication | Manual weekly | tarrow-syndication.js | (XLSX, off-Snowflake) |
| 9 | Author authority | Daily 8:13am | author-authority.js | TRACKER_ENRICHED + ARTICLE_ENGAGEMENT_SIGNALS (180d) |
| 10 | Brief revenue (live BURT) | Daily 8:13am | brief-revenues.js | TRACKER_ENRICHED v2.7 (BURT_INTELLIGENCE_REV joined) |
| — | Outlet eCPM live | Daily 8:13am | outlet-ecpm-live.js | TRACKER_ENRICHED v2.7 (BURT, per-domain) |
Resilience: each precompute step in learning-loop.yml runs with continue-on-error: true. A single layer failing (Snowflake auth flicker, transient outage) does not kill the whole run—prior committed data stays in place; the console keeps rendering until the next clean cycle. Output validation gates the commit, so a malformed or empty JS file never reaches main.
All scheduled off-the-hour because GitHub silently drops top-of-hour scheduled runs. Times in UTC; Dallas equivalents in parens.
| Workflow | UTC cron | Dallas time | Purpose |
|---|---|---|---|
learning-loop.yml daily-outcomes | 13 13 * * * | Mon-Sun 8:13am | Layers 0/6/7/9 |
learning-loop.yml weekly-drift | 17 13 * * 1 | Mon 8:17am | Layers 1/2/4 |
learning-loop.yml monthly-recalibration | 17 14 1 * * | 1st of month 9:17am | Layer 3 gate check |
monthly-semrush-refresh.yml | 13 13 1 * * | 1st of month 8:13am | Refresh competitors + ourPos for Kept briefs |
Concurrency: each workflow uses a concurrency group to prevent overlap. Manual dispatch always available via gh workflow run or the Actions UI.
DST: cron times are UTC-fixed; Dallas time shifts ±1h with DST changes. Adjust manually if needed.
| Secret | Used by | Source |
|---|---|---|
SEMRUSH_API_KEY | monthly-semrush-refresh.yml + manual scripts | SEMrush account dashboard |
SNOWFLAKE_RSA_KEY_B64 | learning-loop.yml all jobs | base64 < ~/.credentials/growth_strategy_service_rsa_key.p8 |
SLACK_WEBHOOK_URL | both workflows (failure notifications) | Slack incoming-webhook URL—channel of operator's choice |
| Secret | Worker | Source |
|---|---|---|
WRITE_TOKEN | data-keywords-decisions | openssl rand -hex 32 |
docs/data/worker-config.js—decisions worker URL + token (committed; CF Access protects access)workers/decisions/wrangler.toml—D1 binding, deploy configscripts/pull_th_v5.py top—TREND_UNITS list (operator edits to add/remove seeds)Auto-deploys on push to main. No manual step. CF Pages reads docs/ and serves it. Live within ~1 min of push.
{`cd workers/decisions
npm install
wrangler d1 create data-keywords-decisions # one-time
# paste returned id into wrangler.toml
npm run db:init-remote
openssl rand -hex 32 | pbcopy
wrangler secret put WRITE_TOKEN # paste at prompt
npm run deploy
# Update docs/data/worker-config.js with deployed URL + token
git add . && git commit -m "wire decisions worker" && git push`}
{`export SEMRUSH_API_KEY=xxx
# Full V5 pull (initial seeding or seed-set update)
python3 scripts/pull_th_v5.py
# Backfill competitor domains
python3 scripts/backfill_competitors.py --scope=all
python3 scripts/backfill_competitors.py --scope=brief:rl-sleep-performance,wh-hormone-health
python3 scripts/backfill_competitors.py --scope=kept
# Backfill ourPos (portfolio SERP positions)
python3 scripts/backfill_positions.py --scope=all
python3 scripts/backfill_positions.py --scope=kept
# Then commit + push
git add docs/data/briefs.js && git commit -m "data: refresh" && git push`}
Run before every commit. scripts/check.sh validates:
Plus session-level checks via /sync-repos in ops-hub:
Both fail-closed: any hit blocks the push.
Quick definitions of the recurring terms. The full primer with examples lives in ; this entry is the at-a-glance reference.
| Term | Stands for | Range | Direction | Source |
|---|---|---|---|---|
| vol | Monthly search volume | 0 – ∞ (typical 100 – 1M) | Higher = more demand | SEMrush phrase_fullsearch |
| KD | Keyword Difficulty | 0 – 100 | Lower = easier to rank | SEMrush phrase_kdi |
| CPC | Cost Per Click | $0.00 – $30+ | Higher = more commercial intent | SEMrush phrase_fullsearch |
| head | Headtail keyword | Single word or 2-word generic | Highest vol, brutal KD | Console classification (vol + word count) |
| mid | Midtail keyword | 3–4 word specific phrase | Moderate vol, winnable KD—sweet spot | Console classification |
| long | Longtail keyword | 5+ word very-specific phrase | Low vol, low KD, high conversion intent | Console classification |
| our pos | Best portfolio rank for this keyword | 1–50, or 999 = unranked top-50 | Lower = better | SEMrush phrase_organic top-50 |
| eCPM | Effective cost per 1000 impressions | $0.50 – $10 typical | Higher = more revenue per pv | |
| CTR | Click-through rate at SERP position | 0% – 28% | Position 1 = 28%, position 10 = ~3% | Industry CTR curve |
What it signifies. The small pill on every brief tile that summarizes the brief's difficulty classification per the TH Keyword Selection Framework v1. Three states (T1 / T2 / T3) plus two suffixes (down-arrow, DA-shifted) that modify how to read the tier. At-a-glance answer to "how hard is this brief and should we attack it now?"
| Pill | Meaning | What to do |
|---|---|---|
| T1 | Tier 1 · Go Now. Avg KD 0–29. Production-mix target 60%. | Today's working surface—write these. Easy SERPs we can win immediately. |
| T2 | Tier 2 · Build Into. Avg KD 30–49. Target 30%. | Locked in Beach lens until rolling-unlock fires (≥6 keeps in the collection in last 60d). Once unlocked, midtail wins that compound authority. |
| T3 | Tier 3 · Long Game. Avg KD 50+. Target 10%. | Locked until higher rolling-unlock threshold (≥15 keeps). Stretch SERPs that need cluster-scale commitment + freshness loops. |
| T1 ↓ (down-arrow) | Per-keyword tier is T1 but the cluster check failed—fewer than 10 sweet-spot keywords (vol ≥ 500 AND KD ≤ 29) OR combined sweet-spot volume < 10K. | Don't treat as a true T1—cluster is too thin for cluster-scale commitment. You might still write the one strong article, but don't plan a cluster around it. |
| T2 ↓ | Same superseded-by-cluster pattern at T2—the per-keyword math says T2 but cluster richness doesn't support cluster-scale work. | Treat as a candidate for narrow-execution rather than cluster-scale commitment. |
| Tier with "DA-shifted from X" tag | Effective tier improved on a specific pub thanks to GSC-observed authority. E.g. "T2 (DA-shifted from T2 on miamiherald.com)" means Miami Herald has enough adjacent ranking authority to attack the brief like a T1. | Route the brief through the named pub—they have the foothold the math needs. |
How it's sourced. Computed at runtime from the brief's avg KD via classifyTier() in util.js. Cluster check (the down-arrow trigger) runs clusterOpportunityScore() on the keyword cluster. DA-shift (the suffix tag) reads GSC authority data via daBonusFromGsc() + classifyTierWithDaBonus(). All three live in util.js; thresholds in TIER_RULES + TIER_1_CLUSTER_MIN.
Why it matters. Tier is the single most actionable summary the engine produces. Without the down-arrow + DA-shift modifiers, a tier label can be misleading—a T1 brief whose cluster won't support cluster-scale commitment looks like a slam-dunk but isn't, and a T2 brief that a specific pub can win like a T1 looks like "wait for unlock" when in reality "send to that pub today." The pill format compresses three correlated facts (raw tier, cluster richness, per-pub authority bump) into a single glance so triage is fast and accurate.
How to interpret it. Read T1 / T2 / T3 as the base. Down-arrow = "the per-keyword math says this tier but the cluster is too thin to commit cluster-scale." DA-shifted = "this pub specifically can attack a tier above what raw KD suggests." Drawer's TH Framework v1 panel shows the full breakdown—cluster keyword count, sweet-spot volume, per-pub authority detail. Use the pill for fast triage; use the panel when you want to understand the underlying judgment.
What it signifies. A single number between 0 and 1 attached to every brief. Think of it as a "how attractive does this opportunity look on paper?" number. Higher means the engine sees more raw opportunity (lots of search demand, low difficulty, decent commercial intent). Lower means the opposite. It is not a forecast of how many page views the article will get—it's a pre-commitment scoring signal.
How it's sourced. Computed at runtime from four ingredient signals, weighted into a single number:
{`composite = volume_norm × 0.75
+ inv_kd_norm × 0.10
+ cpc_norm × 0.10
+ residual_norm × 0.05`}
Volume = monthly searches (log-normalized so it doesn't blow out the scale). Inv-KD = 1 minus keyword-difficulty (so easier KDs score higher). CPC = cost-per-click as a commercial-intent proxy, normalized against per-vertical anchors. Residual = small confidence + persona-fit nudges. Weights live in docs/data/verdict-thresholds.js → weights.default.weights; can be re-calibrated by the ETRP pipeline. Surfaces in the verdict-breakdown panel inside the brief drawer (Score components table) plus drives the verdict label on the tile.
Why it matters. The composite is the single number that determines whether a brief gets a High Opportunity, Worth Testing, or Skip verdict (cohort percentile cuts at 30/50/20; a below-floor TH-pipeline trend gets Monitor instead). It's the engine's editorial vote—"if you only have time for the strongest opportunities, work down from the top of this list." Without it the operator has to weigh four signals manually for every brief, which doesn't scale to a 43-brief inventory.
How to interpret it. Read it as a "where to attack" prioritizer, not a PV predictor. ETRP validation against 1,062 historical McClatchy articles found that the composite score had a slight negative Spearman correlation with actual page views (−0.19 to −0.31)—meaning historically ambitious high-score picks underperformed lower-score picks, almost certainly because high-score topics drew stiffer SERP competition. So: trust the composite to tell you where the surface looks promising, but don't let it predict outcomes. Execution + angle + timing determine the actual hit rate. See .
What it signifies. The "volume" component of the composite score. It takes the raw monthly-search-volume number from SEMrush (e.g. 12,000 searches/month) and converts it to a 0-to-1 score so it can be combined with the other ingredients. Without normalization, a single 800,000-search head term would drown out every other signal in the composite.
How it's sourced. SEMrush phrase_fullsearch returns a monthly-volume number per keyword at brief-pull time. The console aggregates that across the brief's keyword cluster, then runs it through this transform:
{`if volume < 500: volume_norm = 0 # below auto-skip floor
else: volume_norm = min(1, log10(volume / 500) / log10(200))
# 500 monthly searches → 0
# ~7,000 → ~0.5
# 100,000 → 1.0 (saturation cap)
# 800,000 → still 1.0 (no double-credit for outliers)`}
Why it matters. Search volume is heavy-tailed—most keywords sit in the hundreds-to-low-thousands range while a few head terms sit at 100K+. If we used the raw number, a single mega-volume keyword would dominate the composite score regardless of difficulty or relevance. The log transform compresses the tail so a 7K-vol midtail keyword gets a meaningful 0.5 score while a 100K-vol headtail keyword gets a 1.0—penalizing diminishing returns. Below 500/month is treated as zero opportunity (matches the hard auto-skip volume floor).
How to interpret it. If you see the score-components panel showing volume_norm = 0.5, that brief sits roughly at "decent midtail demand" (~7K monthly searches). 1.0 means "saturated head-term demand" (≥100K). 0 means "below the noise floor of 500/month—not worth pursuing on volume grounds alone." A higher number on its own doesn't mean the brief is winnable—it just means the demand exists. Always read it alongside KD.
What it signifies. The "how easy is this to rank for?" component of the composite. KD itself runs 0 (trivial) to 100 (effectively impossible). We invert it so that higher means easier—which keeps every composite ingredient pointed in the same direction (higher = better opportunity).
How it's sourced. SEMrush returns a KD number per keyword via the phrase_kdi endpoint at brief-pull time (50 SEMrush units per keyword). KD itself is a SEMrush proprietary composite of: domain authority of the sites currently ranking, backlink counts of top-10 results, on-page content depth, topical-cluster strength, and some additional weighting. The console takes the brief-level average KD and converts it linearly:
{`inv_kd_norm = max(0, 1 − KD/100)
# KD 0 → 1.0 (trivially rankable; we'll definitely win)
# KD 25 → 0.75 (easy; longtail territory)
# KD 50 → 0.5 (moderate; midtail)
# KD 80 → 0.2 (hard; would need real authority)
# KD 100 → 0 (impossible; entrenched competitors own SERP)`}
Why it matters. Demand without winnability is noise. A 100,000-search keyword is worthless to us if the top 10 results are Wikipedia, NIH, and the New York Times—we'll never break in. Inv-KD is the "sanity check" against volume: it shaves the composite down for opportunities that look big on paper but are practically un-rankable. The 10% weight in the composite is deliberately modest—KD is a constraint, not the primary driver—but it actively pulls down briefs we couldn't realistically execute on.
How to interpret it. KD < 30 = "we can win this if we publish well"—Tier 1 territory. KD 30–49 = "we can win this if we already have some adjacent authority"—Tier 2. KD 50–79 = "hard but possible with cluster + freshness"—Tier 3. KD 80+ = "unrealistic for us" and triggers the hard auto-Skip rule unless we already rank top-50 on a sibling keyword (the tangential-foothold exemption). When you see inv_kd_norm at 0.2 in the score-components panel, the brief's average KD is around 80—read that as "not winnable cold."
What it signifies. The "is there money here?" component of the composite. CPC is what advertisers pay Google per click for ads against this keyword. We don't run ads ourselves—we use CPC as an indirect signal that the topic has commercial intent. Readers searching high-CPC queries are more likely to be in spending mode, which translates to higher organic ad revenue on our pages too (same advertisers buying programmatic display next to our articles).
How it's sourced. SEMrush returns a per-keyword CPC in dollars via phrase_fullsearch at brief-pull time. The console averages it across the brief's keyword cluster, then normalizes against the brief's vertical's low/median/high CPC anchors (not absolute numbers):
{`cpc_norm = piecewise_linear(cpc, vertical.lo, vertical.mid, vertical.hi)
# at vertical.lo → 0.25 (low commercial intent for this vertical)
# at vertical.mid → 0.50 (typical for this vertical)
# at vertical.hi → 0.75 (high for this vertical)
# > vertical.hi → log-asymptote toward 1.0`}
Vertical anchors live in VERTICAL_CPC_NORMS in util.js; the full table is at .
Why it matters. CPC ranges are wildly different across verticals—$1.50 is high for entertainment but laughably low for financial services. Without per-vertical normalization, financial-services briefs would always dominate the CPC signal and entertainment briefs would never score, even when the ent brief is at the top of its own vertical's CPC distribution. The per-vertical anchor approach makes the signal comparable across verticals so editorial decisions aren't biased toward whichever vertical happens to advertise most expensively.
How to interpret it. A cpc_norm of 0.50 means "this keyword sits at its vertical's median commercial intent—typical for the space." 0.75+ means "above-typical intent—the topic is commercially hot for its vertical." Below 0.25 means "low intent for this vertical—readers aren't searching with spending intent." The 10% weight is deliberately modest—CPC is a tiebreaker between similarly-volume-and-difficulty briefs, not a primary driver.
What it signifies. The lookup table of "what counts as low / typical / high CPC" within each vertical we operate in. Each row gives three dollar anchors—low (~25th percentile), mid (~50th), high (~75th)—observed in real CPC distributions. The console uses these anchors to normalize each brief's CPC against its own vertical, so a $0.95 entertainment keyword and a $6.00 financial-services keyword can score equivalently when both sit at their vertical's median.
How it's sourced. Per-vertical CPC distributions originated from data-team commentary on real observed CPC ranges across McClatchy verticals. Lives in VERTICAL_CPC_NORMS in util.js. Manual refresh—revisit when adding a new vertical or when observed distributions shift materially. The _default row is the fallback for unrecognized verticals.
| Vertical | lo (~25th %ile) | mid (~50th) | hi (~75th) |
|---|---|---|---|
| entertainment | $0.30 | $0.95 | $2.00 |
| sports | $0.40 | $1.10 | $2.50 |
| fashion | $0.50 | $1.50 | $4.00 |
| tech | $0.80 | $2.00 | $6.00 |
| travel | $0.50 | $1.50 | $4.50 |
| food-recipes | $0.30 | $0.85 | $2.00 |
| health-wellness | $0.80 | $2.50 | $8.00 |
| home | $0.60 | $1.80 | $5.00 |
| parenting | $0.40 | $1.20 | $3.50 |
| financial-services | $2.00 | $6.00 | $30.00 |
| _default (unrecognized vertical) | $0.50 | $1.50 | $4.00 |
Why it matters. CPC ranges differ wildly across verticals. $1.50 is high for entertainment but laughably low for financial services. Without per-vertical normalization, financial-services briefs would always dominate the CPC dimension of the composite score and entertainment briefs would always lose—even when the entertainment brief is at the top of its own vertical's CPC distribution. Per-vertical anchors keep the signal comparable across verticals so editorial decisions aren't biased toward whichever vertical happens to advertise most expensively.
How to interpret it. Find the brief's vertical row → check where the brief's avg CPC sits between lo / mid / hi. Below lo = bottom-quarter commercial intent for this vertical → cpc_norm ~0.25. Around mid = typical. Around hi = above-typical commercial intent for this vertical. Above hi = exceptional commercial intent (asymptotes toward 1.0). When a vertical isn't listed, the engine falls back to the _default anchors—that's a hint to add the vertical to the table once observation data lets you anchor it accurately.
What it signifies. A small "everything else" adjustment to the composite score that catches signals not captured by volume / KD / CPC. Specifically two things: how confident we are in the underlying SEMrush data for this brief, and how well the brief matches our default audience persona. Acts as a tiebreaker between briefs that score similarly on the main three signals.
How it's sourced. Computed at runtime from two flags already attached to the brief:
{`residual_norm = 0.5 baseline (neutral)
+ 0.10 if confidence == 'precise'
− 0.15 if confidence == 'partial'
+ 0.08 if persona fit (vs Curious Optimizer) == 'high'
− 0.05 if persona fit == 'low'
clamped to [0, 1]`}
Confidence comes from the SEMrush pull: "precise" if we got ≥10 keywords with full vol/KD/CPC coverage, "partial" if the pull was thin or the KD coverage had gaps. Persona fit comes from the same vocabulary-matching logic that drives the Persona-fit panel—see .
Why it matters. Two briefs with identical vol / KD / CPC numbers can still differ in real-world value: one might be backed by sketchy SEMrush data (so the 75/10/10 portion is over-confident) and one might be a poor fit for our default audience (so even if the search demand is real, we're not the right publisher to serve it). The residual lets the engine say "all else equal, this one's a slightly weaker bet" or "this one's a slightly stronger bet" without overhauling the main signals. The 5% weight is intentionally tiny—residual nudges the composite, never dominates.
How to interpret it. A residual_norm of 0.6 in the score-components panel means "small positive nudge—clean SEMrush data plus decent persona fit." 0.4 means "small negative nudge—partial data and/or weak persona fit." Practical effect: at most ±0.012 on the final composite (5% × ±0.23 swing range). It rarely flips a verdict on its own, but it can shift a borderline brief from Worth Testing into High Opportunity or vice versa. Phase-5 will tune the residual ingredients once Decision Log accumulates outcome data.
What it signifies. How the engine converts each brief's composite score (a number 0–1) into a verdict label (High Opportunity / Worth Testing / Monitor / Skip). Instead of fixed numeric thresholds ("composite ≥ 0.6 = High Opportunity"), the engine sorts the entire current cohort of briefs by composite, then slices the sorted list into three buckets by percentile. Two overrides sit on top of the cohort cut: a hard auto-Skip (volume floor / KD ceiling / intent mismatch), and—for a TH-pipeline trend below the volume floor whose only failing check is that advisory floor—a Monitor verdict instead of Skip.
| Cut | Bucket | Verdict | Plain English |
|---|---|---|---|
| Top 30% | composite ≥ 70th percentile | High Opportunity | Strongest bets in the current inventory |
| Middle 50% | composite 20th–70th percentile | Worth Testing | Mid-cohort—probably batch a few articles to learn |
| Bottom 20% | composite < 20th percentile | Skip | Weakest 20% of the inventory |
How it's sourced. Cut percentages live in docs/data/verdict-thresholds.js → buckets.high_opportunity_pct / worth_testing_pct / skip_pct. Recomputed at every page load against the current full cohort of briefs in window.BRIEFS—so adding new briefs reshuffles every brief's verdict if their composite ranking against the new cohort changes.
Why it matters. Percentile cuts force the engine to maintain a coherent triage shape: a roughly fixed proportion of briefs always sit in "do this first" vs "test these" vs "skip these," regardless of whether the cohort skews easy or hard overall. If we used absolute thresholds, a quarter where every brief had high KD would produce zero High Opportunity verdicts and the operator would freeze. The cut percentages were also empirically validated—ETRP ran a sweep over candidate cuts on 1,062 historical articles and found 30/50/20 beat the v2 baseline of 20/50/30 by:
Both metrics beat baseline by ≥3pp—the threshold required to adopt a refinement.
How to interpret it. If a brief's verdict shifts between sessions without you doing anything, the cohort changed: someone added new briefs that scored higher and bumped this one down a percentile bucket, or vice versa. That's expected behavior, not a bug. Reading the verdict pill: "High Opportunity" doesn't mean "guaranteed winner"—it means "in the top 30% of this inventory by composite score." Always pair the verdict with the score-components breakdown to understand why it landed there. And remember the ETRP caveat: the verdict ranks opportunity surface, not predicted PVs.
What it signifies. Three "hard no" rules that override the cohort-percentile verdict. The KD-ceiling and intent-mismatch gates force a Skip regardless of how the brief scored. The volume floor is a hard Skip for ordinary keyword briefs, but for TH-pipeline trends (briefs that carry a thStatus) it is advisory: below the floor they route automatically to a Monitor verdict (velocity-validated, search-demand unproven)—neither pursue nor skip—rather than a hard Skip. They're the engine's safety net for opportunities that look mathematically attractive but are practically un-winnable or ill-fitting.
| Rule | Threshold | What it catches | Override path |
|---|---|---|---|
| Volume floor | brief total volume < 500/month | Briefs whose keyword cluster has too little aggregate search demand to bother spinning up an article | Automatic for TH-pipeline trends: a brief carrying a thStatus is advisory-floored → routes to Monitor (not Skip). The manual TVE "rising" flag is the operator equivalent for non-TH briefs. |
| KD ceiling without tangential foothold | brief avg KD ≥ 80 AND no keyword has ourPos ≤ 20 | Briefs in extremely hard SERPs where we have no existing authority to leverage | If any keyword shows ourPos ≤ 20, the rule auto-bypasses (we have a foothold to build on); otherwise operator must Keep + leave rationale |
| Search-intent mismatch | Advisory check—defaults to pass | Briefs where the formula thinks the topic fits but the actual SERP shows a different intent (e.g. transactional vs informational) | Operator-set; not auto-fired |
How it's sourced. Thresholds live in docs/data/verdict-thresholds.js → auto_skip.min_volume + auto_skip.max_kd_no_tangential. Tangential-foothold check reads topKeywords[].ourPos on the brief (refreshed monthly via backfill_positions.py). All checks run after composite scoring—they take a "passed verdict" and override it to Skip when fired.
Why it matters. Without these gates, a brief with a single high-volume keyword (boosting volume_norm) on a hard SERP could mathematically score into High Opportunity territory while being completely unwinnable in practice. Volume below 500/month is genuinely too thin for the production-cycle math to work even at full hit-rate. KD ≥ 80 without a foothold means we're proposing to outrank Wikipedia from a cold start—not realistic. Both rules are deliberate "the engine refuses to recommend execution here" backstops.
How to interpret it. If the verdict-breakdown panel shows an auto-Skip badge fired, look at WHICH gate triggered: "vol < 500" means the topic is too thin demand-side; "KD ≥ 80 + no foothold" means the SERP is too entrenched and we don't already rank anywhere; intent-mismatch means a domain expert flagged the brief manually. For a TH-pipeline trend the volume floor shows as an advisory ⚠ (not a ✗) and the brief resolves to Monitor automatically—external momentum is presumed by the TH pipeline that surfaced it, so no manual flag is needed. The manual TVE rising override remains the operator's tool for the volume floor on non-TH briefs—use it when external signal (Google Trends, social, news cycle) shows momentum that hasn't shown up in monthly SEMrush volume yet. The KD ceiling override requires explicit operator commitment via Keep + rationale; that decision becomes part of Phase-5 calibration training data.
What it signifies. Three difficulty tiers—T1, T2, T3—that classify each brief by its keyword-difficulty profile. They group briefs into "win this now," "build into this later," and "long-game stretch" buckets so the production pipeline can be staged: do the easy wins first to earn authority, then graduate into harder territory once the foothold exists. The Beach lens uses these tiers as the three difficulty rails inside each TH Collection.
| Tier | KD range | Min keyword volume | Production-mix target | What it means |
|---|---|---|---|---|
| Tier 1 · Go Now | KD 0–29 | 500 | 60% of kept mix | Easy SERPs we can win immediately. Longtail-leaning. Today's working surface—write these. |
| Tier 2 · Build Into | KD 30–49 | 1,000 | 30% | Moderate SERPs winnable once the team has some adjacent-topic authority. Midtail. Locked in Beach lens until rolling unlock fires. |
| Tier 3 · Long Game | KD 50+ | 5,000 | 10% | Hard SERPs. Cluster-scale commitment required (multi-article + freshness). Locked until a higher rolling-unlock threshold. |
How it's sourced. Defined in TIER_RULES in util.js. Pulled from content team lead's TH Keyword Selection Framework v1 (2026-03-16). Each brief is classified by its average KD across the keyword cluster, with the per-keyword min-volume threshold acting as a sanity check that the cluster carries enough demand for the tier. Tier appears as a small pill on every brief tile (T1 / T2 / T3, with a "↓" suffix when the cluster check fails—see ).
Why it matters. Without explicit tiers, the team would be free to attack any KD level at any time, with no gating logic. That tends to produce churn—operators chase shiny high-volume head-terms, lose against entrenched SERPs, and get demoralized. The framework's bet is that staged commitment (T1 wins → T2 unlocks → T3 unlocks) compounds authority faster than scattered effort. The 60/30/10 production-mix target is the explicit rule for "what shape should our weekly output look like" so we never starve the easy-win foundation.
How to interpret it. See a brief tagged T1 in the inventory? Top of the list to attack today—easy SERPs, you'll likely rank if the article is competent. T2 means "this is winnable but not yet—keep stacking T1 wins first, or move on." T3 means "respect the difficulty; only commit if you can do cluster-scale work." When a pub has demonstrated GSC-observed authority on the brief's keywords, the tier can improve for that pub specifically via DA-shift—see . A "DA-shifted from T2 on miamiherald.com" tag means Miami Herald has enough adjacent ranking authority to attack the brief like a T1 even though raw KD says T2.
What it signifies. A per-brief role classification—Entry Point / Deepener / Connector / Converter—that says "what role does this content play in the broader site experience?" Each role has its own minimum thresholds (e.g. an Entry Point brief needs higher acquisition-velocity numbers than a Deepener; a Converter needs commercial intent). Maps each brief to the relevant set of advisory checks based on its content type.
How it's sourced. The role is derived from the brief's content type via contentWebRoleFor() in util.js. Mapping: Blue = Entry Point (acquisition), Orange = Deepener (typical wellness/lifestyle explainer), Purple = Bridge (L&E, currently paused), Green = Converter (commerce/signups). Per-role threshold rules live in WEB_ROLE_RULES. Originated from the TH Keyword Selection Framework v1 along with the tier bands.
Why it matters. Different content roles need different success criteria. An Entry Point brief winning at 8% engaged-session-rate but driving lots of new visitors is doing its job; a Deepener brief with the same engagement number but no return-visit signal is failing. Without role-specific thresholds, every brief gets graded on the same "engagement composite" and we either over-credit acquisition pieces or under-credit deepeners. The role-aware approach lets the engine assess each brief against the standard appropriate to its function.
How to interpret it. Web-role checks are advisory, not gating—they surface in the verdict-breakdown panel as informational notes ("Deepener role: time-on-page below threshold") but do not auto-Skip a brief on their own. Read them as "the engine has noticed something off about this brief's expected behavior for its role"—useful as a reality-check before committing pipeline capacity. The TVE override path is available if external signals (e.g. trend velocity) say the brief should be pursued anyway.
What it signifies. A "is this keyword cluster actually rich enough to commit cluster-scale production effort?" check. A cluster is rich if it has enough sweet-spot keywords—meaning keywords that combine meaningful demand (volume ≥ 500/month) with winnable difficulty (KD ≤ 29)—to support a multi-article content cluster around the topic. Not just one big keyword with a long tail of difficult or thin ones.
How it's sourced. Computed at runtime from the brief's topKeywords[] array (which comes from the SEMrush pull):
{`sweet_spot_keywords = topKeywords filtered to (vol ≥ 500 AND KD ≤ 29)
opportunity_score = count(sweet_spot_keywords) × sum(sweet_spot.volume)
clears_tier_1 = count ≥ 10 AND combined_volume ≥ 10,000`}
The Tier 1 cluster threshold (≥ 10 sweet-spot keywords AND ≥ 10K combined volume) is from TH Framework v1 §4b. Surfaces in the TH Framework v1 panel inside the verdict breakdown.
Why it matters. A brief might pass the per-keyword Tier 1 check (avg KD < 30, decent total volume) on the strength of one or two big keywords—but the engine still recommends cluster-scale commitment for Tier 1. If the cluster is actually thin (one fat keyword surrounded by hard ones), spinning up a 10-article cluster makes no sense; you'd write the one easy article and the rest would lose. The cluster-opportunity check catches this gap. When the brief is "T1 by KD bands but cluster fails," the tier label is marked "superseded"—meaning the engine doesn't actually trust the Tier 1 framing for this brief.
How to interpret it. See "T1 ↓" or "T1 (superseded)" on a brief? The per-keyword math says T1 but the cluster check says it can't support cluster-scale production. Treat as below-T1 for planning—you might still write the one strong article, but don't commit to a cluster around it. See "T1 (cluster: 12 keywords, 14.5K combined vol)" in the framework panel? Solid Tier 1—proceed with cluster commitment. The numbers shown in the framework panel let you eyeball cluster richness directly.
What it signifies. A per-publication "credit" we apply to the brief's keyword difficulty when one of our pubs already ranks well on the brief's keywords. Logic: if Miami Herald already ranks #4 in Google for some keyword in this brief's cluster, then Miami Herald has demonstrable topical authority there—KD 60 isn't really KD 60 for that pub, it's effectively easier. So Miami Herald might be able to attack this brief like a Tier 2 even though raw KD says Tier 3. "DA" = Domain Authority. "Shift" = we shift the effective tier downward (= easier).
How it's sourced. Layer 6 of the daily learning-loop cron pulls Google Search Console data from Snowflake (SEARCH_ANALYSIS_RPT, 28d window) for every brief × pub pair. The avg_position column tells us where that pub already ranks. The bonus scales with how strong the existing ranking is:
{`avg_rank ≤ 5 → DA bonus = 20 KD points (very strong authority)
avg_rank ≤ 10 → DA bonus = 12
avg_rank ≤ 25 → DA bonus = 6
avg_rank ≤ 50 → DA bonus = 3
avg_rank > 50 → DA bonus = 0 (no observable authority)
effective_kd = max(0, brief.avgKD − DA_bonus)
tier = classify_by_band(effective_kd)`}
Computed per pub × per brief, so a single brief can have different effective tiers on different pubs. Sources: daBonusFromGsc + classifyTierWithDaBonus in util.js.
Why it matters. Without DA-shift, the engine treats every brief as a cold start regardless of where in the portfolio we already have authority. That throws away one of our biggest competitive levers—the fact that some keywords have an existing top-50 ranking we could absolutely beat with a freshness pass or a cluster expansion. DA-shift makes that latent authority visible at the verdict-breakdown level so editorial decisions can route toward the pub best positioned to win.
How to interpret it. See a "DA-shifted from T2 on miamiherald.com" tag in the framework panel? Translation: this brief shows as Tier 2 by raw KD, but Miami Herald already has enough adjacent authority that effectively it's a Tier 1 attack for them specifically. Plan to send this brief through the Miami Herald flow—the math says they'll win it. No DA-shift tag = no portfolio pub has observable authority on this keyword space yet—treat as a cold start. The bonus only kicks in when GSC actually shows you ranking; it's not aspirational.
What it signifies. The conversion factor between "where this article ranks on Google's results page" and "what fraction of searchers actually click on it." If your article ranks #1 in a SERP, ~28% of people who search that query click on you; rank #10, only ~3%; rank #20, ~1.5%. The CTR curve is how the engine converts search-volume numbers into expected page-view numbers—multiply monthly searches × CTR-at-position to project monthly traffic.
How it's sourced. Industry-standard CTR curve from Advanced Web Ranking 2024 organic-SERP averages, baked into CTR_CURVE in util.js:
{`CTR by SERP rank (industry baseline):
rank 1 → ~28%
rank 2 → ~16%
rank 5 → ~6%
rank 10 → ~3%
rank 20 → ~1%
rank 50 → ~0.1%`}
Then we need to predict what rank our article would land at, since it doesn't exist yet. Two stages:
Stage 1—KD-derived (fallback when no real ranking data exists). Map KD into an expected rank using expectedRankFromKD():
{`KD < 20 → expect rank ~5 (easy SERPs, top-5 likely)
KD < 30 → expect rank ~8 (longtail, top-10)
KD < 50 → expect rank ~18 (midtail, page 2)
KD < 70 → expect rank ~35 (hard, page 3-4)
KD ≥ 70 → expect rank ~60 (very hard, deep pages)`}
Stage 2—GSC-observed (when available). Layer 6 of the daily learning-loop cron pulls SEARCH_ANALYSIS_RPT from Snowflake (28d window). When a portfolio pub has actually-observed avg_position for the brief's keywords, the engine uses that directly instead of the KD-derived guess. Higher accuracy because it's grounded in real ranking history rather than a SEMrush proxy.
Why it matters. Search volume on its own doesn't tell you traffic—a 100K-search query at rank 50 sends maybe 100 clicks. The CTR curve makes the volume number actionable by attaching a realistic capture rate. It's also the input to the Revenue projection panel—without expected PVs, you can't multiply by eCPM to estimate revenue. Stage-1 KD-derivation is a defensible baseline for greenfield briefs; Stage-2 GSC-observed is more accurate when authority data exists. Both are surfaced in the engine so the operator can see which stage drove the projection.
How to interpret it. Read CTR-projected PVs as theoretical upside if we rank where the engine expects—not as forecasts. Real outcomes vary widely (per ETRP's negative Spearman finding). When the Revenue panel shows "rank source: gsc-observed (pos 12)," it's grounded in actual McClatchy ranking history; when it shows "rank source: kd-estimated (KD 45 → rank ~18)," it's a defensible guess. Trust GSC-observed projections more than KD-estimated ones; treat KD-estimated as directional only.
What it signifies. A "what's this brief potentially worth in dollars per month, per pub?" projection. The engine predicts how many page views the article would get if it ranked where the engine expects, then multiplies that by the pub's eCPM (revenue per 1,000 impressions). Surfaces as a dollar range across all portfolio pubs (e.g. "$240–$1,800/mo · 8 pubs") so you can see which pub is positioned to extract the most revenue from the brief.
How it's sourced. Multi-step computation, run per pub for the entire portfolio:
{`for each pub in portfolio:
rank = gsc_observed[pub] OR expected_rank_from_kd(brief.avgKD)
ctr = CTR_CURVE[rank] # industry CTR curve, see CTR section
monthly_pv = brief.totalVolume × ctr # search vol × click-through rate
ecpm = ECPM[pub] # static per-pub table (quarterly refresh)
revenue = (monthly_pv / 1000) × ecpm
range = { min, max, count, bestPub, bestRevenue }`}
Functions: portfolioRevenue(), revenueRange() in util.js; eCPM in ECPM map. Stage 1 uses KD-derived rank; Stage 2 uses GSC-observed rank when available (see ).
Why it matters. Composite verdicts ("High Opportunity") tell you opportunity surface but say nothing about absolute dollar value. A High Opportunity brief that projects to $200/mo is a different decision than a Worth Testing brief that projects to $3K/mo per pub. The revenue lens turns the engine's verdict-side scoring into business-side scoring—useful for prioritizing under capacity constraints when you have to pick between briefs that all "look good." It's an overlay (off by default) because the projection is theoretical and over-emphasizing dollar projections can distort editorial decisions toward chasing inflated numbers.
How to interpret it. Treat the range as theoretical upside if we rank where the engine expects—not a forecast. Three reasons to be cautious: (1) the eCPM table is static per pub (no section / seasonal / direct-sold variation, see ); (2) KD-derived rank predictions are SEMrush proxies, not actual rankings; (3) ETRP found composite scores are uncorrelated to anti-correlated with PV outcomes historically, so even GSC-observed projections are subject to execution variance. Practical use: compare relative projections across briefs (which one looks bigger?) rather than treating any single number as a forecast. The "best pub" callout is more reliable than the absolute number—it reflects existing authority signals.
Important caveat: the eCPM table is static—one number per pub, refreshed manually every quarter. It does not vary by section, time of year, content type, ad density, or recency. Direct-sold revenue is not modeled. The console nudges Pierce when the table approaches/passes the 90-day refresh deadline.
What it signifies. A flat lookup of "if an article published on this pub generates 1,000 ad impressions, how many dollars do we make?" One number per pub, in dollars. eCPM = effective cost per mille (Latin for thousand)—the standard advertising metric that converts impression count to revenue. The Revenue projection panel uses these numbers to multiply expected page views into projected dollars. Because the table is static, every brief on a given pub uses the same eCPM regardless of the brief's section / vertical / topic—a known coarse approximation.
How it's sourced. McClatchy ad-ops produces a quarterly eCPM export at the pub level. Pierce updates the ECPM map in docs/js/util.js + sets ECPM_REFRESH_DATE to the export's date. Staleness state—ecpmStalenessState() in util.js—flips to "due-soon" 15 days before the 90-day deadline and "overdue" past it. The console nudges visibly once stale.
Why it matters. Composite verdicts ("High Opportunity") tell you opportunity surface but say nothing about absolute dollar value. Multiplying expected PVs by eCPM converts the verdict into rough dollar projections—useful for prioritizing under capacity constraints. But "static per pub" means the number is a baseline programmatic-only estimate, not a forecast: ad sections / time of year / direct-sold mix all create real variation that's not captured. So the table matters as a relative ranking tool ("Miami Herald earns more per PV than Sacramento Bee—route revenue-hungry briefs there") more than as an absolute forecast.
| Pub | Tier | eCPM | Notes |
|---|---|---|---|
| TH O&O | th-primary | $1.95 | Post-pivot home—every new National article ships here |
| Miami Herald | regional | $1.21 | |
| Kansas City Star | regional | $1.10 | |
| Charlotte Observer | regional | $1.06 | |
| Sacramento Bee | regional | $0.92 | |
| Raleigh News & Observer | regional | $0.88 | |
| The State | regional | $1.17 | |
| Fort Worth Star-Telegram | regional | $0.98 | |
| Lexington Herald-Leader | regional | $0.93 | |
| Us Weekly | L&E (paused) | $1.21 | Paused until L&E data pipe is repaired |
| Woman's World | L&E (paused) | $1.13 | Paused |
| Life & Style | L&E (paused) | $1.08 | Paused |
| First For Women | L&E (paused) | $1.33 | Paused |
| In Touch Weekly | L&E (paused) | $3.55 | Paused · small sample (treat with caution) |
| Closer Weekly | L&E (paused) | $2.21 | Paused · small sample |
| Star Magazine | L&E (paused) | $8.73 | Paused · very small sample (treat as outlier) |
| Soap Opera Digest | L&E (paused) | $1.48 | Paused |
REFERENCE.md §"Authoritative site-level eCPM."ECPM map in util.js, set ECPM_REFRESH_DATE to the export's date.How to interpret it. Use eCPM differences to rank pubs against each other for revenue-routing decisions: a $1.95 TH O&O eCPM is roughly 2× a $0.92 Sacramento Bee eCPM, so the same article will earn ~2× more on TH for the same PV count. Don't read a single absolute eCPM number as a precise forecast—section / season / direct-sold can swing actual revenue by 30–50%. When you see the staleness pill ("eCPM table due in 12d" / "overdue 5d"), prompt for a fresh ad-ops export. Treat the L&E pub eCPMs as currently academic—those pubs are paused until the L&E data pipe is repaired. Per-pub authority bonuses (Stage 2) will eventually layer onto this for more accurate routing once GSC integration completes.
Source. ECPM, ecpmFor(), ecpmStalenessState() in util.js.
What it signifies. A 0–100 score per brief that captures "how strongly are readers actually engaging with content like this?"—measured from real reader behavior on McClatchy articles whose keywords match the brief. Different from page views: a high-engagement article holds attention (long time-on-page, multi-page sessions, deep scroll) regardless of total volume; a low-engagement article gets the click but loses the reader. Different content types use different ingredients because they have different success criteria.
How it's sourced. Computed by the BI-team framework, weighted by content type (the role each piece plays):
{`Default / Deepener (Orange): time_on_page × 0.40
+ pvs_per_session × 0.30
+ scroll_depth × 0.30
(when scroll_depth not derivable, weights renormalize)
Entry Point (Blue): PVs ÷ new visitors (acquisition velocity)
Connector: internal-link CTR + cluster-continuation rate
Converter (Green): conversions + signups`}
The live data comes from ARTICLE_ENGAGEMENT_SIGNALS in Snowflake (Amplitude-derived: time-on-page, session length, pvs/session, bounce rate, engaged-session rate, etc.), joined to articles matching the brief's keyword space. Layer 7 of the daily learning-loop cron (8:13am Dallas) refreshes this. Functions: engagementSignal(), engagementSignalDetail(), ENGAGEMENT_FRAMEWORK in util.js.
Why it matters. Page views alone overrate acquisition pieces and underrate deepeners. An article that wins a viral moment but loses readers in 6 seconds is shipping low-quality reach; an article with modest PVs but 4-minute average time-on-page is actually serving the audience. The engagement signal lets the engine assess each brief on the dimension appropriate to its role—and surfaces "this brief's keyword space tends to engage poorly" or "...tends to engage well" warnings before pipeline capacity is committed. It's especially useful for greenfield decisions: "if we publish here, what's the historical engagement profile of similar articles?"
How to interpret it. A 70+ live score = strong reader behavior; readers actually engage with content like this. 40–60 = average. Below 30 = thin engagement; even if you publish, expect bounce. Live data (full color, no asterisk) is real reader behavior—trust the score directly. Proxy (faded color + asterisk *) means no published article matches yet, so the score is derived from KD + persona-fit + content-type—read it as a directional placeholder, not ground truth. The proxy auto-clears the next day after a matching article publishes (Layer-7 cron joins). See for the full visual-state explainer.
What it signifies. The engagement pill on every brief tile renders in two visually distinct states—full-color or faded-with-asterisk—and the difference is load-bearing. Full color = real reader behavior pulled from a published McClatchy article whose keywords match this brief. Faded with an asterisk = no published article matches yet, so the score is a directional placeholder derived from KD + persona-fit + content-type. The visual distinction tells you at a glance whether the number is observed or estimated, so you never accidentally treat a proxy as ground truth.
| State | Visual | Source | How to read |
|---|---|---|---|
| Live | Full color, no asterisk | Snowflake ARTICLE_ENGAGEMENT_SIGNALS joined to articles matching the brief's keyword space | Trust as observed reader behavior. Higher = stronger. |
| Proxy | Faded color + asterisk * | Derived: function(KD, persona-fit, content-type) | Directional only. Use for relative ordering across briefs, not as ground truth. |
How it's sourced. The pill state is decided by engagementSignalDetail() in util.js—returns {`{ source: 'live'|'proxy', score, components, articleCount }`}. Layer 7 of the daily learning-loop cron (8:13am Dallas) runs scripts/precompute_engagement.py which joins TRACKER_ENRICHED (Snowflake) against each brief's keyword cluster + reads ARTICLE_ENGAGEMENT_SIGNALS (also Snowflake, Amplitude-derived: time-on-page, pvs/session, bounce rate). When at least one matched article exists, the engine flips that brief's pill from proxy to live on the next page load. No operator action.
Why it matters. Two briefs with engagement scores of 70 mean very different things if one is live (real reader behavior says this topic engages well) and one is proxy (the engine guesses this topic should engage well based on heuristics). Without the visual distinction, the operator can't tell observation from estimate at the tile level—and proxy-as-truth would push wrong briefs to the top of triage. The fade + asterisk make data quality always visible, with no need to drill into the drawer.
How to interpret it. Live pills (full color): trust the score directly. A 72 means real readers spent real time engaging—actionable. Proxy pills (faded + asterisk): use only for relative ordering across briefs ("proxy 60 looks more promising than proxy 40")—both could land elsewhere when the article actually publishes. Greenfield V5 briefs default to proxy; the proxy clears within ~24 hours of a matching article publishing. The same source flag is mirrored in the drawer's Engagement signal panel with full per-metric breakdown—drill in there when you need to see why a brief scored as it did. See also: .
What it signifies. How strongly a brief's topic + recommended article + keywords resonate with each named audience persona. Scored as high / medium / low / n/a per persona. Says: "if Curious Optimizer is the audience, does this brief speak to her?"—a brief about hormone-balancing supplements is a high fit; a brief about NFL draft prospects is a low fit. Used to flag briefs that mathematically score well by formula but are tonally wrong for the audience we're trying to grow.
How it's sourced. Vocabulary-matching against persona-specific term lists. Process:
{`for each persona:
haystack = brief.topic + brief.recommendedArticle + brief.keywords
(joined, lowercased)
matches = persona.affinity_terms ∩ haystack
score = Σ match.weight + content_type_prior_bonus
fit = 'high' if score is at or near the cohort's top
'medium' if score is mid-range
'low' if score is below the noise floor (0.5)`}
Each persona has three weighted vocabulary categories—topic terms (weight 1.0, primary), format terms (0.6), tone terms (0.4). Plus a content-type prior bonus that adds +0.5 / +0.2 / −0.2 depending on whether the brief's content type is canonically "high / medium / low" fit for that persona. Vocabularies live in PERSONA_AFFINITY; per-content-type matrix in PERSONA_FIT_MATRIX; matching logic in personaFitDetail(). All in util.js. Full vocabulary lists at .
Why it matters. The composite verdict ranks briefs by raw opportunity surface (volume × difficulty × commercial intent), but says nothing about audience fit. A high-composite brief about NFL draft prospects looks great by the math but isn't going to grow the Curious Optimizer audience that the post-pivot TH O&O needs. Persona-fit catches that mismatch—it's the dimension that says "yes the math says go, but should we actually be the publisher serving this query?" Defaults to OFF (overlay toggle) because for most decisions raw opportunity is what matters; flip it on when you want persona-led prioritization.
How to interpret it. When the persona overlay is on, the tile shows "fit · high/medium/low" against the currently-active persona (defaults to Curious Optimizer). High = the brief's vocabulary strongly overlaps the persona's interests; this is squarely on-strategy. Medium = some overlap; the brief might serve adjacent interest. Low = the persona-fit floor wasn't cleared; this brief isn't really for this persona. n/a = persona's content-type prior says "not applicable" for this content type. The drawer's Persona-fit panel shows all five personas ranked + the matched-terms preview so you can see why the engine scored it that way.
The five personas the console scores every brief against, with their complete affinity-term vocabularies. These are content team lead's editorially-validated lists from 2026-04. The full lists ship with the console (in util.js) so anyone can audit the matching logic.
What it signifies. Each persona is a named audience archetype (Curious Optimizer, Discover Browser, Watercooler Insider, Curious Explorer, Science Enthusiast) defined by a curated vocabulary of words and phrases the audience cares about. When a brief's topic + recommended article + keywords overlap heavily with a persona's vocabulary, the engine reads that as "this brief speaks to this audience." Defaults to Curious Optimizer (the always-on TH primary B2C audience) for fit overlay; other personas are available for cross-checking.
How it's sourced. Vocabularies live in PERSONA_AFFINITY in util.js; per-content-type fit matrix in PERSONA_FIT_MATRIX. Scoring logic in personaFitDetail(). Vocabularies originated from content team lead's editorially-validated term lists, 2026-04. To add new personas or terms, edit those constants—the console picks up changes on next page load.
Why it matters. Composite verdicts rank briefs by raw opportunity surface (volume × difficulty × commercial intent), but say nothing about whether we should be the publisher serving that query. A brief about NFL draft prospects might math-out as High Opportunity but isn't going to grow the Curious Optimizer audience the post-pivot TH O&O needs. Persona fit catches that mismatch—it's the dimension that says "the math says go, but is this audience-on-strategy?" Showing the full vocabulary for every persona means anyone can audit how the engine decides fit, and propose vocabulary tweaks based on real outcomes.
How to interpret it. Each persona below has three weighted vocabulary categories—topic (weight 1.0, primary), format (0.6), tone (0.4). When a brief's haystack contains many topic terms from a persona's list, that persona scores high. When you see a brief flagged as "high fit · Curious Optimizer," skim the topic vocabulary below—those are the words the engine matched on. The drawer's Persona-fit panel shows the actual matched terms for that brief × persona, so you can see why the engine decided what it did.
For each persona, the console builds a "haystack" from the brief's topic + recommendedArticle + topKeywords[].label, lowercased and concatenated. It then walks each persona's three vocabulary categories (topic · weight 1.0, format · weight 0.6, tone · weight 0.4) and counts term matches, summing weighted scores. A small content-type prior bonus (+0.5 high / +0.2 medium / −0.2 low) layers on top. The persona with the highest score wins; bucket boundaries (high / medium / low) are relative within the cohort, not absolute.
If no persona scores above the floor (0.5), all return "low"—a "cold brief" the vocabulary doesn't match.
Profile. Emerging trends, self-improvement, ahead-of-curve audience. Reads science-backed wellness, biohacking, productivity, longevity content. Looks for evidence-based "best of" / "how-to" / data-backed framings.
Topic vocabulary (weight 1.0). longevity, lifespan, aging, biohack, optimize, optimizing, productivity, focus, sleep, sleep quality, mindfulness, meditation, fitness, workout, nutrition, diet, protein, supplement, gut health, gut microbiome, fermented, fiber, probiotic, fasting, intermittent, metabolism, hormone, mental health, anxiety, stress, cortisol, mood, energy, habit, routine, morning routine, self-improvement, wellness, cognitive, brain health, memory, learn, glp-1, weight loss, recovery, mobility, strength, cardio.
Format vocabulary (weight 0.6). "best ", "how to", guide, what works, "top ", rated, science of, evidence, data-backed, research-backed, study shows.
Tone vocabulary (weight 0.4). data, evidence, study, research, science, expert, proven, tested, effective.
Profile. Phone-scrollers swiping through Google Discover. Visual hooks, pattern-breaks, "see this!" energy. Listicles, before/afters, gallery-style content.
Topic vocabulary. photo, photos, picture, pictures, image, video, gallery, slideshow, before-and-after, before and after, transformation, makeover, reveal, jaw-dropping, unexpected, surprising, shocking, list, listicle, roundup, best photos, rare photos.
Format vocabulary. "photos:", "photos of", "in pictures", "see ", watch, gallery, " rated ", " ranked ", "top 10", "top 20", "top 25", "list of".
Tone vocabulary. must-see, jaw-dropping, amazing, incredible, shocking, stunning, breathtaking, won't believe.
Profile. Celebrity culture, viral moments, debunks, scandals. The audience that wants the gossip and the timeline.
Topic vocabulary. taylor swift, travis kelce, jenna ortega, aaron rodgers, kim kardashian, kanye, bianca censori, leonardo dicaprio, orlando bloom, eric dane, kelce, celebrity, celebrities, divorce, breakup, split, dating, engaged, wedding, feud, beef, scandal, cheating, affair, drama, red carpet, oscar, grammy, paparazzi, rumor, rumored, reportedly, allegedly, fact-check, debunk, hoax, gossip, tea, who is, spotted, caught.
Format vocabulary. "who is ", "what happened", "the truth about", timeline, "relationship timeline", "inside ", "behind the", "real story", "everything we know".
Tone vocabulary. shocking, bombshell, exclusive, inside, reveals, sources say.
Profile. Weird species, archaeological mysteries, hidden truths. Wants to feel small in the face of big nature / deep history.
Topic vocabulary. species, animal, creature, spider, bird, fish, mammal, reptile, amphibian, insect, wildlife, endangered, rare species, extinct, dinosaur, fossil, paleontology, archaeolog (matches archaeology / archaeological), ancient, ruins, tomb, pyramid, temple, lost city, expedition, jungle, rainforest, amazon, arctic, antarctic, cave, discovery, discovered, unearthed, uncovered, mystery, hidden, rare, natural wonder, national park.
Format vocabulary. discovered, "found in", unearthed, uncovered, revealed, "hidden ", "lost ", "ancient ", "rare ".
Tone vocabulary. wonder, mysterious, fascinating, remarkable, extraordinary, "never before seen", "first time".
Profile. Strange beautiful mechanisms, ocean trenches to exoplanets. Mechanism-curious—wants the "how it works."
Topic vocabulary. physics, quantum, particle, photon, electron, atom, biology, cell, dna, gene, genome, protein, chemistry, molecule, enzyme, reaction, compound, astronomy, galaxy, universe, star, planet, exoplanet, asteroid, comet, black hole, nebula, cosmos, space, ocean trench, deep sea, mariana, abyssal, hydrothermal, neuron, brain, synapse, consciousness, climate, geology, plate tectonic, volcano, earthquake, evolution, natural selection, ecosystem, biodiversity, microbe, bacterium, virus, mathematics, algorithm.
Format vocabulary. "how it works", "why ", "the science of", "the science behind", explained, "inside the", mechanism.
Tone vocabulary. fascinating, remarkable, extraordinary, mechanism, natural, phenomenon, observed, detected.
To add / remove vocabulary terms: edit PERSONA_AFFINITY in util.js. To add a new persona entirely: add a new top-level key to PERSONA_AFFINITY AND add the persona's prior matrix to PERSONA_FIT_MATRIX for each content type. The console picks up changes on next page load.
Phase-5 plan: tune vocabularies based on Decision Log evidence—which personas actually engaged each brief space when articles published.
What it signifies. A ranked list of McClatchy authors who have a track record of writing engaging articles in this brief's keyword space—i.e. the people most likely to land a strong piece if assigned this topic. "E-E-A-T" is Google's quality framework—Experience, Expertise, Authoritativeness, Trustworthiness—and per-author engagement track record is the closest proxy we have to it without explicit credentialing data.
How it's sourced. Layer 9 of the daily learning-loop cron (scripts/precompute_author_authority.py) runs every day at 8:13am Dallas. For each brief, it finds every McClatchy author with ≥3 published articles whose keywords overlap the brief's keyword cluster within a 180-day window. Then it ranks those authors:
{`for each qualifying author:
engagement_avg = mean(engagement_score) over the author's matched articles
articles_count = count of matched articles
score = articles_count × engagement_avg
(sorted descending; top N surface in the drawer panel)`}
Author names are hashed to stable 6-character IDs (a-XXXXXX) before writing the data file—the lookup table lives off-repo in operator's local notes for anonymization compliance. Function: authorAuthorityFor() in util.js.
Why it matters. Without author-authority data, every brief is assigned blind to whoever has bandwidth—which means the writer who has covered this exact space three times before gets the same shot at the brief as the writer who's never touched it. That's a quality-and-engagement floor the team can't afford to give up. Author authority surfaces the "obvious right pick" so editorial assignment routes briefs to writers with proven engagement performance in the space. Especially valuable for cluster-scale commitments where one experienced author can carry 4-5 articles efficiently.
How to interpret it. Drawer panel shows top authors + their (anonymous ID, articles count, avg engagement) for the brief. Higher count × higher engagement = stronger signal. Use it as: "if we're committing to write this brief, route it to the author at the top of this list—they have demonstrated track record." When the panel shows "no qualifying authors," the brief is a true greenfield—no one in the org has covered this space recently. That's not a Skip signal on its own; it's a heads-up that whoever takes the brief is starting from cold and should bring the framework even more carefully. Operator's local hash → name table maps the 6-char IDs back to actual writer names for assignment.
What it signifies. A label that captures where each brief sits in its own life—from "just arrived, hasn't been triaged" through "actively in production" to "old enough that the SEMrush data probably went stale and we should re-check before continuing to invest." Drives the small lifecycle pill on the brief tile so operators know at a glance whether this is fresh inventory or aged inventory needing a refresh.
| State | Trigger | Tile UI | What to do |
|---|---|---|---|
fresh | age ≤ 14d, undecided | "new" pill; surfaces in Recent Intake strip | Triage these first—newest signal, freshest data |
active | age 15–89d, undecided or kept | (no pill—normal state) | Standard handling; data still trustworthy |
serp-reverify | age 90–179d, kept | "SERP re-verify · Xd" pill | Before publishing more articles in this cluster, re-pull SEMrush positions to confirm SERPs haven't shifted |
refresh-due | age ≥ 180d, kept | "refresh due · Xd" pill | Full re-pull recommended—vol/KD/CPC numbers may be materially out of date |
decided | any decision action (skip/defer) | (decision badge replaces lifecycle) | Decision active; lifecycle state suspended until decision changes |
How it's sourced. Computed at runtime from the brief's addedAt field (ISO date, set at SEMrush-pull time) and the current decision state. Thresholds: FRESH_DAYS=14, SERP_REVERIFY_DAYS=90, REFRESH_DUE_DAYS=180 in util.js. Function: briefLifecycleState() + briefAgeDays().
Why it matters. SEMrush data ages—keyword difficulty shifts as competitors invest, search volume swings seasonally, our own rankings move. A 6-month-old brief whose verdict said "High Opportunity" might actually be "Skip" today because the SERP filled in. Without lifecycle pills, operators have no way to know which briefs need a data refresh before continuing to commit pipeline capacity. The "fresh" pill also marks the new-inflow surface so weekly intake gets triaged before it ages into the main queue.
How to interpret it. See "new" on a brief? Recent SEMrush pull, treat the data as authoritative—triage today. No pill = standard handling. "SERP re-verify · 47d remaining" = brief is at day 43 of its 90-day fresh window; consider re-pulling positions before publishing additional cluster articles. "refresh due · 12d overdue" = the data is stale; the verdict shown may not reflect current reality. Run backfill_competitors.py + backfill_positions.py for that brief, or wait for the monthly cron on the 1st (kept briefs only).
What it signifies. The target shape of the team's weekly output across the three difficulty tiers. 60% Tier 1 (Go Now, easy SERPs), 30% Tier 2 (Build Into, midtail), 10% Tier 3 (Long Game, headtail). It's not a quota—it's a "this is the healthy ratio" target so the team is mostly winning easy stuff (foundation), some authority-building stuff (compounding), and a little ambitious stuff (stretch). Drift away from this shape signals the production pipeline is unbalanced.
{`Tier 1 · Go Now: 60% of kept briefs (today's working surface)
Tier 2 · Build Into: 30% (where we're earning authority)
Tier 3 · Long Game: 10% (stretch / experimentation)`}
How it's sourced. Defined in TIER_RULES[N].productionMixPct in util.js. Per TH Keyword Selection Framework v1. Target ratios are tracked in real time against the Kept-brief inventory: the Beach lens production-mix tracker (top strip) shows current actual vs target as a small bar chart with deltas.
Why it matters. Without an explicit mix target, the team gravitates toward the most exciting opportunities—usually high-volume midtail/headtail (T2/T3)—and starves the easy-win foundation that builds compounding authority. Result: lots of effort, few wins, frustrated team. The 60/30/10 forces capacity discipline: every five articles should be roughly three Tier 1, one-and-a-half Tier 2, half a Tier 3. Over-weighting T1 looks too easy and the team gets bored; under-weighting T1 starves the foundation. The framework's bet is that 60/30/10 is the sustainable ratio for compounding traffic over multiple quarters.
How to interpret it. Beach lens production-mix tracker shows current Kept-brief distribution vs target. Big tier-1 shortfall = team is over-investing in hard SERPs; correct by Keeping more easy-rail briefs. Big tier-3 over-investment = team is reaching too far for stretch wins; correct by deferring some T3s. Tracker is informational, not a hard gate—operator can override the mix when there's editorial reason to do so. The rolling-unlock mechanism (see ) is the harder constraint—it prevents the team from chasing T2/T3 work before earning the foothold.
What it signifies. Per-collection gates that determine which difficulty rails are even visible in the Beach lens. The Ready-now rail (KD 0–29) is always available; the Building-toward rail (KD 30–49) is locked until the team has accumulated enough recent Keep decisions in this collection; the Earned-later rail (KD 50+) is locked until an even higher recent threshold. The collection only "unlocks" harder rails after demonstrating it can sustain wins on the easier ones.
| Rail | Unlock condition | Window | Plain English |
|---|---|---|---|
| Ready now (KD 0–29) | Always unlocked | — | You can always work the easy rail; no preconditions |
| Building toward (KD 30–49) | ≥ 6 keeps in this collection in last 60d | 60d rolling | You have to be currently winning easy stuff to graduate to midtail |
| Earned later (KD 50+) | ≥ 15 keeps in this collection in last 60d | 60d rolling | You have to be sustained-winning to attempt stretch SERPs |
How it's sourced. Computed at runtime per collection from the Decision Log: count how many briefs have action: 'keep' in the last 60 days within this TH Collection. Compare against the threshold. Sources: THROUGHPUT.buildingUnlock, THROUGHPUT.earnedUnlock, ROLLING_UNLOCK_DAYS=60, recentKeepCount() in util.js.
Why it matters. Lifetime achievements are misleading—a collection that ran hot 6 months ago and has been quiet for the last quarter doesn't actually deserve "Earned" status today. The rolling 60-day window is an honest signal of "are we currently winning here?" If recent commits dried up, the harder rails re-lock—forcing the team back to the easy rail to rebuild momentum before stretching again. Prevents the team from coasting on past wins and chasing hard SERPs they don't have current authority for. Also creates explicit "earn it" feedback that compounds well: keep stacking T1 wins → T2 unlocks → keep stacking T2 wins → T3 unlocks.
How to interpret it. When you see a Beach rail showing "🔒 Locked—needs N more keeps" overlay, that collection hasn't met the threshold yet. The math is "active recent keeps in this collection within the last 60 days, regardless of what was happening before." If the rail just unlocked but you stop committing, it'll re-lock 60 days from your last keep. Practical: keep the easy rail busy across multiple collections to maintain unlocks. The tracker isn't punitive—it's a reflection of where you have current momentum and where you don't.
What it signifies. A manual operator flag—set per brief—that says "I have external evidence of trend momentum here that SEMrush's monthly-search-volume number doesn't reflect yet." SEMrush data is monthly-aggregated and lagging; a topic trending hard on social media or in the news cycle this week may have very low SEMrush volume because the historical 30-day window hasn't caught up. TVE is the operator's tool for telling the verdict engine "the math says skip but I'm seeing velocity that the math doesn't see."
| State | Effect on verdict | Use when |
|---|---|---|
| off (default) | None—verdict uses raw SEMrush volume | No external velocity signal; trust the SEMrush data |
| rising | Bypasses the volume < 500 hard auto-skip rule | External signal (Google Trends top/rising queries, social momentum, news-cycle event) shows the topic is gaining velocity even though SEMrush volume looks thin |
| flat | None (informational marker) | You've confirmed the trend is steady—useful as a signal to future-you that you've already evaluated velocity for this brief |
| declining | None (informational marker) | You see the trend fading; signal to deprioritize even if SEMrush still shows decent volume |
How it's sourced. Operator sets the flag manually in the brief drawer's TVE bar. State persists to the D1 database alongside the decision row (decision.tve). Reads back on every page load. Per TH Framework v1 §3 / §4c.
Why it matters. Without TVE, operators have no way to tell the engine "I see momentum the data doesn't see yet." Result: every breaking-trend opportunity gets auto-skipped because monthly-aggregated SEMrush volume hasn't caught up. That's a structural false-negative—we'd never act on news-cycle momentum. The "rising" flag explicitly carves out the bypass: once set, the engine respects the operator's external evidence and lets the brief be Kept despite low SEMrush volume. Flat / declining are informational-only—they don't change verdict logic but mark that velocity has been considered (so the next operator session knows the brief was triaged with that context).
How to interpret it. Default state is "off." Flip to "rising" only when you have specific external evidence (Google Trends rising queries, social-platform velocity, current news cycle) that contradicts SEMrush's volume number. Don't use it as a general "I want to keep this anyway" override—that's what the Keep + rationale path is for. Important limit: TVE rising bypasses the volume floor only—it does not override the KD ≥ 80 ceiling or the intent-mismatch check. Those still fire even with TVE rising set. Flat / declining are useful as session-to-session memory: setting "flat" tells future you "I checked velocity here, it's steady, no need to re-evaluate."
What it signifies. ETRP stands for Empirical Threshold Refinement Pipeline—a calibration engine that tests whether the verdict-scoring rules are actually right by comparing them against real historical article outcomes. Instead of trusting that "75% volume / 10% inv-KD / 10% CPC / 5% residual" is the right weight mix because the data team picked those numbers, ETRP runs the math against 1,062 actual McClatchy articles and asks: did the engine's scoring predict which articles would win? If a fitted alternative weighting clearly beats the baseline on held-out data, we adopt it; if not, we keep baseline. First run: 2026-04-27.
How it's sourced. The pipeline lives in calibration/scripts/ as a numbered sequence (00–11)—pulls Snowflake article data, tags content types, fits ensemble candidates, validates via held-out cross-validation + bootstrap CI gates, commits the surviving thresholds to docs/data/verdict-thresholds.js. Audit trail: calibration/PIPELINE.md (pre-registered methodology), calibration/STATUS.md (run-by-run state), calibration/reports/* (intermediate artifacts).
Why it matters. The verdict is the engine's editorial recommendation—High Opportunity / Worth Testing / Skip (plus Monitor for below-floor TH-pipeline trends). If the rules behind that recommendation aren't validated empirically, we're just dressing up someone's gut feel with formulas. ETRP is the discipline that says "before we ship a threshold, we test whether it actually predicts outcomes on real data"—and ships only the refinements that survive bootstrap-CI gates. It's also the mechanism that makes the deferred Phase-5 retest possible—once active-decision data accumulates in the Decision Log, the same pipeline runs again with that data instead of historical PV.
The pipeline takes a historical sample of articles where we know both (a) what the engine would have scored each article based on its keywords, and (b) what actually happened—page views, ranking, engagement. Then it splits the sample into a "training" half (used to fit alternative weightings) and a "held-out" half (used to test whether those fits actually generalize). A fitted alternative only "wins" if it beats baseline on the held-out half by enough margin to clear bootstrap confidence-interval gates (≥ 0.05 Spearman improvement, with the confidence interval of the improvement excluding zero). This is statistical-rigor-by-default—bypasses the "we tuned the model and it looks great in training" trap.
The predicted composite score had a negative Spearman correlation (−0.19 to −0.31) with actual page-view outcomes across every cohort tested. (Spearman correlation = a stat that measures whether one variable's rank ordering matches another's; -1 = perfectly inverse; +1 = perfectly aligned; 0 = no relationship.) Translation: articles the engine would have scored highest historically actually performed slightly worse than ones the engine would have scored lower. For L&E specifically: volume → PV Spearman −0.25 with p=0.028 (statistically significant—the 0.028 is the probability this could be a random coincidence; below 5% is the conventional bar).
Hypothesis for why this happens. Editorial selection bias. When the team had multiple briefs to choose from, ambitious high-volume picks were the ones that got greenlit—and those high-volume queries faced stiffer SERP competition from institutional sites (NIH, Healthline, NYT). Result: ambitious picks lost more SERP battles than the pragmatic lower-score picks that quietly over-performed. The composite score wasn't wrong; it just measured opportunity surface, not what would actually rank given competitive realities.
How to interpret it. Treat the verdict as opportunity-surface assessment, NOT a PV predictor. "High Opportunity" tells you "the demand and difficulty look good on paper"—it does NOT tell you "this article will get lots of page views." Hit rate is determined by execution + angle + timing, not by the score. Use the verdict to identify where to attack; trust your editorial judgment + the cluster framework + the author-authority signal to determine how.
Phase 5 (the deferred next ETRP run) will re-test this finding using active-decision data—i.e. once the team has been making Keep/Skip decisions through the console for ~3 months, we'll have real outcome data tied to specific decisions and can rebuild the calibration on that. The historical-data sub-finding may not persist once we control for editorial selection.
Total spend on the first run. ~6 hours wall-clock · ~36K SEMrush units (1.9% of the 1.93M unit balance available at the time) · zero blockers.
Audit trail. Full pipeline source at calibration/PIPELINE.md, run-by-run state at calibration/STATUS.md, intermediate reports at calibration/reports/.
What it signifies. A coarse classification of "what shape of article should this brief produce"—the role the article plays in the broader site experience. Different content types optimize for different success metrics (acquisition velocity for entry points, time-on-page for explainers, conversions for commerce). Surfaces as a small colored chip on the brief tile + full type label in the drawer's recipe-coordinates panel.
| Type | Color chip | What it is | How it's measured |
|---|---|---|---|
| Blue | Blue | Entry Point—acquisition-driven content. Brings new visitors in from search / discover / social. Often listicle-y, hooky, optimized for first-impression conversion (visit ➝ engaged session). | PVs ÷ new visitors (acquisition velocity) |
| Orange | Orange | Standard Explainer / Deepener—the default for wellness / lifestyle / evergreen explainers. The "trade attention for understanding" piece readers actually finish. | time-on-page + pvs/session + scroll-depth composite |
| Purple | Purple | Bridge / L&E—celebrity / entertainment / drama-adjacent content historically run on L&E publications (Us Weekly, Woman's World). Currently paused—post-2026-04-27 pivot, L&E pubs are frozen until the L&E data pipe is repaired. | Default Deepener composite (pending pipe repair) |
| Green | Green | Converter—commerce / signups / affiliate. Built to drive a specific conversion event, not just engagement. | conversions + signups |
| Untyped | (no chip) | Brief has no explicit content_type assignment. Falls back to Orange-style measurement and recommendations. | Default Deepener composite |
How it's sourced. inferContentType() in util.js uses several signals: the brief's vertical, the persona-fit shape, format hints in the topic + recommended-article text (e.g. "best of" → Green, "what is" → Orange), and any explicit content-type override set on the brief. Untyped briefs are common in V5 because the seed data didn't always carry a content-type assignment; future versions may default-tag at pull time.
Why it matters. Different content roles need different success criteria. Without content typing, an Entry Point brief ("Best Sleep Aids 2026") gets graded on the same time-on-page metric as a Deepener brief ("How Cortisol Affects Sleep")—and the Entry Point will look bad even though it's doing its job (driving new visitors). Content typing lets the engine match each brief against the standard appropriate to its function: acquisition velocity for Blue, deep engagement for Orange, conversions for Green. Also drives format suggestions in the recipe-coordinates panel.
How to interpret it. See a Green chip on a brief? The engagement signal is being measured against conversion / signup metrics—read accordingly (a Green brief with low time-on-page can still be doing great if it's converting). Blue chip = acquisition-velocity grading; the brief should pull in new visitors. Orange chip = standard depth-of-engagement grading. Purple chip = paused—drawer will show a paused banner; do not commit pipeline capacity until L&E data pipe is repaired. No chip (Untyped) = engine is using fallback Orange grading; consider setting an explicit type on the brief if behavior should differ.
What it signifies. The three top-level content collections that organize the post-pivot Trend Hunter site. Every new article lands in exactly one of these collections—they're the IA (information architecture) Trend Hunter is launching with. The console mirrors the same IA so editorial decisions in the tool match the structure readers will encounter on TH itself. Replaces the prior 9-vertical taxonomy that was built for the old multi-pub world.
| Collection | Covers | Example briefs |
|---|---|---|
| Mind & Body | Health, fitness, wellness, mental health, nutrition, sleep, longevity, supplements—anything serving readers' bodies and minds | Sleep performance, hormone health, cardio recovery, GLP-1, fasting protocols |
| Experiences | Travel, food, dining, events, escapes, cultural moments—what readers do outside their daily routine | Wellness retreats, regional food finds, weekend escapes |
| Everyday Living | Home, family, productivity, finance-adjacent, daily-life optimization—the texture of the day-to-day | Cleaning routines, time management, kid sleep schedules |
How it's sourced. inferTHCollection() in util.js maps each brief to one collection by matching the brief's vertical / topic / recommended-article terms against per-collection vocabulary. V5 trend-unit seeds are pre-assigned at pull time, so most briefs don't need runtime inference. Future state: editorial sets the collection explicitly on each brief; inferTHCollection() remains as fallback.
Why it matters. Without a coherent IA, weekly editorial planning becomes "pick from 43 random briefs and hope the mix lands well across the site." With the three-collection IA, the team can balance output across collections deliberately—a quarter that ships 90% Mind & Body content under-serves the Everyday Living readership and starves the Experiences pillar. The Beach lens makes this balance visible by grouping briefs into 3 columns by collection so production planning happens at the right altitude. Today's briefs and Gap map both have a Collection filter so the operator can drill into one area at a time.
How to interpret it. Brief tile shows a small collection chip—the colored glyph next to the topic. Drawer's recipe-coordinates panel shows the full collection label + description. In the Beach lens, each collection becomes its own column with three difficulty rails inside; production-mix tracker (top of lens) shows how the kept inventory distributes across the three. If you're filtering for editorial planning, set Collection = Mind & Body (or whichever) to focus on one pillar at a time. The default unfiltered view shows all collections.
What it signifies. A flag—"precise" or "partial"—that grades how trustworthy the SEMrush data behind a brief actually is. Set at the moment the SEMrush pull runs. "Precise" means the pull returned a full, healthy keyword cluster with complete vol / KD / CPC coverage. "Partial" means the pull came back thin or sparse—fewer keywords than expected, or KD coverage gaps. Surfaces as a soft-confidence badge in the verdict-breakdown panel and shifts the residual nudge that feeds into the composite score.
| Confidence | Trigger | Effect on scoring |
|---|---|---|
| precise | Initial SEMrush pull returned ≥10 keywords with full vol / KD / CPC coverage | +0.10 to residual nudge (bumps composite up slightly—we trust the math behind this brief) |
| partial | Pull returned < 10 keywords OR significant KD-coverage gaps OR SEMrush API timeouts dropped data | −0.15 to residual nudge; "soft confidence" badge appears in the brief drawer's verdict-breakdown panel |
How it's sourced. The pull script (scripts/pull_th_v5.py) inspects each brief's API response after running phrase_fullsearch + phrase_kdi. Counts returned keywords + checks KD-coverage completeness. Sets brief.confidence to 'precise' or 'partial' in briefs.js at write time. Read by residualNudge() in util.js at runtime to compute the composite.
Why it matters. Two briefs can score identically on the composite math but be backed by very different data quality. A brief whose composite was computed from 12 keywords with full coverage is genuinely more trustworthy than one built on 4 keywords with KD gaps. The confidence flag makes that data-quality dimension visible to the operator and bakes a small penalty into the composite for partial briefs (so "thin-data" briefs don't crowd into the top of triage just because they got lucky on the few keywords they had).
How to interpret it. A "soft confidence" badge in the verdict breakdown means the brief's verdict is directional, not definitive—the math is doing its best with thin SEMrush data. Action: run scripts/repull_weak_briefs.py against this brief's ID. The script uses a multi-seed strategy (tries the primary seed, then 1–2 fallback seeds derived from the brief's topic, picks whichever yields the richest cluster). If the re-pull comes back precise, the badge clears on next page load. If it stays partial after re-pull, the keyword space genuinely lacks rich SEMrush coverage—that's a structural property of the topic, not a fixable data issue. Treat partial briefs as "score directionally, validate with editorial judgment before commitment."
What it signifies. The best (lowest-numbered) Google ranking position one of our portfolio pubs already holds for a keyword. Lower is better. Position 3 means a portfolio pub already ranks #3 in Google for that exact query—strong existing authority. Position 47 means somewhere on page 5—minimal but real foothold. Position 999 is a special sentinel value meaning "none of our pubs rank in the top 50 for this keyword"—not a literal rank, just the engine's way of marking unranked.
| Value | Position meaning | What this signals |
|---|---|---|
| 1–10 | Page 1 ranking | Strong existing authority—we already win this query. Defend / refresh when freshness window expires. |
| 11–25 | Page 2 ranking | Leverageable foothold. Fresh content + cluster expansion realistically pushes us into page 1. |
| 26–50 | Pages 3-5 | Minimal authority but a ranking exists—Google has decided we're at least relevant on this query. Foundation we can build on. |
| 999 | Sentinel: no portfolio pub in top 50 | Cold start—we have no existing authority. Greenfield decision. Backfill cron only pulls top-50; anything beyond collapses to 999 (not a literal "rank 999"). |
How it's sourced. SEMrush phrase_organic endpoint returns the top-50 ranking domains per keyword. The backfill_positions.py script runs this for every Kept brief's keywords against the portfolio pub list and stores the best-observed rank as topKeywords[].ourPos in briefs.js. The monthly cron (`monthly-semrush-refresh.yml`, fires 1st of month at 8:13am Dallas) auto-refreshes Kept briefs. Manual refresh: python3 scripts/backfill_positions.py --scope=kept (or --scope=brief:ID,ID for targeted refresh).
Why it matters. Existing authority is one of the most valuable inputs to a verdict—and one of the most often overlooked. A brief with KD 65 looks hard until you see "our pos: 14 on miamiherald.com"—meaning Miami Herald already ranks page 2 for that keyword and is very likely the right pub to run the cluster through. The DA-shift mechanism (see ) uses this data to bump effective tier per pub. The KD ≥ 80 hard auto-Skip rule also has a "tangential-foothold" exemption: if any keyword has ourPos ≤ 20, the auto-Skip is bypassed and the operator can Keep the brief. So an "our pos: 17" on even a single keyword can flip a brief's verdict from auto-Skip to actionable.
How to interpret it. Drawer's keywords table shows the per-keyword ourPos column. Look for any value ≤ 25—those are foothold opportunities. All-999 columns mean we'd be entering the SERP cold; combine with KD to gauge difficulty. When you see "our pos: 7" alongside a KD-50+ keyword, that's a cluster-expansion opportunity (we already win one corner of the topic; more articles can extend the win). When you see all 999s + KD ≥ 80, the auto-Skip will fire—and rightfully—unless a tangential-foothold keyword exists that the engine missed.
No reconciliation data yet. scripts/precompute_decisions_outcomes.py{' '}
emits docs/data/decisions-with-outcomes.js by joining the Decision Log
(D1 worker) with Layer 0 outcomes + Layer 10 revenues. Either it hasn't run yet, or no
decisions have been recorded. Once you've Kept/Skipped/Deferred at least one brief and
the daily cron has fired, this section populates.
As of {data.asof}, {rows.length} decisions on record. Outcomes joined from
Layer 0 (TRACKER_ENRICHED articles published since the brief's attribution floor) and
Layer 10 (live BURT revenue attribution).
| Action | N | With matches | In-zone | Cold | Total PVs (share-adjusted) |
|---|---|---|---|---|---|
| {label} | {set.length} | {matched(set).length} ({pct(matched(set).length, set.length)}) | {inZone(set).length} ({pct(inZone(set).length, matched(set).length)}) | {cold(set).length} ({pct(cold(set).length, matched(set).length)}) | {Math.round(set.reduce((s, r) => s + (r.outcome?.total_pvs_share_adjusted || 0), 0)).toLocaleString()} |
Read this: the headline number is "Keep · in-zone %." That's the calibration test. If <30% of Kept briefs land in-zone, the verdict thresholds are too loose. If >70%, they're too tight (we're skipping briefs that would have worked). The ETRP- validated 30/50/20 cuts predict ~50% in-zone for Keeps; the rest is split between foothold (still useful) and cold (genuine misses).
Four moving parts decide which published article credits which brief—and how much credit it gets. Read this once; the rest of Part IV makes more sense after.
Each brief carries a keyword set (the SEMrush seeds plus expansions). Each published article carries its own extracted keyword set. An article credits a brief when the two sets intersect on at least one keyword. One article can credit multiple briefs.
A brief's addedAt timestamp is when it entered the queue; its attributionFloor is the earliest publish date eligible to credit it (default = addedAt; can be back-dated when a brief replaces an older one). Articles published before the floor never credit the brief—they predate the decision.
When an article credits N briefs, full-credit PV gives the entire pageview total to each—useful for "did this brief produce anything?" Share-adjusted divides PVs evenly across the N briefs—the right number when summing across briefs without double-counting traffic.
Article-vs-co-median is weighted by 0.95^weeks_since_publish, then averaged. Floor: needs ≥3 articles before the recency-weighted figure displays—fewer and the average is too noisy to act on.
Outcome distribution per action class. Columns sum to the action's matched-articles total.
| Action | N matched | In-zone | Foothold | Cold | Avg AVC | Avg AVC (recency-weighted) |
|---|---|---|---|---|---|---|
| {label} | no matches yet | |||||
| {label} | {m.length} | {inz} ({pct(inz, m.length)}) | {fh} ({pct(fh, m.length)}) | {cd} ({pct(cd, m.length)}) | {avg(avc)} | {avg(avcRw)} |
Avg AVC is the article-vs-co-median proxy averaged across matched articles. ≥1.0 means typical article in this brief outperforms the company median. The recency- weighted version decays older articles by 0.95 per week and floors at 3 articles.
Each Kept brief plotted against its observed AVC. The diagonal line is "perfect calibration"—predictions track outcomes. Points above the line outperformed; below underperformed. (Chart renders client-side via inline SVG.)
Distribution of (predicted AVC − observed AVC) for Kept briefs with ≥3 matches. Green bars near zero = well-calibrated; red bars in the tails = systematic over- or under-prediction.
Brier = mean squared error between verdict-implied probability and the in-zone outcome (1 = in_zone, 0.5 = foothold, 0 = cold). Lower is better. Reliability curve bins predicted probability into deciles and plots observed in-zone rate per bin against the diagonal of perfect calibration.
Calibration sliced by thV5.play_num. Plays with Brier > 0.25 (red) are where the model is most miscalibrated—investigate before trusting verdicts there.
Briefs whose recorded action changed across the quarter—a Skip that became a Keep, a Keep that became a Defer. Useful for spotting unstable verdicts and tracing what changed in the snapshot when the call moved.
Every decision in the log, joined with its current outcome state. Filter chips narrow to a slice; sortable columns; click a brief id to jump.
No Kept briefs with ≥3 matched articles yet—chart needs sample size.
; } // X-axis: brief's snapshot.kd (proxy for difficulty; lower = predicted easier). // Y-axis: observed avg_article_vs_co_median (1.0 = on-median; >1 = outperforming). const points = rows.map(r => ({ id: r.brief_id, x: Number(r.snapshot?.kd ?? 50), y: Number(r.outcome?.avg_article_vs_co_median ?? 1.0), })).filter(p => Number.isFinite(p.x) && Number.isFinite(p.y)); if (points.length === 0) returnInsufficient data to plot.
; const W = 600, H = 280, M = 32; const xs = points.map(p => p.x), ys = points.map(p => p.y); const xMin = Math.min(...xs, 0), xMax = Math.max(...xs, 100); const yMin = Math.min(...ys, 0.3), yMax = Math.max(...ys, 1.7); const sx = (x) => M + (W - 2 * M) * (x - xMin) / (xMax - xMin || 1); const sy = (y) => H - M - (H - 2 * M) * (y - yMin) / (yMax - yMin || 1); return ( ); } function ReconciliationTable({ rows }) { const [sortKey, setSortKey] = React.useState('decision_ts'); const [dir, setDir] = React.useState('desc'); const sorted = React.useMemo(() => { const copy = rows.slice(); copy.sort((a, b) => { const av = sortKey.includes('.') ? sortKey.split('.').reduce((o, k) => o?.[k], a) : a[sortKey]; const bv = sortKey.includes('.') ? sortKey.split('.').reduce((o, k) => o?.[k], b) : b[sortKey]; const cmp = (av ?? -Infinity) < (bv ?? -Infinity) ? -1 : (av ?? -Infinity) > (bv ?? -Infinity) ? 1 : 0; return dir === 'asc' ? cmp : -cmp; }); return copy.slice(0, 200); // Cap at 200 to keep DOM manageable }, [rows, sortKey, dir]); const sh = (key) => () => { if (sortKey === key) setDir(d => d === 'asc' ? 'desc' : 'asc'); else { setSortKey(key); setDir('desc'); } }; const sortIcon = (key) => sortKey === key ? (dir === 'asc' ? ' ▲' : ' ▼') : ''; return (| Brief{sortIcon('brief_id')} | Action{sortIcon('action')} | When{sortIcon('decision_iso')} | Articles{sortIcon('outcome.matched_articles')} | PVs (adj){sortIcon('outcome.total_pvs_share_adjusted')} | Avg AVC{sortIcon('outcome.avg_article_vs_co_median')} | State{sortIcon('outcome.best_position_state')} | Note |
|---|---|---|---|---|---|---|---|
{r.brief_id} |
{r.action || '—'} | {r.decision_iso?.slice(0, 10) || '—'} | {r.outcome?.matched_articles ?? 0} | {r.outcome?.total_pvs_share_adjusted != null ? Math.round(r.outcome.total_pvs_share_adjusted).toLocaleString() : '—'} | {r.outcome?.avg_article_vs_co_median?.toFixed(2) ?? '—'} | {r.outcome?.best_position_state || '—'} | {r.note || ''} |
Need ≥10 Kept rows with recorded outcomes—currently {usable.length}.
; } const pairs = usable.map(r => ({ p: predictedProb(r), a: actualOutcome(r) })); const brier = pairs.reduce((s, x) => s + (x.p - x.a) * (x.p - x.a), 0) / pairs.length; const interp = brier < 0.15 ? 'well-calibrated' : brier < 0.25 ? 'fair' : 'miscalibrated'; const interpColor = brier < 0.15 ? '#4ea88f' : brier < 0.25 ? '#c0a050' : '#a86a4e'; // Bin into 10 deciles by predicted_prob const bins = Array.from({ length: 10 }, () => ({ ps: [], as: [] })); pairs.forEach(x => { const idx = Math.min(9, Math.max(0, Math.floor(x.p * 10))); bins[idx].ps.push(x.p); bins[idx].as.push(x.a); }); const points = bins.map((b, i) => { if (b.ps.length === 0) return null; const meanP = b.ps.reduce((s, v) => s + v, 0) / b.ps.length; const meanA = b.as.reduce((s, v) => s + v, 0) / b.as.length; return { i, meanP, meanA, n: b.ps.length }; }).filter(Boolean); const W = 360, H = 280, M = 36; const sx = (p) => M + (W - 2 * M) * p; const sy = (p) => H - M - (H - 2 * M) * p; return (Brier: {brier.toFixed(3)} · {interp} (<0.15 well-calibrated · 0.15–0.25 fair · >0.25 miscalibrated · n={pairs.length})
No matched Kept rows with AVC yet.
; } // Buckets at 0.2 from -2 to +2 → 20 buckets const STEP = 0.2, MIN = -2, MAX = 2; const nBuckets = Math.round((MAX - MIN) / STEP); const counts = Array.from({ length: nBuckets }, () => 0); pts.forEach(r => { const clamped = Math.max(MIN, Math.min(MAX - 1e-9, r)); const idx = Math.floor((clamped - MIN) / STEP); counts[idx]++; }); const maxC = Math.max(...counts, 1); const W = 600, H = 220, M = 32; const bw = (W - 2 * M) / nBuckets; const colorFor = (centerResidual) => { const a = Math.abs(centerResidual); if (a < 0.3) return '#4ea88f'; if (a < 0.7) return '#c0a050'; return '#a86a4e'; }; return ( ); } // ─── Per-Play breakdown ────────────────────────────────────────────────────── function PerPlayBreakdown({ rows }) { const [sortKey, setSortKey] = React.useState('brier'); const [dir, setDir] = React.useState('desc'); const grouped = React.useMemo(() => { const map = new Map(); (rows || []).forEach(r => { const play = r.snapshot?.thV5?.play_num ?? r.thV5?.play_num ?? null; if (play == null) return; if (!map.has(play)) map.set(play, []); map.get(play).push(r); }); const out = []; map.forEach((set, play) => { const inz = set.filter(r => r.outcome?.best_position_state === 'in_zone').length; const avcs = set.map(r => r.outcome?.avg_article_vs_co_median).filter(v => typeof v === 'number'); const avgAvc = avcs.length ? avcs.reduce((s, v) => s + v, 0) / avcs.length : null; const briers = set.map(r => { const a = actualOutcome(r); if (a === null) return null; const p = predictedProb(r); return (p - a) * (p - a); }).filter(v => v !== null); const brier = briers.length ? briers.reduce((s, v) => s + v, 0) / briers.length : null; out.push({ play, n: set.length, inzone_rate: set.length ? inz / set.length : 0, avg_avc: avgAvc, brier }); }); return out; }, [rows]); const sorted = React.useMemo(() => { const copy = grouped.slice(); copy.sort((a, b) => { const av = a[sortKey], bv = b[sortKey]; const cmp = (av ?? -Infinity) < (bv ?? -Infinity) ? -1 : (av ?? -Infinity) > (bv ?? -Infinity) ? 1 : 0; return dir === 'asc' ? cmp : -cmp; }); return copy; }, [grouped, sortKey, dir]); if (grouped.length === 0) { returnNo Plays recorded on Kept rows yet.
; } const sh = (k) => () => { if (sortKey === k) setDir(d => d === 'asc' ? 'desc' : 'asc'); else { setSortKey(k); setDir('desc'); } }; const ic = (k) => sortKey === k ? (dir === 'asc' ? ' ▲' : ' ▼') : ''; return (| Play{ic('play')} | N{ic('n')} | In-zone %{ic('inzone_rate')} | Avg AVC{ic('avg_avc')} | Brier{ic('brier')} |
|---|---|---|---|---|
| {row.play} | {row.n} | {(row.inzone_rate * 100).toFixed(0)}% | {row.avg_avc != null ? row.avg_avc.toFixed(2) : '—'} | {row.brier != null ? row.brier.toFixed(3) : '—'} |
No verdict flips recorded this quarter.
; } const fmtDelta = (v, suffix = '') => v == null ? '—' : `${v > 0 ? '+' : ''}${typeof v === 'number' ? (Math.abs(v) >= 100 ? Math.round(v) : v.toFixed(1)) : v}${suffix}`; return (| Brief | Flip | Days | Δ vol | Δ KD |
|---|---|---|---|---|
{f.brief_id} {f.topic} |
{f.prior} → {f.curr} | {f.days != null ? `${f.days}d` : '—'} | {fmtDelta(f.volDelta)} | {fmtDelta(f.kdDelta)} |