knowledge-file-staleness-sweep

name

knowledge-file-staleness-sweep

description

Run a periodic staleness sweep over all `plugins/<plugin>/knowledge/*.md` files and any decision-tree sections — flag entries past their `last-verified` window, categorize by re-verification effort (Tier 1-5 per Researcher schema), produce a remediation queue with named re-verifiers. Reach for this skill on the Researcher's weekly cadence OR before a marketplace release. Used by `deep-researcher` (primary) plus the maintainer.

Skill: knowledge-file-staleness-sweep

You are running a sweep across the marketplace's knowledge surfaces to find content that's drifted out of currency. The sweep produces a remediation queue — not silent date-stamp refreshes. The output is actionable per entry: re-verify against N sources, deprecate, or promote.

This skill is the operational arm of the Researcher meta-skill (researcher.md). Researcher decides what needs updating; this skill is how to find it systematically.

When to invoke this skill

• Weekly Deep Research cadence — the Researcher's Sunday/Monday sweep includes this skill.
• Pre-release gate — before tagging any plugin release, run the sweep and block-on-merge for any knowledge file inside the release diff with last-verified > 90 days.
• Post-incident — when a real engagement surfaces that a knowledge file gave wrong advice, run a targeted sweep over related files in the same plugin.
• Quarterly maintainer audit — sweep the full marketplace, not just one plugin.

Scope

⛔ SWEEP THE CONSTITUTION FILES FIRST — they are the highest-priority surface.

CLAUDE.md, AGENTS.md and every plugins/*/CLAUDE.md are loaded into every session, so a stale claim in one of them is not a documentation lag — it is a prior that every future agent starts out believing, with nobody left to cross-examine it. The knowledge files below are read on demand; these are read unconditionally, which makes them the worst place for drift and the first place to look.

This is not hypothetical. An agent read a stale "Still open" list in one of these files, took it at face value, and told the maintainer twice that his command-review tribunal was broken on macOS — while it had been working for releases. The reader it fooled was the constitution's primary audience: an agent.

What to look for here is different from a last-verified date. These files carry no freshness stamps; they carry status claims. Sweep for:

Claim shape	How to test it
"Still open" / "not yet built" / "unowned"	find the artifact — did it ship?
"Gate N is unrun / never registered"	grep audit-gates.sh for the gate
"path/to/file was deleted / is a phantom"	is it on disk?
a milestone's "Next:" or "Deferred:" list	did a later milestone close it?

The rule, already stated in the v0.196.0 supersession note: when you close a door, supersede the entry that says it's open in the same PR. A sweep that finds a closed door still described as open should fix it there, not file it.

Gate 202 (scripts/check-constitution-claim-staleness.py) mechanizes the narrow, binary subset of this — a claim that a named artifact is missing where it is in fact present. It deliberately does not judge whether a "Still open" item is genuinely still open; that needs a judgment about the world, not a fact about the tree. That judgment is this sweep's job, and the gate is the floor beneath it, not a replacement for it.

Two phrasings are correct and must not be "fixed": a conditional ("the hook allows everything if the manifest is absent" — a statement about a code path) and past-tense history ("Gate 184 was unreachable" inside a milestone that records the fix). Both were real false positives caught before Gate 202 shipped. This repo keeps superseded entries as dated records on purpose.

The knowledge-file sweep then runs against three surfaces:

1. plugins/*/knowledge/*.md — long-form curated reference material.
2. plugins/*/skills/*.md — skill files with explicit last-verified: dates (most skills don't carry these, but some do).
3. plugins/*/scenarios/*.md — dated war-story narratives (the contributed_at field substitutes for last-verified).
4. Any file containing ## Decision Tree: section headers anywhere under plugins/ — per the convention in docs/best-practices/decision-trees-in-knowledge-files.md.

Thresholds

Per the decision-tree-in-knowledge-files best-practice doc:

Age (since last-verified)	Disposition
0-90 days	Fresh — no action.
90-180 days	Flag for re-verification. Surface in the remediation queue. Knowledge file is still usable.
180-365 days	Block on inclusion in a release until re-verified. Knowledge file should not appear in release notes or be cited in agent output without an inline freshness disclaimer.
365+ days	Strong-deprecate candidate. Either re-verify with explicit reason for keeping ("still authoritative because X"), or queue for removal.

These thresholds apply to decision trees and to knowledge files. Scenarios use a softer threshold — they're already labeled "unverified" and carry a contributed_at date that the user sees, so the staleness signal is built into how they're surfaced. Sweep scenarios at 365 days for the strong-deprecate question only.

Categorization by Researcher Tier

For each flagged entry, the sweep assigns one of the five Researcher categorization tiers — this determines the re-verification effort:

Tier	Label	Re-verification effort
Tier 1	Consensus / Widely Accepted	Re-verify against ≥3 sources (official + 2 community). If all 3 still agree → bump date, no content change. If divergence has emerged → recategorize.
Tier 2	Strong but Contextual	Re-verify against 2 sources. Pay attention to whether the "context" caveat is still accurate (e.g. "premium-only" might now be GA).
Tier 3	Divergent / Contrarian Views	Re-verify against the named source(s) in the file. Has the contrarian view become mainstream, been refuted, or stayed niche?
Tier 4	Emerging / Experimental	Re-verify quarterly regardless of the 90-day threshold. Emerging content has the fastest decay. Either promote to Tier 1/2, deprecate to Tier 5, or refresh as still-emerging.
Tier 5	Deprecated or Risky	Sweep result is propose removal unless there's an explicit "keep as cautionary" rationale.

Sweep mechanics

Step 1 — Inventory entries with explicit dates

# Find all files with a last-verified field
grep -rln '^last-verified:\|^\*\*Last verified:\*\*' plugins/

# Find all decision-tree sections
grep -rln '^## Decision Tree:' plugins/

Step 2 — Extract dates and compute ages

For each match, parse the YYYY-MM-DD from the last-verified field (or **Last verified:** YYYY-MM-DD in decision-tree blocks). For files with no explicit field, fall back to git blame age on the first content line as a proxy — record the file as "no explicit stamp, git-age N days" in the remediation queue with a note that the file should grow a last-verified field.

Step 3 — Categorize each entry

For each entry past the 90-day threshold:

1. Read the file's existing tier label (most knowledge files in the marketplace declare a tier in their frontmatter or first paragraph).
2. If no tier is declared, infer one from the content — but flag the missing-tier-label as a separate remediation item.
3. Assign the re-verification effort per the Tier table above.

Step 4 — Assign the re-verifier

Route by plugin + topic:

Plugin + topic	Re-verifier
ravenclaude-core/knowledge/<anything>	deep-researcher
power-platform/knowledge/<anything>	power-platform specialist matching the topic (dataverse-architect for schema, flow-engineer for flows, etc.) + deep-researcher for Microsoft-doc verification
<domain>/knowledge/<anything>	The corresponding domain specialist + deep-researcher
Decision trees	The agent that owns the decision (cited in the tree's preamble)
Scenarios > 365 days	The maintainer (manual deprecate decision)

If no clear owner exists, route to the maintainer with a note that the file needs an ownership label.

Step 5 — Produce the remediation queue

Output a single CSV or markdown table:

| File | Age (days) | Tier | Effort | Re-verifier | Disposition |
|---|---|---|---|---|---|
| plugins/power-platform/knowledge/programmatic-flow-creation.md | 142 | Tier 1 | ≥3 sources | power-platform/flow-engineer + deep-researcher | refresh |
| plugins/power-platform/knowledge/dataverse-customer-column.md | 211 | Tier 2 | 2 sources | power-platform/dataverse-architect | **release-block** |
| plugins/data-platform/knowledge/jwt-embed-flow.md | 38 | Tier 4 | quarterly | data-platform/skills/jwt-embed-issuance owner | fresh-but-Tier-4-flag |
| plugins/ravenclaude-core/knowledge/old-airbyte-pattern.md | 412 | Tier 5 | n/a | maintainer | propose-removal |

Save the queue to .ravenclaude/runs/<sweep-id>/staleness-queue.md so the Researcher's structured output can point to it.

Step 6 — Hand off to the re-verifiers

For each row with Disposition: refresh or release-block, draft a Focused Task brief for the named re-verifier per spawn-team.md Step 4. The brief includes:

• The file path.
• The current last-verified date and computed age.
• The Tier-driven verification effort ("re-verify against ≥3 sources").
• The categorization schema labels they should apply.
• An explicit reminder to update the date only if the content was actually re-verified, not as a bookkeeping refresh.

Pre-release gate

Before any plugin release is tagged, run a scoped sweep over only the files in the release diff:

# Files changed since the last release tag
git diff --name-only <last-release-tag>..HEAD -- 'plugins/<plugin>/knowledge/*.md' 'plugins/<plugin>/skills/*.md'

For each file in the diff:

• If last-verified is > 90 days, block the release until that file is re-verified.
• If a file was added in this release, it must carry a last-verified field set to a date within the last 30 days.

This is the discipline that keeps stale advice out of release notes.

Anti-patterns

• Silent sweep with no remediation queue. A sweep that prints "all files older than 90 days" without disposition + named re-verifier is just noise. The queue is the deliverable.
• Fixing the date without re-verifying. Bumping last-verified: 2026-05-21 on a file you didn't actually research is worse than letting it go stale — it silently launders untrustworthy content.
• Removing the last-verified stamp to avoid the sweep. Don't. Files without stamps fall back to git-age and still get caught.
• Treating decision trees and prose the same way. Decision trees decay faster (a 404 → reimport leaf is wrong the moment the platform returns 409). Trees ≥ 90 days are higher priority than prose ≥ 90 days even at the same age.
• Sweeping scenarios on the 90-day cadence. Scenarios are labeled unverified by design — the user sees the date. Don't queue them for re-verification at 90 days; queue at 365 days for the deprecate question.
• Promoting a Tier 4 emerging pattern to Tier 1 because it "feels stable now." Tier 4 → Tier 1 requires re-verification against ≥3 sources, same as any new Tier 1 entry.
• Auto-deprecating Tier 5 files. Tier 5 sometimes intentionally stays as a cautionary record. Always confirm with the maintainer before deletion.

Output

After running the sweep, produce a brief report + the queue file, then emit the Structured Output Protocol JSON block per structured-output.md:

---RESULT_START---
{
  "status": "complete",
  "summary": "swept N files across M plugins; X flagged for refresh, Y release-blocked, Z propose-removal",
  "deliverables": [
    ".ravenclaude/runs/<sweep-id>/staleness-queue.md",
    ".ravenclaude/runs/<sweep-id>/release-blockers.md"
  ],
  "handoff_recommendation": {
    "to_specialist": "deep-researcher",
    "reason": "re-verify N Tier-1 knowledge files",
    "context_summary": "see staleness-queue.md rows tagged Tier 1"
  },
  "confidence": 0.95,
  "risks_or_open_questions": ["..."],
  "next_actions": ["dispatch re-verifiers per queue routing", "schedule next sweep for <date>"]
}
---RESULT_END---

See also

• researcher.md — the meta-skill this sweep operationalizes. Tier 1-5 schema lives there.
• ../../../docs/best-practices/decision-trees-in-knowledge-files.md — defines the 90/180/365 thresholds and the Last verified: field format.
• plugin-release-checklist.md — wires the pre-release gate into the release process.
• spawn-team.md — how the Team Lead routes the re-verification work after the queue lands.