/canvas-health

name: canvas-health
description: "Lint canvas files for staleness, missing fields, inconsistent evidence types, and orphaned references. Run periodically or before major transitions."
metadata:
  instruction_budget: "87"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

Canvas Health Check

Audit the canvas knowledge base for quality, consistency, and completeness. The canvas is Mycelium's source of truth -- its quality directly determines agent output quality (Raschka: "context quality = model quality").

When to Use

• Before any diamond records a decision (called automatically by `/mycelium:diamond-assess`)
• After a period of inactivity (>7 days since last canvas update)
• When agent output quality seems to degrade
• After onboarding a new team member (ensures canvas is self-explanatory)
• Proactively: run periodically to catch silent drift

Workflow

1. **Load project configuration**:

• Read `.claude/diamonds/active.yml` for `product_type` and `project_type`
• Read `${CLAUDE_PLUGIN_ROOT}/engine/canvas-guidance.yml` for required/recommended/optional files per project type

2. **Check file presence**:

• For each **required** canvas file: does it exist? Is it non-empty (>50 bytes)?
• For each **recommended** canvas file: does it exist? Flag as gap if missing.
• Report: `N/M required files present, K recommended files missing`

3. **Check `_meta` blocks**:

• For each existing canvas file, check for `_meta:` block
• Flag missing `_meta` blocks
• **SKIP a file whose schema declares no `_meta` and names its own freshness field**,

and judge that field by its own rule instead. Today that is `doctrine.yml`: `schemas/canvas/doctrine.schema.json` declares `schema_version`, `last_reviewed`, `doctrine` and `climate`, and no `_meta`. Its `last_reviewed` is event-based ("a retrospective is DUE when a diamond has entered completed_diamonds with a completed_at later than this date"), not a calendar, and `check_doctrine_due.py` reads exactly that. Asking that file for `_meta` asks for a field the schema left out on purpose, so the warning cannot be cleared by a correct file. Before flagging a missing `_meta`, read the file's schema: if it has no `_meta` property, do not flag it. Added v0.333.0, found on the dogfood repo 2026-11-06.

• Flag `last_validated` past **the horizon for that file's category**, per the

"Which threshold applies to which canvas file" table in `${CLAUDE_PLUGIN_ROOT}/engine/evidence-decay.md` (strategic 180d, technical feasibility 120d, user-needs/competitive/market 90d, delivery metrics 30d, regulatory 365d; unlisted files fall back to 90d).

• **SKIP any file whose `_meta.applicability` marks it inapplicable** (a value

starting `n/a`, or naming a product type this project is not, or saying "NOT actively used", **or declaring the file an append-only log with no quality bar to validate against**). Added v0.90.0; the append-only form added v0.234.0. **WHY THE APPEND-ONLY FORM WAS MISSING FOR SO LONG, AND WHY IT IS THE SAME RULE.** Step 9b below already exempts append-only logs from its length budget, on the reasoning that for such a file the line count IS the value and pages-as-shape is a category error. **The identical reasoning applies to a validation DATE on a file with nothing to validate**, and this step never got the rule — so a dogfood `archived-solutions.yml`, a registry of discarded leaves whose own `_meta` said "no quality bar to validate against", was flagged as stale on every pass. Its author had written the exemption in prose AND appended "flagged as missing `_meta` in recurring canvas-health passes" to the marker, and it went on being flagged: **a finding the author has pre-emptively annotated as noise is a check being routed around**, which is the condition this very step warns trains a reader to skip it (2026-09-21). Same one-rule-two-places shape as the horizon exemption written into 8c(b) and not carried to 8c(a). Two dogfood canvases held ZERO evidence — every metric field null, the only non-null leaves `False` schema defaults — and already said so in their own `_meta`. They decayed on a 30-day horizon anyway, and the only way to silence that warning would have been to date a validation of a file nobody uses: the manufactured-validation move v0.89.0 removed `last_updated` to prevent. Precedents for the marker: `dora-metrics.yml#sre` (`n/a-until-production`) and `dependency-pins.yml` (`scope: local`). **This replaced a flat 30-day rule in v0.89.0.** That rule was the only staleness number in this skill grounded in nothing — step 7 below has always used the decay table — and on the dogfood repo it flagged 20 of 25 canvases, including a strategic file validated 46 days earlier against a 180-day horizon. A check that fires on 80% of a corpus trains its reader to skip it.

• Flag `version` field missing or at 0

4. **Check confidence consistency**:

• Gather all `confidence:` values across canvas files
• Flag confidence > 0.5 with `evidence_type: speculation` or `evidence_type: assumption`
• Flag confidence > 0.7 with fewer than 2 evidence sources
• Flag confidence values that haven't changed across git history (anchored confidence anti-pattern)
• Cross-check against `.claude/diamonds/active.yml` confidence
• **Cross-check the confidence RATIONALE prose too, not only the `confidence:` field.** Projects record *why* a value moved in narrative fields (`confidence_effect`, `confidence_effect_v2`, or any prose block that names a number). Nothing reads those,