wardley-mapping

name	wardley-mapping
user-invocable	true
description	Create professional interactive Wardley Maps with strategic analysis, evolution rationale, and actionable recommendations. Produces React artifact maps with hover tooltips, dependency highlighting, and a figure legend, plus OWM-format text and structured strategic commentary. Use this skill when the user asks to create a Wardley map or mentions "wardley mapping".

Wardley Mapping

Create interactive Wardley Maps with rigorous strategic analysis. Every map tells a story about where value comes from, how components evolve, and where to focus strategic effort.

Three Deliverables — Always Produce All Three

1. Interactive React artifact (.jsx) — Wardley Map with hover tooltips showing evolution rationale, click-to-highlight dependency chains, a professional figure legend, and evolution stage shading.

2. OWM (OnlineWardleyMaps) text block — Standard OWM DSL so the user can paste into VS Code, Obsidian, or onlinewardleymaps.com.

3. Strategic commentary — Markdown analysis with per-component evolution rationale table, doctrine observations, and recommended actions.

---

Workflow

Step 1: Establish Strategic Context

Before placing a single component, clarify with the user:

• Strategic question: What decision does this map inform? ("Should we build or buy our auth system?" is better than "map our architecture.")
• User anchor: Who is the customer or end-user at the top of the chain?
• Core needs: What are the user's 2-4 most important needs?
• Scope boundary: One product line? One business unit? Entire company?

If the user provides existing OWM text, parse it first:

python {baseDir}/scripts/parse_owm.py input.owm

({baseDir} is automatically resolved by Claude Code to this skill's installation directory.)

This outputs JSON you can work with directly — skip to Step 4.

Step 2: Build the Value Chain

Work backward from user needs to capabilities to infrastructure:

• Target 8-15 components. Fewer than 6 lacks insight; more than 18 becomes unreadable. If scope is large, propose splitting into a main map plus submaps.
• Every component must connect to at least one other via a dependency.
• The chain must trace from the user anchor down to the lowest dependencies.
• Name components as nouns or noun phrases ("Payment Processing" not "Process Payments").

Step 3: Assess Evolution — The Critical Step

This is what separates a useful Wardley Map from a pretty diagram. For every component, assess its position against the evolution characteristics framework. Read references/evolution-assessment.md for the full criteria.

Terminology: The x-axis represents evolution — the competitive journey from novel to commodity. A component's numeric position on this axis is its maturity value (0.0 to 1.0).

Score each component across all dimensions in the evolution assessment reference (ubiquity, certainty, market, user perception, failure tolerance, focus, methods). Map the aggregate assessment to a maturity value using these operational heuristics for consistent placement:

• Genesis: 0.00–0.17
• Custom-Built: 0.18–0.39
• Product (+Rental): 0.40–0.69
• Commodity (+Utility): 0.70–1.00

Note: Wardley's framework uses qualitative assessment via characteristics, not numeric boundaries. These ranges are operational heuristics for consistent placement. The visual map columns use equal-quarter boundaries (0.25, 0.50, 0.75) following standard OWM tooling convention — the columns are approximate zones, not precise classification boundaries.

Write a 1-2 sentence rationale for each placement. This goes in both the tooltip and the strategic commentary. Rationale should reference observable market evidence — "Multiple utility providers exist (Stripe, PayPal, Adyen) with standardised APIs" — not vague claims.

For AI-era considerations (how AI coding tools are shifting the evolution axis and reshaping build-vs-buy), read references/ai-era-patterns.md.

Step 4: Validate the Map Data

Before rendering, check for logical errors. If {baseDir}/scripts/validate_map.py is available, run it. Otherwise check manually:

• All positions within [0, 1] range for both axes
• No circular dependencies
• Evolution arrows always point rightward (higher maturity)
• Every referenced component exists
• At least one user/anchor component at the top of the chain
• Flag: >15 components (suggest submaps), orphaned components, likely label overlaps (components within 0.06 of each other on both axes)

Step 5: Render the Interactive React Artifact

Generate a React component (.jsx) that renders the Wardley Map. Read templates/artifact-template.jsx for the complete reference implementation. Follow its structure closely — it handles coordinate mapping, layered rendering, interactivity, the figure legend, and label placement.

Key architectural decisions in the template and why they matter:

Use React with inline SVG elements. Claude produces higher-quality output with React components than with raw SVG files. The <svg> element lives inside the React component, benefiting from React's state management for interactivity while using SVG's precision for drawing.

Coordinate system: The template handles SVG coordinate mapping — visibility is inverted (high = top = low SVG y). See templates/artifact-template.jsx for the exact formulas.

Rendering layers (draw in this order):

1. Background: white, clean
2. Evolution stage columns: alternating subtle fills for visual grouping
3. Dashed vertical grid lines at stage boundaries (x = 0.25, 0.50, 0.75)
4. Axis lines with labels (Y: "Visible" → "Invisible", X: the four stages)
5. Pipeline rectangles (horizontal bars spanning evolution range)
6. Dependency lines: solid gray, slight curve (quadratic bezier) to reduce overlap
7. Evolution arrows: dashed red with arrowhead, showing predicted movement
8. Inertia markers: thick bars on resistant components
9. Component circles: filled white, dark stroke, consistent radius
10. Labels: positioned to avoid overlaps (offset algorithm in template)
11. Figure legend: bottom-right or below the map, explaining all symbols
12. Title: top-left, prominent

Interactivity (React state):

• Hover: Show tooltip with component name, evolution stage, and rationale
• Click: Highlight the component and its full dependency chain (both upstream and downstream), dim everything else
• Click background: Clear selection, restore full view

Figure Legend — Include This Every Time: The legend explains the map's visual language. Place it below or beside the map. It must show and label: component circle, dependency line, evolution arrow, inertia marker, pipeline bar, and the four evolution stage labels with their x-axis ranges.

Visual Quality Rules:

• Minimum 10px font size — nothing should require squinting
• Labels offset from circles, not overlapping them
• Use quadratic bezier curves for dependency lines when straight lines would overlap
• Professional, muted colour palette
• No purple gradients, no centred-everything layouts, no rounded-corner card wrappers — these are generic AI aesthetics that undermine credibility
• Map should feel like it belongs in a strategy consulting deck

Available libraries: See the header of templates/artifact-template.jsx for permitted imports and restrictions. Do NOT import D3, Recharts, or other charting libraries — use raw SVG elements inside the React component.

Step 6: Generate OWM Text

Output the map in standard OWM DSL format. Full syntax in references/owm-syntax.md. This makes the map portable to the entire Wardley ecosystem (VS Code extension, Obsidian plugin, onlinewardleymaps.com).

See references/examples/tea-shop.md for the canonical Tea Shop example with OWM source, JSON data, and strategic commentary.

Step 7: Generate Strategic Commentary

Produce a structured analysis. This is where the map becomes actionable.

Template:

# Wardley Map Analysis: [Context]

## Purpose
[The strategic question this map answers]

## Component Evolution Assessment
| Component | Stage | Position [vis, mat] | Rationale |
|---|---|---|---|
| [name] | [Genesis/Custom/Product/Commodity] | [y, x] | [Evidence-based justification] |

## Key Strategic Observations
[3-5 insights derived from the map's topology — what does the shape
of the value chain reveal? Where are clusters of genesis components?
Where are potential single points of failure?]

## Doctrine Check
[Assess the map against relevant Wardley doctrine principles.
Read references/doctrine-and-gameplay.md for the full catalogue.]
- Are user needs clearly identified?
- Is there unnecessary duplication?
- Are appropriate methods matched to evolution stages?
- Is there bias toward a single stage?

## Recommended Actions
[3-5 prioritized, concrete actions with justification from map positions]

## Build vs. Buy Assessment
| Component | Recommendation | Rationale |
|---|---|---|
| [genesis/custom] | Build/Invest | [why — competitive advantage, no market alternative] |
| [product/commodity] | Buy/Outsource | [why — mature market, not a differentiator] |

## Evolution Predictions (12-24 months)
[Which components are likely to move rightward? What market forces
drive this? What inertia might resist it?]

## Open Questions
[2-3 questions the map raises for further investigation]

For AI-era build-vs-buy considerations, read references/ai-era-patterns.md — it covers how AI coding tools are compressing the Custom-Built→Product boundary and shifting the economics.

For doctrine and gameplay patterns beyond the basics, read references/doctrine-and-gameplay.md — it covers the Pioneers-Settlers-Town Planners (PST) framework, climatic patterns, and key gameplay moves.

---

When Things Go Wrong

• Validation errors: Fix the specific issue, re-validate. Common: circular dependencies from copy-paste, positions outside [0,1] from coordinate confusion.
• Incomplete user input: Ask for the missing context. Don't guess strategic questions — the map's value comes from the user's domain knowledge.
• Ambiguous evolution stage: Default to the stage supported by the most dimensions. Document the ambiguity in the rationale: "Positioned at Product (0.45) — ubiquity suggests Commodity but market is still fragmenting."
• >15 components: Propose splitting into a main map + submaps. Each submap replaces one component on the main map.

---

Handling Different User Requests

User says...	What to do
"Create a Wardley map for X"	Full workflow, Steps 1-7
"Here's my OWM, render it"	Parse → validate → render artifact + legend (Steps 4-6)
"Analyze this map"	Parse → full assessment → all three deliverables
"What stage is X at?"	Read evolution-assessment.md, apply framework, explain
"Build vs buy for X"	Read ai-era-patterns.md, assess stage, give grounded advice
"Add component X to this map"	Update existing map data, re-render, update analysis
"Compare our map to [industry]"	Render user's map, note where their placements differ from industry norms

Recognizing Context Patterns

These heuristics help with initial placement, but always verify against the evolution assessment framework — don't rely on pattern matching alone:

• Startup context: Expect many Genesis/Custom components, few Commodity
• Enterprise IT: Expect more Product/Commodity, watch for Custom-Built components that should have evolved further (inertia signal)
• "We built our own X": Flag potential inertia — is Custom-Built justified or are they resisting available Product/Commodity alternatives?
• "Everyone uses X": Likely Product or Commodity stage
• "We're experimenting with X": Likely Genesis
• Disruption context: Look for evolution compression and value chain restructuring

Reference Files

Read these when you need deeper detail beyond what's in this SKILL.md.

Token efficiency: Read reference files on demand per the workflow steps. Do NOT read all files at once — only load what the current step requires.

File	When to read
references/evolution-assessment.md	Every time you assess component positions (Step 3)
references/doctrine-and-gameplay.md	When generating strategic commentary (Step 7)
references/owm-syntax.md	When generating OWM output with advanced features (pipelines, annotations)
references/ai-era-patterns.md	When the map involves technology/software components or build-vs-buy
references/examples/tea-shop.md	For the canonical reference example
references/examples/saas-platform.md	For a modern enterprise SaaS example
references/examples/ai-startup.md	For an AI-era example with compressed evolution
templates/artifact-template.jsx	Every time you render a map artifact (Step 5) — read this closely
assets/style-constants.json	Visual style reference — authoritative colour values, font sizes, canvas dimensions. The artifact template embeds these inline; this file is the single source of truth for updates