health

name	health
description	Validate knowledge base quality, check freshness, analyze coverage gaps, and generate health reports

Validates knowledge base quality across three tiers and three quality dimensions. Runs deterministic checks, LLM-assisted assessments, and surfaces items requiring human judgment. Produces actionable health reports with severity-ranked issues.

1. Tier 1 -- Deterministic (Python) -- Fast, automated checks run by check_knowledge_base.py. 18 per-file validators (frontmatter, sections, size bounds, readability, sources, freshness, and more) plus 6 cross-file validators (manifest sync, curation plan sync, proposal integrity, link graph, duplicate detection, naming conventions). Auto-fix available for common issues. No LLM required. CI-friendly.
2. Tier 2 -- LLM-Assisted (Claude) -- Claude evaluates items flagged by Tier 1 or entries with stale last_validated dates. Assesses source drift, depth label accuracy, "Why This Matters" quality, and "In Practice" concreteness.
3. Tier 3 -- Human Judgment -- Surfaces decisions that require human input: relevance questions, scope decisions, pending proposals, and conflict resolution between knowledge base claims and updated sources.

<quick_start> Run Tier 1 checks (default): /dewey:health or /dewey:health check Run full audit (Tier 1 + 2): /dewey:health audit Surface human decisions: /dewey:health review Check coverage gaps: /dewey:health coverage Check staleness: /dewey:health freshness </quick_start>

1. **Relevance** -- Is this content needed by the role? Does the relevance statement accurately describe who benefits and when? 2. **Accuracy / Freshness** -- Are claims current and traceable to sources? Has the content been validated recently? 3. **Structural Fitness** -- Does the content follow the knowledge base spec? Correct depth, proper sections, valid frontmatter, companion files present? - **Fast feedback first** -- Tier 1 runs in seconds, catches structural issues immediately - **LLM where it matters** -- Tier 2 only evaluates what Tier 1 flags or what's overdue - **Humans decide scope** -- Tier 3 never auto-resolves relevance or pruning decisions - **Severity-ranked output** -- Every issue carries a severity (fail, warn) so users can prioritize - `$ARGUMENTS` -- Arguments passed to this skill (workflow name and parameters) - `${CLAUDE_PLUGIN_ROOT}` -- Root directory of the Dewey plugin Validating knowledge base quality.

Before routing, check if a curation plan exists:

1. No knowledge base initialized (no AGENTS.md or knowledge base directory) -- Suggest /dewey:curate first. Do not proceed.
2. Knowledge base exists but no .dewey/curation-plan.md -- Pause and build a plan:
   • Read AGENTS.md to understand the role and domain areas
   • Read the knowledge base directory structure to see what topics already exist
   • Propose 2-4 starter topics per domain area based on context
   • Ask the user to confirm or adjust
   • Write .dewey/curation-plan.md with the confirmed topics (use the format from the curate-plan workflow)
   • Then resume the original command
3. Plan exists -- Proceed to routing normally

Default behavior: Run Tier 1 deterministic checks only (fast, CI-friendly).

Available actions:

• check -- Tier 1 deterministic validation (default)
• audit -- Tier 1 + Tier 2 LLM-assisted assessment
• review -- Tier 1 + Tier 2 + surface Tier 3 decision queue
• coverage -- Gap analysis against AGENTS.md responsibilities
• freshness -- Staleness report sorted by urgency

Parse the action from $ARGUMENTS. If no arguments provided, run check (Tier 1 only).

Parse `$ARGUMENTS`:

• Starts with check or no arguments provided -> Route to workflows/health-check.md
• Starts with audit -> Route to workflows/health-audit.md
• Starts with review -> Route to workflows/health-review.md
• Starts with coverage -> Route to workflows/health-coverage.md
• Starts with freshness -> Route to workflows/health-freshness.md

<workflows_index> All workflows in workflows/:

Workflow	Purpose
health-check.md	Tier 1 deterministic validation -- fast, CI-friendly
health-audit.md	Tier 1 + Tier 2 LLM-assisted quality assessment
health-review.md	Full assessment + Tier 3 human decision queue
health-coverage.md	Gap analysis comparing AGENTS.md responsibilities to knowledge base contents
health-freshness.md	Staleness report grouped by urgency
</workflows_index>

<references_index> All references in references/:

Reference	Content
validation-rules.md	Complete list of Tier 1 checks with fields, thresholds, and severities
quality-dimensions.md	Three quality dimensions: what each means, how measured, which checks apply
design-principles.md	Twelve design principles grounded in agent context research and cognitive science
</references_index>

<scripts_integration> Located in scripts/:

check_knowledge_base.py -- Health check runner

• Discovers all .md files under the knowledge base directory (excluding _proposals/ and index.md)
• Runs all Tier 1 deterministic validators on each file
• Returns structured JSON report with issues and summary
• Summary includes total_files, fail_count, warn_count, pass_count

Usage:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/health/scripts/check_knowledge_base.py --knowledge-base-root <knowledge_base_root>

validators.py -- Tier 1 deterministic validators

Structural checks:

• check_frontmatter -- Required fields: sources, last_validated, relevance, depth
• check_section_ordering -- "In Practice" before "Key Guidance" in working-depth files
• check_section_completeness -- Required sections present for each depth level
• check_heading_hierarchy -- No skipped heading levels (e.g., h1 to h3)
• check_cross_references -- Internal markdown links resolve to existing files
• check_size_bounds -- Line counts within range for each depth level
• check_readability -- Flesch-Kincaid grade level within bounds per depth (overview 8-14, working 10-16)

Coverage and sync checks:

• check_coverage -- Every area has overview.md; every topic has .ref.md companion
• check_index_sync -- index.md references all topic files on disk; warns on stale index
• check_inventory_regression -- Detects topics that disappeared between runs

Source and link checks:

• check_source_urls -- Source URLs are well-formed (http/https)
• check_freshness -- last_validated within threshold (default 90 days)
• check_go_deeper_links -- Working files link to their reference companions
• check_ref_see_also -- Reference files include a "See Also" section linking back
• check_placeholder_comments -- Flags TODO/FIXME/placeholder markers left in content
• check_source_diversity -- Warns when all sources come from a single domain
• check_citation_grounding -- Working files have inline citations near key claims
• check_source_accessibility -- Source URLs return HTTP 200 (opt-in via --check-links)

Every validator returns a list of issue dicts: {"file": str, "message": str, "severity": "fail" | "warn"}

Tier 2 pre-screening only:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/health/scripts/check_knowledge_base.py --knowledge-base-root <knowledge_base_root> --tier2

Combined Tier 1 + Tier 2:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/health/scripts/check_knowledge_base.py --knowledge-base-root <knowledge_base_root> --both

Returns {"tier1": {...}, "tier2": {...}} with both Tier 1 issues/summary and Tier 2 queue/summary.

tier2_triggers.py -- Tier 2 deterministic pre-screener

Content quality triggers:

• trigger_source_drift -- Flags files with stale or missing last_validated
• trigger_depth_accuracy -- Flags files where word count or prose ratio mismatches depth
• trigger_source_primacy -- Flags working files with low inline citation density
• trigger_why_quality -- Flags working files with missing or thin "Why This Matters"
• trigger_concrete_examples -- Flags working files with missing or abstract "In Practice"
• trigger_citation_quality -- Flags files with weak or missing inline citations

Source quality triggers:

• trigger_source_authority -- Flags files whose sources lack authoritative domains
• trigger_provenance_completeness -- Flags files with incomplete provenance metadata
• trigger_recommendation_coverage -- Flags files lacking actionable recommendations

Every trigger returns: {"file": str, "trigger": str, "reason": str, "context": dict}

history.py -- Health score history tracking

• record_snapshot(knowledge_base_root, tier1_summary, tier2_summary) -- Appends timestamped snapshot to .dewey/history/health-log.jsonl
• read_history(knowledge_base_root, limit=10) -- Returns the last N snapshots in chronological order
• Auto-called by check_knowledge_base.py after each run

utilization.py -- Topic reference tracking

• record_reference(knowledge_base_root, file_path, context="user") -- Appends to .dewey/utilization/log.jsonl
• read_utilization(knowledge_base_root) -- Returns per-file stats: {file: {count, first_referenced, last_referenced}}

log_access.py -- Hook-driven utilization logging

• log_if_knowledge_file(knowledge_base_root, file_path) -- Logs access if file is a .md under the knowledge directory
• Filters out _proposals, non-.md files, and files outside the knowledge directory
• Called by hook_log_access.py (Claude Code PostToolUse hook entry point)

hook_log_access.py -- CLI entry point for Claude Code PostToolUse hook

• Reads tool input JSON from stdin, extracts file_path
• Calls log_if_knowledge_file to conditionally log the access
• Exit code always 0 (hook failures never block the agent)

cross_validators.py -- Cross-file consistency validators

• check_manifest_sync -- AGENTS.md topic list matches files on disk
• check_curation_plan_sync -- Curation plan checkmarks match actual file presence
• check_proposal_integrity -- Proposals have required frontmatter and valid target areas
• check_link_graph -- Internal links between knowledge files all resolve
• check_duplicate_content -- Detects duplicate paragraphs and high Jaccard similarity across files (skips companion pairs)
• check_naming_conventions -- Validates directory and file names against slug conventions

Every cross-validator returns: {"file": str, "message": str, "severity": "fail" | "warn"}

auto_fix.py -- Automated fixes for common issues

• fix_missing_sections -- Adds missing required sections with placeholder content
• fix_missing_cross_links -- Adds "Go Deeper" / "See Also" links between companion files
• fix_curation_plan_checkmarks -- Updates curation plan checkmarks to match files on disk </scripts_integration>

<success_criteria> Health assessment is successful when:

• Every issue is reported with a severity level (fail or warn)
• Issues include the affected file path and a clear message
• Summary statistics are provided (total files, fails, warnings, passes)
• Recommendations are actionable (fix this specific field, re-validate this entry)
• Tier 2 assessments include reasoning, not just pass/fail
• Tier 3 items are framed as questions for human decision, not directives </success_criteria>