ost-builder

OST Builder Skill

Build and maintain Opportunity Solution Trees from research evidence.

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.

Workflow

Building a New OST

1. Define the desired outcome at the top of the tree. This comes from the north star metric or current strategic goal.

1. Review all research data: Interview transcripts, behavioral data, analytics, observation notes.

1. Extract opportunities (unmet needs, pain points, desires):
2. Each opportunity must cite at least 2 evidence sources.
3. Phrase as user needs, not solutions: "Users need to know their payment succeeded" not "Users need a confirmation email."
4. Look for frequency across interviews, not just intensity in one.

1. Structure hierarchically: Group related opportunities. Identify parent-child relationships.
2. Before structuring, ensure each opportunity has been examined from all three trio perspectives (product, design, engineering). Product lens sees user value; design lens sees experience gaps; engineering lens sees technical constraints or enablers.
3. Classify each opportunity's Cynefin domain (clear/complicated/complex). Complex-domain opportunities must produce probes (experiments), not fully-designed solutions. See ${CLAUDE_PLUGIN_ROOT}/engine/cynefin-routing.md.

1. For each leaf opportunity, check scenario coverage:
2. Does .claude/canvas/scenarios.yml have at least one scenario illustrating this opportunity?
3. If not: extract one from the research evidence. Use Hoskins' four elements: Persona (who), Means (how they interact), Motive (why — link to JTBD), Simulation (the full narrative).
4. Scenarios should emerge from interview stories, not be invented. If no interview data exists for this opportunity, flag it as an evidence gap.

1. For each leaf opportunity, generate solution ideas:
2. Multiple solutions per opportunity.
3. Solutions can be simple experiments, not just features.
4. Include "do nothing" as an option when appropriate.
5. Each solution should reference which scenarios it addresses.

1. For each solution leaf, assess the Four Risks (Torres Product Trio):
2. Value (product lens): Is there evidence users want/need this?
3. Usability (design lens): Can users figure out how to use it?
4. Feasibility (engineering lens): Can we build it within constraints?
5. Viability (cross-cutting): Does it align with business/legal/ethical?

Each risk must have its own evidence — a combined statement fails. Write four_risks per solution in .claude/canvas/opportunities.yml.

1. For each solution, identify riskiest assumptions from the Four Risks:
2. Which risk dimension has the least evidence?
3. What is the cheapest way to test that assumption?
4. Tag each assumption with its risk_dimension (value|usability|feasibility|viability).

Updating an Existing OST

1. Review new research data since last update.
2. Add new opportunities with evidence citations.
3. Refine or remove opportunities that evidence no longer supports.
4. Add new solutions for validated opportunities.
5. Update confidence scores based on new evidence.
6. Prune solutions that have been invalidated.

Rules

• Never add opportunities without evidence citations.
• Never brainstorm opportunities. Discover them.
• Every opportunity must link to at least 2 research data points.
• Solutions come after opportunities are understood, not before.
• The OST is a living document. Update weekly with new research.
• Avoid the decoy effect: do not generate weak solution variants whose only purpose is to make a preferred option look better in comparison. Each solution must stand on its own user-need rationale. If a solution exists only as a foil for another, drop it. Source: Huber, Payne & Puto, "Adding Asymmetrically Dominated Alternatives" (1982) — adding a clearly inferior option shifts preference toward the dominating option without changing the underlying value.

Canvas Output

Always update .claude/canvas/opportunities.yml with the OST contents after building or updating. This is the single source of truth for the opportunity space.

Also update:

• .claude/canvas/scenarios.yml if scenarios were created or refined (step 5)
• .claude/canvas/user-needs.yml if new needs were identified
• .claude/canvas/jobs-to-be-done.yml if JTBD dimensions surfaced during mapping

Lean UX Connection

When generating solution ideas for leaf opportunities, frame each as a Lean UX hypothesis: "We believe [outcome] for [users] if [change]." This makes the solution testable via /mycelium:assumption-test. Flow: Opportunity (research) -> Solution hypothesis (Lean UX) -> Assumption test (smallest viable test).

Theory Citations

• Torres: Continuous Discovery Habits (OST methodology). Update 2026-05-13 ("Behind the Scenes: Building AI-Generated Opportunity Solution Trees", producttalk.org): Torres now ships AI-generated OSTs via Vistaly, generated from customer interview transcripts (3 minimum, scaling to 16+). This reinforces this skill's "never from brainstorming" rule — the canonical OST voice independently converged on evidence-only generation. Her service also exposes a structural lesson Mycelium has not yet implemented: when updating an OST from new evidence, emit a change set (add/delete/reframe/merge/split) alongside the new tree so users can accept/modify/reject each move. Today /mycelium:ost-builder and `/mycelium:canvas-upda