seo-freshness (M13)

Freshness is a recency signal both classic ranking systems (Query Deserves Freshness) and AI answer engines weigh — Perplexity in particular favours recently-updated sources when citing. Date fields tie directly to Article schema (cross-check M5); see

references/schema-tier1.md

for the date rules.

Inputs

Work from the PageSnapshot named in your dispatch envelope: read

parsed

from

<run_dir>/pages/<slug>.json

(

jsonld[]

metas[]

for

article:published_time

modified_time

) plus

headers.last-modified

; Grep

pages/<slug>.html

for verbatim evidence; site artifacts live in

<run_dir>/site/{robots.json,sitemaps.json,discovery.json}

. Deterministic findings already emitted by

audit.mjs

are listed in

<run_dir>/findings.deterministic.json

— do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run

node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"

and use the printed snapshot path.

Audits

Working from the PageSnapshot (

parsed_rendered

when

render.used

is not

none

, else

parsed

Visible dates: detect on-page "Published" / "Updated on" / "Last reviewed" patterns and their values (ISO or human-readable).

Schema dates: parse

datePublished

dateModified

from JSON-LD

Article

BlogPosting

NewsArticle

Agreement: visible date and schema date must match; flag mismatches and schema dates with no visible counterpart (AI engines distrust hidden-only dates).
Staleness: estimate content age (most recent reliable date) vs topic volatility — fast-moving topics (prices, tooling, "best X 2026", regulations) decay faster than evergreen reference content. Report stale, not just old.
Pattern hygiene: "updated on" with no substantive content change is a freshness anti-pattern — note it, never recommend it.

Fixes

AUTO (
```
fixable: auto
```
): inject a missing
```
dateModified
```
into existing Article schema as an additive diff for
```
fix
```
. Never backdate to a false date — use the verifiable last-change date (e.g. Last-Modified header / repo mtime / today) or leave a clearly-marked
```
TODO
```
placeholder the user confirms.
PROPOSED (
```
fixable: proposed
```
): surface visible-vs-schema date mismatches with the corrected value as a draft requiring per-item accept; never auto-rewrite a date the user must verify.
ADVISORY (
```
fixable: advisory
```
): recommend a genuine content refresh for stale-on-volatile pages — the tool never writes editorial content. Never fabricate dates or invent an update that did not happen.

Verification

```
dom_assert
```
: visible date string present and parses; matches schema value.

schema_validator

datePublished

dateModified

present, valid ISO 8601,

dateModified >= datePublished

```
header_check
```
: HTTP
```
Last-Modified
```
header corroborates the claimed modification date.
When the live tier (header fetch / validator) is unavailable, status is
```
needs_api
```
, never a false
```
pass
```
.

Findings

Findings conform to

schema/finding.schema.json

; axis

both

; confidence

directional

throughout. Severity policy: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an

established

severity-5

fail

in an active category can cap a score (

references/scoring-model.md

). Freshness never caps.

M13.datemodified.missing

— Article schema with

datePublished

but no

dateModified

(

fail

, severity 3,

fixable: auto

M13.dates.visible_schema_mismatch

— visible "Updated May 2025" against schema

dateModified: 2023-01-10

(

warn

, severity 3,

fixable: proposed

```
M13.content.stale_volatile
```
— a "best X 2024" page unchanged for two years on a fast-moving topic (
```
warn
```
, severity 2,
```
fixable: advisory
```
).
```
M13.schema.date_unparseable
```
— a date field that exists but does not parse as ISO 8601, or a page with several
```
dateModified
```
values (the latest wins, and the conflict is reported) (
```
warn
```
, severity 2,
```
fixable: proposed
```
). Emit this instead of a mismatch: an unreadable date is a parsing gap, not proof the dates disagree. Each finding:
```
evidence.observed
```
quotes the page (date string + selector);
```
verification.reproduce
```
is a runnable assertion (e.g.
```
node "${CLAUDE_PLUGIN_ROOT}/scripts/check-freshness.mjs" --snapshot <pages/<slug>.json> [--lang en|es|auto]
```
(or
```
--url <u>
```
));
```
expected_impact
```
is banded + confidence-tagged, with any published number confined to
```
rationale
```
with a citation.

Honesty

Freshness is a contextual signal, not a universal ranking boost — refreshing evergreen content rarely moves rankings, and a
```
dateModified
```
bump without a real content change is detectable and adds no durable value. Confidence here is directional, never
```
established
```
; never present a date edit as a guaranteed ranking gain or backdate to fake recency.
Date parsing is language-bound: Spanish month names and
```
article:published_time
```
/
```
article:modified_time
```
are read, but an unrecognized format produces
```
M13.schema.date_unparseable
```
, never a fabricated mismatch.

seo-freshness

NPX Install

Tags

SKILL.md Content