canvas-health

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:
2. Read .claude/diamonds/active.yml for product_type and project_type
3. Read ${CLAUDE_PLUGIN_ROOT}/engine/canvas-guidance.yml for required/recommended/optional files per project type

1. Check file presence:
2. For each required canvas file: does it exist? Is it non-empty (>50 bytes)?
3. For each recommended canvas file: does it exist? Flag as gap if missing.
4. Report: N/M required files present, K recommended files missing

1. Check _meta blocks:
2. For each existing canvas file, check for _meta: block
3. Flag missing _meta blocks
4. Flag last_validated older than 30 days (staleness warning)
5. Flag version field missing or at 0

1. Check confidence consistency:
2. Gather all confidence: values across canvas files
3. Flag confidence > 0.5 with evidence_type: speculation or evidence_type: assumption
4. Flag confidence > 0.7 with fewer than 2 evidence sources
5. Flag confidence values that haven't changed across git history (anchored confidence anti-pattern)
6. Cross-check against .claude/diamonds/active.yml confidence

1. Check evidence type consistency:
2. Every canvas file with evidence_type: should have it set to one of: interview, survey, analytics, experiment, speculation, assumption, mocked_persona
3. Flag unknown evidence types
4. Flag evidence_type: interview when only mocked personas were used (honesty check)
5. Every source_class: value should be one of: external_human, external_data, internal_stakeholder, internal_desk, internal_simulated — flag unknown values
6. Flag internal_stakeholder evidence with confidence > 0.5 that has validated: false or no validated field — stakeholder beliefs should not carry high confidence without external validation (Brown: organizational mythology)
7. Flag L2 opportunity canvas entries where ALL evidence is internal_stakeholder or internal_desk — no external human voice heard (Spool: secondhand research insufficient)

1. Check for orphaned references:
2. Canvas files that reference other canvas files (e.g., jobs-to-be-done.yml referencing opportunities.yml) -- verify the referenced file exists
3. Diamond references to canvas files -- verify they exist

1. Check evidence freshness (evidence decay):
2. Scan all provenance blocks across canvas files for validated_at or captured_at timestamps
3. Compare against staleness thresholds from ${CLAUDE_PLUGIN_ROOT}/engine/evidence-decay.md:
4. User needs/interviews: 90 days
5. Competitive intelligence: 90 days
6. Strategic assumptions: 180 days
7. Technical feasibility: 120 days
8. DORA/delivery metrics: 30 days
9. Flag evidence past threshold as warning; past 3x threshold as critical
10. Suggest refresh actions: "Evidence in [file] is [N] days old. Run /mycelium:user-interview or /mycelium:log-evidence to refresh."
11. Note: corrections and patterns do NOT decay — process learnings are timeless

7b. Check metric snapshot freshness (v0.14):

• If .claude/jit-tooling/active-metrics.yml exists, for each status: active source:
• Find the newest snapshot in .claude/evals/metrics/<source>/.
• If >7 days old: warning ("[source] snapshot is [N] days old — run /mycelium:metrics-pull to refresh").
• If >30 days old: critical (evidence this stale is worse than no metric reference — anchors old state).
• If missing entirely: info-level ("No snapshots yet for [source]. Run /mycelium:metrics-pull.").
• Also check per-adapter freshness: for each adapter file in ${CLAUDE_PLUGIN_ROOT}/jit-tooling/metrics-adapters/, if last_known_working is >180 days old, flag as warning suggesting regeneration via metrics-adapters/GENERATING.md.
• Source: v0.14 metrics harvesting. Metric evidence has a faster staleness curve than interview evidence because the underlying data changes continuously.

1. Check cross-reference integrity (leaf lifecycle):
2. Every GIST idea with source_leaf_id → verify that leaf exists in opportunities.yml (and not in archived-solutions.yml without the GIST being shelved)
3. Every service entry with gist_id → verify that GIST idea exists
4. Every threat model entry with solution_id → verify that solution exists
5. Every go-to-market feedback_loop entry with source_leaf_id → verify leaf exists
6. Flag broken references as warnings ("Zombie Solution" anti-pattern)

8b. Check scenario health (Hoskins):

• If .claude/canvas/scenarios.yml exists:
• Every scenario must have all four Hoskins elements populated (persona, means, motive, simulation) — flag incomplete scenarios
• Every scenario must have lifecycle.born_at set — flag if missing (orphan scenario with no origin)
• Every scenario with confidence > 0.5 must have evidence sources — flag unsupported confidence
• Every scenario referenced in lifecycle.designed_against[] → verify the solution exists in opportunities.yml or gist.yml
• Every scenario referenced in lifecycle.tested_against[] → verify test date is not in the future
• Flag scenarios with status: draft older than 30 days (stale draft — either promote or discard)
• If .claude/canvas/scenarios.yml does NOT exist but project_type requires it (per ${CLAUDE_PLUGIN_ROOT}/engine/canvas-guidance.yml): flag as warning

8c. Human-task reconciliation (added v0.31.3, closes the evidence/status/consent decoupling drift — corrections.md 2026-05-28):

The failure this catches: a fact about a human-task lives in 2+ places (the task status, the evidence file it produced, the contributor's consent registry) and only the salient one gets updated, so the canvas silently drifts from reality. Three sub-checks over .claude/canvas/human-tasks.yml#pending_tasks:

• (a) Status-vs-activity staleness: for each task whose status is non-terminal (NOT completed/abandoned/stalled), compute the latest activity date across updated_at, touch_log[].date, and partial_findings[].date. If the latest is >21 days ago (or no activity date at all), flag: "ht-XXX untouched [N]d while still [status] — decide: mark stalled, mark abandoned, or nudge the contact. Abandonment is a non-event; nothing else will surface this." (The session-start hook flags this at 14d for awareness; canvas-health is the deeper 21d decision prompt.)
• (b) Evidence-exists-but-task-open: for each non-terminal task, check whether it has already produced evidence — i.e. it has a populated partial_findings block, OR its canvas_refs resolve to real evidence entries in purpose.yml/user-needs.yml dated at/after the task's activity. If evidence exists but the task is still open, flag: "ht-XXX has captured evidence (partial_findings / linked purpose.yml entry) but status is [status] — close it (completed) or record why it stays open. Logging evidence and closing the source task are separate steps; this catches the gap." Recommend /mycelium:log-evidence should be closing the task going forward.
• (c) Consent-registry sync (best-effort; cross-source): if an attribution registry is available ($MYCELIUM_ATTRIBUTION_REGISTRY or a private companion repo's .claude/memory/attribution-registry.yml), compare each contributor's consent value there a