Wardley Mapping

Visualize your value chain and make strategic decisions. Source: Simon Wardley.

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

Mapping Process

0. Score any due climatic predictions FIRST (added v0.95.0)

Before mapping anything, read .claude/canvas/climatic_predictions in landscape.yml and settle every entry whose due date has passed. Set status to held, refuted or unscoreable, stamp scored_on, and write what actually happened in outcome.

This step is first on purpose. A prediction nobody settles is a wish, and the natural failure is not dishonesty — it is that scoring is boring and mapping is fun, so the unscored pile grows until the record is worthless. Doing it before the interesting work is the only ordering that survives contact with a real session.

unscoreable is a first-class outcome. If a prediction turned out not to be checkable, say so. Marking it held because nothing contradicted it, or quietly deleting it, is how a forecasting record launders itself clean — and a clean record that was never at risk teaches nothing.

1. Identify the User

Who is the map for? What scope?

2. Identify User Needs

What does the user need? Place at the top of the map (most visible).

3. Map the Value Chain

What components are needed to serve those needs? Draw dependency lines top-down.

4. Assess Evolution Stage

For each component:

Stage	Characteristics	Strategy
Genesis	Novel, uncertain, high failure rate	Explore, experiment, small teams
Custom	Better understood, bespoke builds	Build or partner, reduce uncertainty
Product	Standardized, feature competition	Buy or build competitively
Commodity	Utility, cost competition	Consume as service, don't differentiate here

5. Add Movement

Mark components that are evolving (arrow pointing right). All components evolve over time.

6. Identify Patterns

• Components in Genesis = Complex domain (Cynefin) -> probe
• Components in Commodity = Clear domain -> best practice
• Evolution mismatch = waste (building custom what you should buy as commodity)

7. Assess Climate — the patterns that act on you whether or not you look (added v0.95.0)

Wardley's Strategy Cycle runs Purpose → Landscape → Climate → Doctrine → Gameplay → Leadership. Steps 1-6 built the landscape. Climate comes BEFORE gameplay because gameplay chosen against a static picture assumes the board stops moving while you think.

This is the step that makes a map falsifiable. A map that records positions cannot be wrong. Climatic patterns generate statements about what happens NEXT, which can be. Apply each of the five below and emit at least one dated prediction per pass into landscape.yml#climatic_predictions.

Pattern	The question it forces	What a prediction from it looks like
everything-evolves	Which component will have moved a stage by when?	"comp-0NN reaches product by — a second vendor ships a paid managed version."
characteristics-change	What stops being true about a component as it evolves?	"As X commoditises, buyers stop evaluating it on capability and start on price/SLA."
no-choice-over-evolution	What are we resisting that competition will decide anyway?	"Our custom-built Y is superseded by a commodity equivalent by ."
commoditisation-genericisation	Which of our differentiating TERMS will become category vocabulary?	"The phrase we lead with appears in 3+ unrelated products' one-liners by ."
inertia	Who has a working alternative, and what event would break it?	"Self-solvers do not adopt absent a triggering failure; adoption arrives only after a public burn."

Genericisation applies to VOCABULARY, not only components, and that is the case most teams miss. The phrase a project leads with is itself a component on the map, and it commoditises like any other: coined, then borrowed, then category-standard, then worthless as a differentiator. A team that has not predicted this experiences it as a series of unpleasant surprises, each read as news. The test is cheap — search your key phrase and count how many unrelated products use it in their own one-line description. Worked instance (dogfood, 2026-08): a project observed two of its lead terms genericise within 24 hours of each other, one having spread to a domain with no connection to its own, and treated each as a discovery. Both were predictable from this pattern.

Inertia is the pattern that explains non-adoption, and it is usually reached for last because it is unflattering. Someone with a working alternative does not switch on evidence that yours is better; they switch when their alternative visibly fails them. If your evidence is people agreeing with your thesis while continuing to use their own approach, inertia — not persuasion — is the thing to model. Predict the triggering EVENT, not the argument.

Coverage is checkable and unused patterns are a finding. The pattern field is enumerated, so a pass can ask which of the five produced nothing. A pattern that never emits a prediction is one nobody applied, not one that had nothing to say.

8. Apply Gameplay

Strategic options based on the map:

• Open source: Accelerate commoditization
• ILC: Innovate -> Leverage -> Commoditize
• Ecosystem: Build platform, commoditize lower layers
• Tower and moat: Invest in defensibility

Output

Update .claude/canvas/landscape.yml with components, evolution stages, movements, gameplay options, and climatic_predictions (new + scored). Report the coverage of the five climatic patterns explicitly, naming any that produced nothing this pass.

Decision Log (MANDATORY per G-P4)

APPEND a ### Wardley Map Assessment entry to .claude/harness/decision-log.md with: components mapped, evolution stages, strategic gameplay identified, recommendations.

Connection to Other Frameworks

• Evolution stage maps to Cynefin domain (use /mycelium:cynefin-classify)
• User needs at top map to OST outcomes (use /mycelium:ost-builder)
• Strategic gameplay informs GIST goals (use /mycelium:gist-plan)

Postflight: Verify-After-Write (claim matches state)

Hard rule (per CLAUDE.md Communication Rules, anti-pattern #7 write-narration-verification — mechanism Check 42, graduated v0.39.18; enforced surface expanded to this skill v0.44.0). This skill mandates multi-field canvas updates. Before narrating "updated / wrote / refreshed [canvas]" in any user-facing summary, RE-READ the value fields this skill's MANDATORY says to update and confirm they actually changed — not just _meta.last_validated or a freshness stamp. Each field you claim to have updated must reflect its new value. The symmetric half of the Read-before-Write Preflight: that one protects what gets read before a write; this one protects that the write matches the claim. Worked failures: 2026-06-05 #18 (/dora-check narrated "updated" with value fields unchanged) + #19 (/retrospective left a cycle-history aggregate un-propagated).