wardley-map git:20260805.f245a07A

Immutable. This exact content is served forever at /api/v1/blob/1d8990920c41d6b6.

---
name: wardley-map
description: "Create or update a Wardley Map of how any domain delivers value. Maps the needs it serves, the capabilities involved, how each is evolving (genesis to commodity), and strategic plays. Applies to any domain, not only software."
metadata:
  instruction_budget: "10"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."
---

# 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 "^  - 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.

## 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 <date> — 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 <date>." |
| **commoditisation-genericisation** | **Which of our differentiating TERMS will become category vocabulary?** | "The phrase we lead with appears in 3+ unrelated products' one-liners by <date>." |
| **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).