content-refresh

name	content-refresh
description	Specialist tool for Stage 3 Update Decision routing logic. Identifies pages needing refresh based on dateModified > 6mo OR ranking dropped >5 positions in 30d OR BLS data older than current release OR ROOS dropped >20% vs 90d baseline OR freshness SLA breached. Triggers refresh PRs.
metadata	{"family":"ops","owner":"content","last_reviewed":"2026-04-29T00:00:00.000Z","version":"1.0.0","related_skills":["seo-foundations","marketing-foundations","traffic-monitor","seo-health","content-writer"],"kpis":["100% of pages within template freshness SLA","Refresh cycle time <14d (Discovery → Stage 8 PASS)"],"marketing_pillar":34,"seo_standard":"B","kpi_tier":123,"funnel_stage":"all","maturity_stage":"diagnostic","used_by_stages":[3]}

Content Refresh

Decision logic for Stage 3 Update Decision: when to refresh existing content vs create new.

When to Use

• Stage 3 Update Decision — exclusive consumer for refresh routing logic.
• Weekly autoresearch — surfaces refresh candidates as 90_10_class: striking_distance opportunities.

Do Not Use When

• Need to write the actual refresh content — use content-writer.
• Need to verify the refresh post-ship — use seo-health + web-vitals.

Refresh Triggers

Any one of these triggers a refresh recommendation:

Trigger	Source	Threshold
dateModified > 6mo	content data file frontmatter	180d default; per-template SLA may shorten
Ranking dropped >5 positions in 30d	gsc-mcp.query_search_analytics	5 positions
BLS data cited is older than current release	nextjs-app/src/lib/data/data-sources.ts cross-reference	annual BLS OEWS release (typically May)
ROOS dropped >20% vs 90d baseline	ops/performance-attribution	20%
Freshness SLA breached per template	per-template SLA in marketing-foundations/reference/excellence-targets.md	template-specific (30/90/180/365 days)

Per-Template Freshness SLAs

Template	SLA	Rationale
role-page	90d	BLS data + pay range may shift
city-page	180d	City data slower-moving
city-role-page	90d	BLS + city data
guide-article (BLS-cited)	30d	After BLS release
guide-article (general)	180d	Slow-moving general advice
tool-page	365d	Tool logic stable; UX may need yearly polish
comparison-page	90d	Comparison numbers shift
cep-trigger-page	90d	CEP context may shift
original-research-page	365d	Annual research cycle
state paycheck calculator	60d (after tax-table updates)	State + federal tax law changes
state unemployment guide	90d	State benefit changes
how-to-become guide	180d	Career path slower-moving
interview-questions bank	180d	Question relevance shifts slowly

Workflow

1. Pull cached evidence from traffic-monitor (ranking drops) + performance-attribution (ROOS decay) + content data file frontmatter.
2. Cross-reference BLS data freshness — check every page citing BLS against current published release date.
3. For each candidate page:
   • Determine which trigger fires.
   • Estimate refresh effort (1-3h baseline, +1h for data-update if BLS-tied).
   • Compute lift_per_effort for the refresh.
4. Decide route per Strategic Brief:
   • refresh-existing if any refresh trigger fires AND page exists.
   • create-new if topic is genuinely new + similar page doesn't exist.
   • extend-template if the brief needs template work to deliver value.
   • skip if lift_per_effort below median candidate this week.
5. Output route decision for Stage 4 Creation to action.

Output Contract

Per Strategic Brief:

brief_id: <slug>-<date>
route: refresh-existing | create-new | extend-template | skip
target_file: <path-to-feature-data-file>
refresh_trigger: <one-of-the-5-triggers>
estimated_diff_lines: <number>
estimated_effort_hours: <1-3 typically>
rationale: <text>

Aggregated markdown at nextjs-app/docs/reports/<date>/03-update-decisions.md.

Refresh PR Pattern

For refresh-existing routes:

1. Stage 4 Creation produces a focused diff (data-only when possible).
2. Stage 5 Brand+Guardrail re-checks DBAs + citations.
3. Stage 7 UI commits the diff.
4. Stage 8 UX runs pnpm audit:responsive + post-ship attribution check at 30d.

PR title: refresh: <slug> (<refresh_trigger>)

References

• marketing-foundations/reference/excellence-targets.md — freshness SLAs
• .agents/rules/030-launch-cadence.mdc — launch cadence context (refresh shouldn't happen during pillar's pre-launch window)