processed_volume_trend_meta — refresh-detection signals

The first of three families inside processed_volume_trend_meta. Drives the two refresh extractors (extract_gt.py, extract_gkp.py).

Keys

Key	Type	Meaning
needs_gt	bool	If true, extract_gt.py will queue this keyword for refresh
gt_tier	int (0 / 1 / 2)	1 = urgent (jump to head of queue); 2 = deferred (long tail); 0 = not needed
needs_gkp	bool	Same role for extract_gkp.py
gkp_tier	int (0 / 1 / 2)	GKP equivalent of gt_tier
refresh_signals	object	Per-signal evidence — see below

Per-signal evidence

The refresh_signals sub-object exposes the individual rules that flipped the needs_* flags. Each signal is a boolean; multiple may be true on the same keyword.

Signal	Meaning
surge	GSC volume spike that isn't yet corroborated by GT/GKP — need fresh GT/GKP to verify
stale_gt	gt_last_update older than the staleness threshold for this keyword
stale_gkp	gkp_last_update older than threshold
divergence	GT and GSC have diverged enough that one of them is suspect
missing_gkp	No GKP data for this keyword and we believe there should be
shape_mismatch	GT and the blended trend have different shapes (e.g. one shows seasonality the other doesn't)

How it's computed

detect_refresh_needs() in processing.py:L681. The function takes the just-computed trend + the prior meta + each source's last_update timestamp and returns the flag set + tier assignment + signal sub-object.

Tier assignment is informed by:

• surge or divergence true → tier 1 (urgent)
• stale_* only → tier 2 (deferred)
• All signals false → tier 0 (no refresh)

(Exact rules live in the archived _archive/refresh_detection.md and the function source; Phase 3 will decompose this into decision nodes.)

Edge cases

• All flags false — the keyword is "fresh enough"; nothing queued.
• Multiple signals true — usually means a more substantive issue (the keyword's data is wrong in multiple ways). Tier 1 wins.
• Sub-gate keywords — processing.py's outer gate means the function isn't called for keywords below the volume threshold; the meta isn't written and the flags don't exist.

Adding new signals (experimentation)

If you want to add a new refresh signal:

1. Add the rule inside detect_refresh_needs() and emit a new key inside the refresh_signals sub-object.
2. Decide whether it flips needs_gt and/or needs_gkp (and at what tier).
3. Add the key to the table above on this page.
4. Optional: extend the extractor pages to mention the new signal.

The refresh_signals sub-object is intentionally open-ended for exactly this reason.

See also

• Overview
• extract_gt · extract_gkp — consumers
• Archive: _archive/refresh_detection.md · _archive/REFRESH_PIPELINE.md — original signal definitions and tier-assignment logic; Phase 3 will decompose into decision nodes