/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 phase transition (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
• 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"). Added v0.90.0. 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, so a canvas can be numerically consistent everywhere while the sentence explaining the number contradicts it. Flag when a rationale block names a confidence value that no longer matches `.claude/diamonds/active.yml`. **Prose that encodes state is state, and it is otherwise unvalidated.** (Roadmap dogfood 2026-08-02: the field said 0.10, the narrative beside it still said 0.25, and the numeric check passed.)

5. **Check evidence type consistency**:

• Every canvas file with `evidence_type:` should have it set to one of the shipped schema enum values (`schemas/canvas/_common.schema.json#$defs/evidence_type` — Gilad's evidence ladder): `speculation`, `anecdotal`, `data-supported`, `test-validated`, `launch-validated`
• Flag unknown evidence types (note: `_meta` blocks in the field carry structural markers like `schema` / `assessment` / `not-yet-populated` — flag these only when they appear OUTSIDE `_meta`; inside `_meta` they describe the file, not an evidence claim)
• Flag evidence graded `anecdotal` or better whose only sources are mocked personas / `internal_simulated` (honesty check — simulated evidence sits at `speculation` on the ladder regardless of how vivid it reads)
• Every `source_class:` value must be one of the values in the SHIPPED SCHEMA

enum — read `${CLAUDE_PLUGIN_ROOT}/schemas/canvas/_common.schema.json#$defs/source_class` and compare against that, exactly as the `evidence_type` rule above already does. **Do NOT hardcode the list here.** Until v0.90.0 this step named five values while the schema had six; `pointer` is valid, `check_source_independence.py` handles it correctly, and a dogfood canvas used it 61 times. Following the prose produced 61 phantom violations — the documented-rule-diverges-from-enforcement class, in a step whose own sibling rule says to read the schema.

• Flag `internal_stakeholder` evidence with confidence > 0.5 that has `validated: false` or no `validated` field — stakeholder beliefs should not carry high confide