haabe/mycelium/diamond-progress

Diamond Progress Skill

Record a diamond's decisions, each through the theory gates it needs. Where a diamond is, is read from its decisions ("target set", "committed to build", "released", "closed"; discovery until commit_to_build, delivery after; DL-1368, DL-1372). At close, runs an executable checklist that GATES it.

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.

Preflight: Read-before-Recommend (gate-narration discipline)

Hard rule (per the operating contract's Communication Rules, anti-pattern #7 graduation v0.39.16). Every gate-status narration, blocker statement, hold claim, theory-gate verdict, or transition-blocked finding this skill emits MUST cite the canvas file + field path of the source evidence. Adjacent-surface inference (different opportunity, different ht, different topic) MUST be tagged as inference, not asserted as gate state. Companion to the Read-before-Write rule above: that one protects what gets WRITTEN to canvas; this one protects what gets CLAIMED about canvas state in the skill's narration.

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 -o "<prefix>-[0-9][0-9]*" .claude/canvas/<file>.yml | sort -u -t- -k2 -n | tail -3

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, matching the zero-padding already used in that file. The sort is NUMERIC (-t- -k2 -n) rather than lexical, and that is not pedantry: a plain sort -u orders ht-1 after ht-080, so on a canvas with inconsistent padding it reports the wrong maximum and the next ID collides. Verified on the dogfood repo 2026-08-13, where lexical sort returned ht-1 as the highest human-task ID against an actual ht-080. grep -o is also deliberate: it matches IDs wherever they appear, including cross-references and prose, so an ID that was promised somewhere but not yet defined is not handed out twice. validate_canvas.py has a per-file duplicate-ID check (it reports duplicate id '<id>') 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; that happened on 2026-05-15, when a duplicate ID was created in landscape.yml.

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_PLUGIN_ROOT}/engine/agent-operating-contract.md Canvas writes — Read before Write for the canonical rule.

Workflow

1. Identify the decision: where the diamond is (scale_locks.position, e.g. "target set

(discovery)") and the decision to record next at [scale]: set_target; start_experiment and commit_to_build, recorded together to commit to build; release; close. An L0 records state_purpose, then review. To iterate, append (DL-1373, step 8).

1b. Cognitive Forcing (before gate evaluation):

Before running gates, ask the human for their unprimed judgment:

> "Before I check the gates — do you think we're ready to record [decision]? What's your gut say?"

Wait for the response. Record it. Then run the gates. After presenting results, compare:

> "You said [X]. The gates say [Y]. Where do we differ?"

The turn that asks this question ends with a `Next:` line, like every turn in which a skill ran (contract rule 12). The question is the next action: Next: say whether you think we're ready to record [decision] (per: diamond-progress step 1b). Without that line the Stop hook hooks/next-action-check.sh blocks the turn, and Claude Code shows the block to the person as "Stop hook error" under a question they have not answered yet. The same pause in diamond-assess step 0 caused 3 of that hook's first 5 blocks on the dogfood project.

The human's instinct often catches risks the gates miss. If the human says "not ready" but gates pass, investigate — the human may be sensing something the evidence hasn't captured yet.

Source: Buçinca, Malaya & Gajos (Cognitive Forcing Functions, Harvard CHI/CSCW 2021). Applied after Hoskins transcript analysis — Drew's product judgment consistently outperformed the agent's gate-based assessment.

Autonomous mode (per ${CLAUDE_PLUGIN_ROOT}/engine/autonomous-mode.md): rung (b) — record the declared persona's gut call BEFORE running gates, tag internal_simulated, ledger it. The compare-after step still runs.

1. Run all required theory gates (per ${CLAUDE_PLUGIN_ROOT}/engine/theory-gates.md Decision Matrix, one column per decision; a move needs the gates of every decision it records):

• For each gate:

a. State the gate name and source theory. b. Surface the suggested skill: "Run /skill-name to satisfy this gate." c. Evaluate pass criteria against available evidence. d. Record Pass / Fail / Insufficient Evidence in `theory_gates_status` on the diamond, on every outcome, not only when it progresses (pass, fail, or pending with what is missing in progression_blockers). Added v0.278.0: E2E rung L4-define ran this skill on an L4, ruled needs-evidence, and wrote no gate result, since the only instruction to record gates sat under the phase move. The next session read "no gate results are recorded" as a blocker, the closing path read the empty field as every gate passing, and the L4 sat in discover. A gate evaluated and not written is a gate the next assessment re-derives from nothing. e. If Fail: document what is missing, recommend the skill to run, and do NOT proceed.

CRITICAL — Perspective conflict check (do this BEFORE evaluating any other gate): Before checking any gate status, read .claude/canvas/opportunities.yml and inspect the Four Risks risk LEVELS for the active solution. Do NOT rely on theory_gates_status.four_risks in active.yml — that only records whether risks are documented, not whether they conflict. You must read the actual value.level, usability.level, feasibility.level, viability.level values.

If TWO OR MORE risk dimensions are rated HIGH, or if perspectives directly contradict each other (e.g., value says "build it" but usability/feasibility say "don't"), this is a perspective conflict — not a simple gate failure. STOP evaluating other gates and jump to step 2b immediately. This takes priority over all other gate checks.

2b. Resolve perspective conflict (if detected in step 2): Do NOT continue to steps 3-6. A perspective conflict must be resolved before any other gate evaluation matters. Follow this procedure:

1. Name the conflict explicitly in the decision log: "Perspective conflict: [type]" — use the vocabulary from ${CLAUDE_PLUGIN_ROOT}/engine/perspective-resolution.md (value-vs-feasibility, usability-vs-feasibility, value-vs-viability, usability-vs-viability, three-way).
2. Classify the conflict type per the resolution framework.
3. State each perspective's position:

• Product perspective: what does the value evidence say?
• Design perspective: what does the usability evidence say?
• Engineering perspective: what does the feasibility evidence say?

1. Apply the resolution methods in order of preference:

• Constraint-based: Can all three perspectives be satisfied within acceptable thresholds?
• Phased: Can we deliver in stages? (Phase 1 = MVP addressing highest risk, Phase 2 = polish)
• Evidence-based: Can we test the disputed dimension? (Run /mycelium:assumption-test on the riskiest assumption)
• Scope reduction: Can we remove features until all perspectives align?

1. Log the resolution in .claude/harness/decision-log.md with: the conflict type, each perspective's position, the resolution method chosen, and why.
2. Block progression: Report "Progression blocked: perspective conflict ([type]). Recommended resolution: [method]."
3. Do NOT proceed to step 3 or beyond. The conflict must be resolved first.

The perspective resolution framework (${CLAUDE_PLUGIN_ROOT}/engine/perspective-resolution.md) is the authoritative reference. The anti-pattern to avoid is Perspective Suppression — resolving a conflict by ignoring one perspective.

2c. Build-to-learn awareness NUDGE (at commit_to_build only): When the diamond commits to build, surface this prompt to the human: > "Are you building to learn or building to earn right now? Discovery work (prototypes, spikes, experiments) can use lighter gates. Delivery work (shipping to users) must meet full DoD." This is awareness only — it does not change gate requirements or routing. The human's answer is informational context, not a gate input. Source: Cagan (SVPG), Patton (build to learn vs build to earn). Added as NUDGE per risk analysis — conceptual awareness, not process gate.

2c-2. An L4's `commit_to_build` says where the work may write (v0.324.0, enforced by hooks/scope-gate.sh). In the same edit that records commit_to_build on a delivery cycle (an L4), write in_scope_paths on that cycle: the folders, files or globs the work will touch, project-relative.

``yaml in_scope_paths: [app/billing/, tests/billing/**] # the agent is held to these in_scope_paths: [] # no hold for this one, said on purpose ``

Propose the list from the plan; the person decides it. Say which folders you propose and why, in one line, before the edit. The edit is put to the person by the gate (an ask), because where the agent may write is theirs to say; where nobody can be asked it is refused, and the person makes the change themselves. An empty list is a real answer ("no hold for this one") and is asked about the same way. Do not write an empty list to get past the question: propose the folders, and let the person say "no hold" if that is what they want.

A commitment to build with nothing said is refused. The gate reads the edit, and an L4 that would end up committed with no in_scope_paths at all does not land.