Diamond Progress Skill

Progress a diamond through phases with full theory gate validation. At delivery completion, runs an executable checklist that GATES progression.

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 CLAUDE.md 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 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.

Workflow

1. Identify transition: From [current phase] to [next phase] at [scale].

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 move from [current] to [next]? 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 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.

2. Run all required theory gates (per ${CLAUDE_PLUGIN_ROOT}/engine/theory-gates.md transition matrix):

   • 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. 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?
4. 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?
5. Log the resolution in .claude/harness/decision-log.md with: the conflict type, each perspective's position, the resolution method chosen, and why.
6. Block progression: Report "Progression blocked: perspective conflict ([type]). Recommended resolution: [method]."
7. 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 (Define → Develop transitions only): At the point of entering Develop, 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.

3. Calculate confidence:

   • Apply scoring rules from ${CLAUDE_PLUGIN_ROOT}/engine/confidence-thresholds.yml.
   • Look up project_type and dogfood from .claude/diamonds/active.yml.
   • Apply project_type_adaptations from ${CLAUDE_PLUGIN_ROOT}/engine/confidence-thresholds.yml:
     • effective_threshold = base_threshold * threshold_multiplier
     • If dogfood: true: effective_threshold *= dogfood_modifier.additional_threshold_multiplier
     • effective_min_sources = ceil(base_min_sources * min_sources_multiplier)
   • Compare confidence to the effective threshold (not the base).
   • Report both: "Confidence: 0.55. Effective threshold: 0.57 (base 0.85, adapted for solo_product). Needs: one more evidence source to cross."

4. Check human approval requirement:

   • Per ${CLAUDE_PLUGIN_ROOT}/engine/confidence-thresholds.yml, is human approval required/recommended/optional?
   • If required: present assessment and wait for approval.
   • When asking for approval, include the interaction convention explicitly in the prompt — do not leave it implicit. Use this template (or paraphrase faithfully):

     "Reply yes to advance, no to stay. Re-invoking /mycelium:diamond-progress is also treated as approval (shortcut). Type evaluate again to re-run gates from scratch."

   • This makes the implicit-shortcut convention visible. If the user re-invokes /mycelium:diamond-progress while a previous invocation is awaiting approval, that re-invocation IS treated as approval — but only because the convention has been surfaced in the prompt above. Without the prompt-line, the behavior is a footgun (corrections.md 2026-05-06 — /mycelium:diamond-progress re-invocation interpreted as approval).
   • Autonomous mode (per ${CLAUDE_PLUGIN_ROOT}/engine/autonomous-mode.md): where human_approval is required, this is a HARD GATE — rung (c): do not advance, ledger the block, surface it for the next human session. Where it is recommended/optional, autonomous advance is permitted ONLY if every gate passes on evidence that does not depend on internal_simulated entries; ledger + decision-log entry mandatory. The re-invocation-as-approval shortcut does NOT apply in autonomous runs — an agent re-invoking the skill must never count as its own approval.

5. Run bias check: Execute bias-check for the current stage.

6. Run corrections check: Review corrections.md for relevant entries.

6b. Check trio perspective coverage (Torres Product Trio):

• For each gate evaluated in step 2, verify all three perspectives (product/design/engineering) are documented.
• Each perspective must have evidence or an explicit "N/A: [reason]" justification.
• Missing perspectives without justification = GATE FAILED (Perspective Skip anti-pattern).
• See ${CLAUDE_PLUGIN_ROOT}/engine/theory-gates.md §Trio Perspective Requirement for per-scale guidance.
• Note: Perspective CONFLICTS (2+ HIGH risk dimensions) are caught in step 2b, not here. This step checks for missing perspectives, not conflicting ones.

7. If transition is Deliver -> Complete: RUN EXECUTABLE DoD CHECKLIST (see below)

8. Decision:

   • All gates pass + confidence met + approval (if needed) + DoD pass (if delivery) = PROGRESS
   • Any REVIEW item fails = blocked (list specific blockers with suggested skills)
   • Confidence below threshold = NEEDS EVIDENCE (list what would help)

   Write the ruling to the diamond — MANDATORY, on ALL THREE outcomes, added v0.92.0. Immediately after deciding, set these fields on the assessed diamond in .claude/diamonds/active.yml:

   progression_ruling: progressed | blocked | needs-evidence   # one of exactly these
   progression_ruled_at: <YYYY-MM-DD>
   progression_blockers:                # REQUIRED when ruling is blocked or needs-evidence;
     - gate: <which gate or threshold>  # omit entirely when progressed
       reason: <why it did not clear, in your own words>
       unblocked_by: <the skill or evidence that would clear it>
   

   Why this is mandatory rather than nice-to-have. The verdict was previously narrated to the user and written as prose to the decision log, and nowhere else. Nothing downstream could tell a refusal from a narration ABOUT refusal — the only available check was grepping the log for words like "block", "gate" and "insufficient", which any paragraph explaining the framework's philosophy satisfies without a single gate having fired. Discovered 2026-08-05: progression_ruling was read by a consumer and written by no skill, so the rigorous path was dead code and every check silently fell through to the prose grep.

   Write it on a PASS too. A field that only appears on failure cannot distinguish "this diamond was assessed and cleared" from "this diamond was never assessed" — which is the same absent-vs-negative confusion that made confidence required on the diamond schema in this release. The ruling records that a judgement happened; its value records which way it went.

9. If progressing:

   • At Define→Develop with a product-leaf solution chosen: open a cycle record in .claude/canvas/cycle-history.yml with cycle_class: product-leaf and copy the solution's ice_score from opportunities.yml into predicted.ice_score. If the solution has no ICE score, STOP — return "Cannot open product-leaf cycle without ICE. Run /mycelium:ice-score on the chosen solution first." This is the gate that prevents permanent dark cells in calibration. See ${CLAUDE_PLUGIN_ROOT}/engine/cycle-learning.md#cycle-class.
   • Framework-self-development or observation transitions (no OST solution leaf chosen — e.g., L2 strategy adjustment, cohort-log capture, validator-check ship): open the cycle record with cycle_class: meta-dogfood or cycle_class: observation as appropriate. ice_score may be zero with a notes: line stating why. These cycles are excluded from ICE-calibration aggregates by design.
   • Update diamond state in .claude/diamonds/active.yml.
   • At Deliver→Complete: stamp completed_at on the diamond (ISO-8601 — the true ship timestamp; no other diamond field records completion). This times the outcome→discovery loop: /metrics-pull Step 8b (DoD outcome-check) and the session-start overdue nudge both read completed_at to know when a shipped diamond's outcome is due for verification. Without it, the back half of the loop can't fire.
   • Render the updated journey map: Follow ${CLAUDE_PLUGIN_ROOT}/engine/wayfinding.md to show the user where they've moved to. This makes the transition visible — the user sees their position shift on the map.
   • Log transition in .claude/harness/decision-log.md. If threshold was adapted, include: "Threshold adapted from [base] to [effective] because project_type=[type]. Would increase with [action]."
   • Update .claude/memory/product-journal.md.
   • Identify if child diamonds should be spawned. For each child diamond spawned, run /mycelium:define-done before it goes live — pin its outcome definition_of_done and set rolls_up_to naming which parent outcome it serves (contribution-not-summation). A child born without a done-bar inherits the implicit-harshest-bar problem.
   • Capture learnings (see Learning Capture section below)

10. If blocked or needs evidence:

    • Report in plain language: "Can't mark this done yet because [reason]."
    • List each failed item with its suggested skill
    • Do not progress. Stay in current phase.
    • At L0 / L1 / L2 / L5 diamonds, if the Evidence gate is "Insufficient Evidence" and .claude/jit-tooling/active-metrics.yml is configured, suggest /mycelium:metrics-pull as one route to strengthen external signal. If .claude/jit-tooling/active-metrics.yml is missing, suggest /mycelium:metrics-detect first. (v0.14: external_data from snapshots satisfies the Evidence gate's behavioral-data criterion but does NOT replace external_human requirements at L2 Develop->Deliver.)

    Technical-discovery shape detection (sol-007a, v0.39.6): when Evidence/Bias/Feasibility gates are blocking AND the agent observes any of the following technical-shape signals in canvas state, name the dimension explicitly as "technical discovery" in the verdict and recommend /mycelium:assumption-test with read-docs / pull-real-payload framing — NOT /mycelium:user-interview (interviewing a domain user does not validate an unread API contract):

    • Any constraints.* entry with validated: false that names an external API, contract, schema, data model, or third-party integration
    • Develop_intent or develop_summary referencing a specific external API/service version without an evidence source
    • Recent code change touching an external client/SDK while the contract is unread (look for client/SDK imports in src/ adjacent to the active diamond's scope)

    Verdict-line template when triggered: "Blocked — technical discovery incomplete. The [API contract / data model / architecture decision] for [name] is unverified. Feasibility evidence missing: [the specific assumption flagged]. Recommended next: /mycelium:assumption-test against the unread contract — read the current docs, pull a real payload, validate the assumption against observed data before building the dependent component."

    Why this routing-branch (rationale captured 2026-06-03 — roadmap brownfield-iteration eval, sw-tech-discovery dogfood pass 6/7 with decision_log_contains failing): the framework's existing gates correctly BLOCK the bad-progression behavior (5+ of 7 measurable dimensions pass on the failing-first dogfood) — the structural gating is healthy. The gap was purely vocabulary + routing: the verdict didn't NAME the dimension as technical-discovery and recommended /user-interview where read-docs / pull-payload was the correct surface. Sol-007a closes both gaps without adding a new gate, scale, or skill. See opp-007 in mycelium-roadmap canvas.

11. Always communicate in plain language:

    • Use ${CLAUDE_PLUGIN_ROOT}/engine/status-translations.md for all state descriptions
    • Include contextual confidence explanation
    • Suggest specific skills for any gaps

---

Executable Definition of Done (Deliver -> Complete ONLY)

When transitioning from Deliver to Complete, run this checklist. Items marked REVIEW block progression. Items marked PROMPTED are asked but don't block.

Auto-Checked (Machine Verifiable)

Check product_type from .claude/diamonds/active.yml to determine which auto-checks apply.

For software and ai_tool (code components):

Testing (G-V7 REVIEW):

• Check: Do test files exist? (glob for .test., .spec., Tests/, tests/)
• If no tests AND project has source files: GATE FAILED
• Message: "No tests found. Tests must exist before marking delivery complete. Run /mycelium:reflexion to add tests."
• If tests exist: run them and verify they pass

Type Safety (REVIEW for typed languages):

• Check: If tsconfig.json, *.swift, *.cs, go.mod, Cargo.toml detected: run type checker
• If type errors: GATE FAILED

Linting (REVIEW if linter detected):

• Check: If linter config exists (.eslintrc, biome.json, .swiftlint.yml, ruff.toml): run it
• If lint errors: GATE FAILED

For content products (content_course, content_publication, content_media):

Content Quality (REVIEW):

• Check: Are content-metrics.yml#quality_review flags all true? (sme_reviewed, accessibility_checked, fact_checked, style_consistent, learning_objectives_met)
• If any flag is false: GATE FAILED -- "Content quality review incomplete. Set the relevant flags in content-metrics.yml after completing review."
• Fallback: If content-metrics.yml doesn't exist yet, ask: "Has content been reviewed? Create content-metrics.yml and mark quality_review flags."

For ai_tool:

Eval & Safety (REVIEW):

• Check: Are ai-tool-metrics.yml#prompt_quality fields populated (not null)? Specifically: accuracy_score, consistency_score, safety_score.
• If any are null: GATE FAILED -- "Prompt/model must be evaluated. Populate accuracy_score, consistency_score, and safety_score in ai-tool-metrics.yml."
• Check: Is ai-tool-metrics.yml#prompt_quality.last_evaluated set?
• If null: GATE FAILED -- "No evaluation timestamp. Run eval and record the date."

For all product types:

Secrets (G-S1 BLOCK):

• Check: Scan all project files for secret patterns (same as gate.sh)
• If secrets found: GATE FAILED

Delivery-Type Dependent (from ${CLAUDE_PLUGIN_ROOT}/engine/canvas-guidance.yml)

For user_facing work (G-V2, G-V8, G-V9 REVIEW):

• Check: Has services.yml been assessed? (count of "not-assessed" < 15)
• If all 15 are "not-assessed": GATE FAILED -- "Run /mycelium:service-check before completing."
• Check: Has accessibility been considered? (any evidence of a11y work)
• If no evidence: GATE FAILED -- "Run /mycelium:a11y-check for user-facing work."
• Check: Has usability been evaluated? (Nielsen's 10 heuristics via /mycelium:usability-check)
• If no evidence: GATE FAILED -- "Run /mycelium:usability-check for user-facing interfaces." (G-V10)

For api_service or permission_requiring work (G-S2 REVIEW):

• Check: Does threat-model.yml have components listed?
• If empty: GATE FAILED -- "Run /mycelium:threat-model for work that handles data or requires permissions."

For data-handling work (G-S3 REVIEW):

• Check: Does privacy-assessment.yml have principles assessed?
• If all "not-assessed" and product handles user data: GATE FAILED -- "Run /mycelium:privacy-check."

Always Required (REVIEW)

Outcome Definition of Done met (REVIEW):

• Read .claude/diamonds/active.yml for this diamond's definition_of_done (the outcome bar, distinct from the quality checklist below — set at birth via /mycelium:define-done).
• If the field is absent: GATE FAILED — "This diamond has no outcome Definition of Done. Run /mycelium:define-done to pin what behaviour-change marks it done before completing." (Do not silent-fill — the question is what produces a real bar.)
• If present: the gate passes only when either the signal is met with evidence (cite the canvas/decision-log source), OR the kill_criterion (state+date) has fired with evidence — done-by-invalidation, which must route through /mycelium:diamond-progress kill + dogfood-mode, not be declared here. If neither holds: GATE FAILED — report which (signal unmet / kill-date not reached) and stay in Deliver.
• Child diamonds: also verify the outcome rolls_up_to the parent — the parent outcome moved or the parent assumption validated. A child that shipped but did not move the parent is not done (contribution-not-summation).
• This is the diamond-level outcome gate; the items below are per-feature quality. Both must pass.