| name | freshness-aware-retrieval |
| description | Staleness detection and freshness-weighted retrieval: recency preferences by topic class, stale-source quarantine for pricing/policy/security, and re-ingestion signals. Owned by Metis. |
| user-invocable | false |
| argument-hint | <check-freshness|weight-results> |
| allowed-tools | ["Read","Grep"] |
Freshness-Aware Retrieval
A stale source on the wrong topic is worse than no source: it produces
confident, citable, wrong answers. This skill defines how the hearth
weights recency and when age disqualifies a source outright.
Purpose
Prevent stale-context failures (the research doc's "stale context and
data drift" risk) by making freshness a first-class retrieval signal with
topic-dependent thresholds.
When to use
- Metis on every retrieval pass.
- Asclepius when runbook age matters (infra changes fast).
- Themis when scoring
kb-citation-grounding's source-freshness
dimension.
Topic freshness classes
| Class | Examples | Stale threshold | On stale |
|---|
| Volatile | pricing, plan limits, policy terms, security advisories, legal language | 90 days or any newer conflicting doc | source disqualified → treat as no source (Article VI.3) |
| Active | product features, UI walkthroughs, integrations, runbooks | 6 months | usable with an "as of " caveat in the draft |
| Stable | concepts, architecture, formats, troubleshooting fundamentals | 24 months | usable; prefer newer when scores tie |
When a topic spans classes, the most volatile component sets the class.
Weighting rules
- Retrieval ranking blends relevance with recency; on near-tie relevance,
newer wins.
- Every citation carries its
as-of-date — the date is part of the
citation form, so Themis and the customer can both see it.
- A newer document that contradicts an older one wins, AND the conflict
is filed as a KB gap (the older doc needs retirement — that is
curation signal, not noise).
- Unknown date = treat as oldest in its class; flag for curation.
Re-ingestion signals
File a KB gap note (kb-gap-detection) tagged freshness when:
- a volatile-class answer had to fail closed for staleness,
- two sources conflicted on currently-true facts,
- a customer corrected the squad with newer reality than the KB holds.
These notes are the change-data-capture signal the KB pipeline consumes;
the squad does not edit the KB itself, it reports with evidence.
Failure modes
- Recency worship: a fresh-but-thin doc outranking the definitive
older one on a stable topic. Class thresholds exist precisely so
stable topics keep their deep sources.
- Caveat laundering: "as of last year" buried in a footnote on a
pricing answer. Volatile topics do not get caveats; they get fresh
sources or fail closed.
- Silent conflict resolution: averaging the old and new price.
Conflicts surface (Article VI.3); they are never averaged.