knowledge-health

name

knowledge-health

description

Surface knowledge-file staleness across all plugins as a Structured Output block. Wraps the `knowledge-health.py` script — sweeps `plugins/*/knowledge/**.md`, groups files by bucket (stale / due_soon / untracked / fresh), and returns a remediation queue. Used by the release checklist and the `ravenclaude doctor` health check. Read this skill before answering "is our knowledge layer current?", "which knowledge files are stale?", or before tagging a marketplace release.

Skill: knowledge-health

This skill is the read-side surface for knowledge freshness. The knowledge-file-staleness-sweep skill does the deep authoring work (tier classification, named re-verifiers, manual sweep narrative); this one is the deterministic, scriptable counterpart that powers automation: the release checklist step, the ravenclaude doctor command, and any future dashboard card.

When to invoke

• Release checklist — Step 1.5: run before tagging a marketplace release so a stale knowledge file in the diff is caught at gate-time, not a week after consumers have updated.
• ravenclaude doctor — one of the health checks; surfaces stale counts in the doctor's report.
• Ad-hoc — when the user asks "what's stale?", "which knowledge files need re-verification?", or "is the knowledge layer current?"

How to invoke

# Human-readable
python3 plugins/ravenclaude-core/scripts/knowledge-health.py

# JSON for automation / dashboard
python3 plugins/ravenclaude-core/scripts/knowledge-health.py --json

# Custom threshold (default 90 days)
python3 plugins/ravenclaude-core/scripts/knowledge-health.py --threshold-days 180

What the script reads

plugins/*/knowledge/**/*.md — every knowledge file across every plugin. It scans the first ~30 lines for a date marker in any of these forms:

• Last reviewed: 2026-05-21
• Last verified: 2026-05-21
• last-verified: 2026-05-21
• last_verified: 2026-05-21
• retrieved: 2026-05-21

Case-insensitive on the key; ISO-8601 on the value. A file with no recognizable marker lands in the untracked bucket — these are gaps, not warnings.

Buckets

Bucket	Meaning
stale	Last verified > threshold-days ago. Re-verify.
due_soon	Last verified within 30 days of the threshold. Schedule a sweep.
untracked	No date marker. Add one — these files escape the regular sweep.
fresh	Last verified within (threshold - 30) days. No action.

Pairing with knowledge-file-staleness-sweep

The two skills are deliberately separate. knowledge-file-staleness-sweep is the authoring skill: it's where the Researcher writes the remediation queue with named re-verifiers and Tier 1-5 effort classifications. knowledge-health is the detection skill: it gives you the inventory and the dates, deterministically, for downstream automation. Use this skill to find the work, the staleness-sweep skill to plan it.

Output contract (Structured Output Protocol)

When invoked from a multi-agent dispatch, the skill's output ends with a structured block summarizing the report:

---RESULT_START---
{
  "status": "complete",
  "summary": "Knowledge sweep — N stale, N due_soon, N untracked, N fresh.",
  "deliverables": ["staleness inventory by file"],
  "next_actions": ["re-verify stale files (named in the JSON)", "add Last reviewed date to untracked files"],
  "confidence": 1.0
}
---RESULT_END---

See also

• scripts/knowledge-health.py — the engine.
• knowledge-file-staleness-sweep/SKILL.md — the authoring counterpart.
• docs/best-practices/knowledge-categorization-schema.md — the Researcher's Tier 1-5 effort taxonomy.
• checklists/release-checklist.md — where this skill is wired into the release flow.