Canvas Update

Canvas Update

Preflight: Read target canvas file(s) before any Write/Edit

Hard rule. Before issuing Write or Edit against any .claude/canvas/*.yml, use the Read tool on that file in this session. Claude Code's Read-before-Write check requires the Read tool specifically — cat/head/grep via Bash do NOT satisfy it.

Edit vs Write — different cost profiles (verified 2026-05-14):

• Edit (exact-string replacement): Read with limit: 1 satisfies the check at ~50 tokens. State-tracking is per-file, not per-byte — subsequent Edit calls work anywhere in the file. Use this for partial updates against large canvas files (e.g., purpose.yml at 800+ lines).
• Write (full replacement): do a full Read first. Write obliterates the file; you should see what you're about to replace. The limit:1 shortcut is not appropriate here.

ID-bearing entries — scan the ID space before assigning (added 2026-05-15, v0.23.19): When adding a new component, opportunity, solution, or any other ID-bearing entry to a canvas file, run a Bash grep first to confirm the next ID in your prefix sequence is actually free:

grep "^  - id: <prefix>-" .claude/canvas/<file>.yml | sort -u

Replace <prefix> with the canvas's ID prefix (comp for landscape, opp for opportunities, sol for solutions, ht for human-tasks, etc.). Then pick the next free integer. validate_canvas.py has a duplicate-ID check (lines 230-239) that catches the failure on CI, but a duplicate can persist in the working tree for days if CI isn't run between edit and discovery — see roadmap-repo corrections.md 2026-05-15 "Duplicate canvas ID created in landscape.yml" for the worked example.

Original failure mode: anti-pattern #7 instance #5, 2026-05-09 — agent conflated Bash head with the Read tool, lost ~14k tokens to a Write-fail → remedial-full-Read → re-Write loop. The limit:1 discipline (graduated 2026-05-14, v0.23.18) prevents the second-order cost where the agent correctly follows the rule but full-Reads every time. The ID-scan discipline (graduated 2026-05-15, v0.23.19) prevents the related class where the agent reads enough of the file to satisfy the Edit check but not enough to see existing ID assignments — kin to anti-pattern #8 (Stale State Read).

If this skill writes to multiple canvas files, register each one first (limit:1 for Edit-only paths; full Read for Write paths) AND ID-scan any prefix you intend to assign.

See CLAUDE.md Canvas writes — Read before Write for the canonical rule.

Rules

1. Never update without evidence -- every canvas change must have a source
2. Maintain cross-file consistency -- if you update opportunities.yml, check if north-star.yml or gist.yml need updates too
3. Log the update -- add an entry to .claude/harness/decision-log.md explaining what changed and why

Which Canvas File for Which Information

Workflow

1. Identify which canvas file(s) need updating
2. Read current state
3. Make the update with evidence citation
4. Check cross-file consistency
5. Log in .claude/harness/decision-log.md

Counter-Argument Check (Bias Mitigation)

Before applying the canvas update, draft a one-line counter-argument: "What's the strongest case AGAINST this update — what evidence or perspective would invalidate it?" If you can't articulate one, run /mycelium:devils-advocate before proceeding.

This addresses the bias cluster documented in corrections.md (L5 sycophancy 2026-04-20, eval overfitting 2026-04-30, sharper-framing-isn't-righter 2026-05-03). Common shape: agent prefers what feels right over what evidence supports under competing pressure (be helpful vs. be honest, sharpen framing vs. preserve evidence base). The counter-argument step forces the missing perspective explicit, so the bias surfaces before it lands in canvas.

Especially important when interpolating user-supplied content (already untrusted per ${CLAUDE_PLUGIN_ROOT}/harness/security-trust.md#prompt-injection-defense) AND when increasing a confidence value — both contexts where the agent is most likely to default toward the optimistic read.