| name | wardley-mapping |
| description | This skill should be used when the user asks about Wardley Mapping, evolution stages, strategic positioning, creating maps, value chain decomposition, gameplay patterns, doctrine assessment, climatic patterns, build vs. buy, or inertia analysis. |
| paths | ["**/ARC-*-WARD-*.md","**/*.wardley"] |
Wardley Mapping
A strategic mapping technique created by Simon Wardley for understanding competitive landscape, technology evolution, and making informed architectural decisions. A Wardley Map visualizes four dimensions: the value chain (components needed to meet user needs), evolution (how components mature over time), the landscape (competitive environment), and movement (how the landscape changes).
This skill ships reference material, not runnable scripts. Read the relevant section here (or the linked references) with Read, apply the OnlineWardleyMaps syntax, and write the map into the user's artefact. Do not Bash-execute anything from this skill — there is no script to run.
Map Structure
The following diagram illustrates the conceptual axes of a Wardley Map. For the generation template with placeholders, see the Map Template section below.
EVOLUTION
Genesis Custom Product Commodity
↓ ↓ ↓ ↓
┌──────────────────────────────────────────┐
│ │
Visible │ User Need ● │ ← Anchor
│ │ │
│ ↓ │
│ Component A ●──────────→ ● │
│ │ │
│ ↓ │
│ Component B ● │
│ │ │
Hidden │ ↓ │
│ Component C ● │
│ │ │
│ ↓ │
│ Component D ● │ ← Commodity
│ │
└──────────────────────────────────────────┘
Y-axis: Visibility (to user)
X-axis: Evolution (certainty)
Evolution Stages (Summary)
| Stage | Position | Key Trait | Sourcing | Example |
|---|
| Genesis | Far left (0.0-0.25) | Novel, uncertain, high failure | Build (R&D) | Novel AI architectures |
| Custom-Built | Center-left (0.25-0.50) | Understood but bespoke, differentiating | Build (custom dev) | Bespoke trading platform |
| Product | Center-right (0.50-0.75) | Multiple vendors, feature competition | Buy (configure) | CRM systems |
| Commodity | Far right (0.75-1.0) | Well understood, essential, utility | Outsource (consume) | Cloud compute (IaaS) |
For detailed stage characteristics, indicators, and positioning criteria, see references/evolution-stages.md.
How to Create a Wardley Map
Follow these steps in order when the user asks to create or analyze a Wardley Map.
Step 1: Gather Context
Use the AskUserQuestion tool to interactively gather the information needed to create the map. Ask up to 3 questions at a time.
First, identify the anchor and scope:
Use AskUserQuestion to ask:
- Who is the primary user? — Options might include: "External customers", "Internal developers", "Business analysts", or let the user specify
- What is the user need? — e.g., "Purchase products online", "Deploy applications reliably", "Generate analytical reports"
- What is the scope? — Options: "Single product/service", "Business unit", "Entire organization", "Specific capability"
Then, gather strategic context:
Use AskUserQuestion to ask:
- What is the primary goal? — Options: "Identify investment priorities", "Evaluate build vs. buy", "Assess competitive position", "Plan technology evolution"
- What industry/domain? — Let the user specify (affects how components are positioned on the evolution axis)
- What depth of analysis? — Options: "Quick overview (5-10 components)", "Standard map (10-20 components)", "Deep analysis (20+ components with gameplay)"
Step 2: Build the Value Chain
Work backwards from the user need. List every component required to deliver it, then arrange them by visibility (user-facing at top, infrastructure at bottom). For each component, identify what it depends on — dependencies flow downward.
- List capabilities, not just technologies
- Include people, practices, and data alongside technical components
- Map both technical and business components
- Ask: "What components are needed?", "What does each depend on?", "What is hidden from the user?"
If component identification is uncertain, use AskUserQuestion to ask the user about key capabilities, technologies, and processes in their domain.
Step 3: Position on Evolution
For each component, assess its evolution stage using the indicators in references/evolution-stages.md. Place it on the X-axis accordingly.
Key questions for each component:
- How well understood is it in the market?
- How many alternatives exist?
- Is it commoditized or unique?
- What's the market maturity?
Avoid common mistakes: don't position based on age (use market maturity), don't confuse internal unfamiliarity with market-wide genesis, and always consider industry context.
If positioning is ambiguous for key components, use AskUserQuestion to clarify with the user — e.g., "Is your recommendation engine a custom differentiator or are you using an off-the-shelf product?"
Step 4: Add Movement
Add arrows showing how components are evolving. All components naturally drift rightward over time, but some move faster or slower.
→ Natural evolution (component moving right over time)× Inertia (resistance to movement from past success, skills, or politics)>> Acceleration (forced rapid evolution from competition or disruption)
Step 5: Analyze and Recommend
After drawing the map, apply the analysis checklist below, then review gameplay patterns in references/gameplay-patterns.md and climatic patterns in references/climatic-patterns.md to identify strategic moves.
Use AskUserQuestion to confirm priorities with the user before finalizing recommendations — e.g., "The map suggests these three strategic moves. Which areas are most important to your organization right now?"
Step 6: Quantitative Analysis (Optional)
When the user asks for numeric precision, scoring, or data-driven positioning, apply the mathematical models from references/mathematical-models.md:
- Evolution Scoring — Calculate precise X-axis positions using Ubiquity and Certainty scores
- Decision Metrics — Differentiation Pressure, Commodity Leverage, and Dependency Risk
- Weak Signal Detection — Assess readiness factors to predict stage transitions
Present results as a table alongside the qualitative analysis — the numbers should confirm or challenge the intuitive positioning, not replace it.
Common Gotchas
The highest-signal failures, collected from real maps. Check these before finalizing.
Positioning mistakes
- Positioning by age, not market maturity. A 20-year-old internal system is not Commodity if the capability it provides is still bespoke across the market. Use ubiquity + certainty, never "how long we've had it." (See Step 3 and references/evolution-stages.md.)
- Confusing internal unfamiliarity with Genesis. "New to us" ≠ "new to the world." If multiple vendors sell it, it is Product/Commodity even if your team has never used it. This is the single most common error.
- Treating the Y-axis as importance. Visibility means visibility to the user, not business value or criticality. Power supply is invisible-but-critical → it belongs low on the map, not high.
- Floating components with no anchor. Every value chain must trace upward to the user need. A component nothing depends on (directly or transitively) is either mis-placed or doesn't belong on this map.
OnlineWardleyMaps (OWM) syntax — for the /arckit:wardley* commands
These produce OWM text for https://create.wardleymaps.ai. The renderer is strict:
- Coordinates are
[visibility, evolution], both 0–1, in that order — component Foo [0.9, 0.2]. Authors routinely swap the pair or use 0–100; either silently mis-renders. Visibility first (Y), evolution second (X).
- Declare a component before linking it.
A->B referencing an undeclared B drops the link. Declare all component lines first, dependency lines after.
evolve needs only the target X, and the component must already exist: evolve Foo 0.7. Don't restate visibility; don't evolve a name you never declared.- Names with spaces work in declarations but must match exactly in links —
component Data Pipeline [..] then Kettle->Data Pipeline, not ->DataPipeline. Trailing whitespace breaks the match.
- Stage-boundary x-values: Genesis
0.0–0.25, Custom 0.25–0.50, Product 0.50–0.75, Commodity 0.75–1.0. Keep positions inside the intended band so the visual reads correctly.
- One statement per line. OWM is line-based; no semicolons, no inline comments after a statement.
Process mistakes
- Skipping the AskUserQuestion triage. Inventing the user need, scope, or positioning instead of asking produces a confident-but-wrong map. When positioning is ambiguous for a key component, ask (Step 3) rather than guess.
- Listing only technology. A value chain includes people, practices, and data — not just systems. Maps that are all boxes-of-software miss the inertia and doctrine insights that make the exercise worthwhile.
- Recommendations with no rationale. Every strategic move must tie back to a position or movement on the map ("commoditize X because it sits Product-right with three vendors"), not generic advice.
Analysis Checklist
Apply this checklist to every completed map:
analysis_checklist:
completeness:
- "Is the anchor (user need) clearly defined?"
- "Are all components necessary to meet the need included?"
- "Are dependencies shown?"
- "Are movement arrows present?"
positioning:
- "Is each component positioned based on market evolution, not internal capability?"
- "Are commodity components on the right?"
- "Are genuinely novel components on the left?"
insights:
- "What components have inertia?"
- "Where are there opportunities to commoditize?"
- "What genesis activities could become differentiators?"
- "Where is there technical debt (building custom where products exist)?"
strategic:
- "What gameplay patterns apply?"
- "Where should we invest vs. outsource?"
- "What climatic patterns affect our landscape?"
- "What doctrine weaknesses exist?"
For deeper strategic analysis, consult:
Map Template
Always produce the visual map using the template below. Also produce the structured YAML output (using the Output Format section) when writing the map to a file; for conversational responses, the visual map alone is sufficient.
Use this template when generating a visual Wardley Map:
Title: {Map Name}
Anchor: {User Need}
Date: {ISO-8601}
Genesis Custom Product Commodity
│ │ │ │
Visible ┌───┼──────────┼──────────┼──────────┼───┐
│ │ │ │ │ │
│ │ {User Need} │
│ │ │ │
│ │ ↓ │
│ │ {Component 1} ●──────→ │
│ │ │ │
│ │ ├───────────────┐ │
│ │ ↓ ↓ │
│ │ {Component 2} {Component 3} │
│ │ ● ● │
│ │ │ │ │
│ │ ↓ │ │
│ │ {Component 4} │ │
│ │ ● │ │
Hidden │ │ │ │ │
│ │ ↓ ↓ │
│ │ {Component 5}───────┘ │
│ │ ● │
│ │ │
└───┴────────────────────────────────────┘
Legend: ● Current position, → Evolution direction, × Inertia
Output Format
When generating a Wardley Map document, use this structure:
wardley_map:
metadata:
title: "{Map Name}"
author: "{Author}"
date: "{ISO-8601}"
version: "1.0"
scope: "{What this map covers}"
anchor:
user: "{User description}"
need: "{User need statement}"
components:
- name: "{Component Name}"
evolution: "{Genesis/Custom/Product/Commodity}"
position: "{0.0-1.0}"
visibility: "{0.0-1.0}"
depends_on:
- "{Dependency 1}"
- "{Dependency 2}"
notes: "{Strategic notes}"
movement: "{evolving/accelerating/inertia/none}"
analysis:
opportunities:
- "{Opportunity 1}"
- "{Opportunity 2}"
threats:
- "{Threat 1}"
- "{Threat 2}"
inertia_points:
- component: "{Component}"
reason: "{Why inertia exists}"
recommendations:
immediate:
- "{Action with rationale}"
short_term:
- "{Action with rationale}"
long_term:
- "{Action with rationale}"
References
Consult these reference files for deeper analysis:
- Evolution Stages — Stage characteristics, indicators, positioning criteria, transition heuristics, pioneers/settlers/planners talent model
- Climatic Patterns — 32 patterns across 6 categories (component, financial, speed, inertia, competitor, prediction), peace/war/wonder cycle, pattern interactions
- Gameplay Patterns — 60+ plays across 11 categories with D&D alignment classification, play-position matrix, play compatibility, case studies (AWS, Netflix, Tesla, Spotify)
- Doctrine — 40+ principles across 4 phases and 6 categories, Strategy Cycle framework, implementation journeys, maturity assessment template
- Mapping Examples — Worked examples: E-Commerce, DevOps Platform, ML Product, TechnoGadget Smart Home, value chain decomposition walkthrough, case study cross-references
- Mathematical Models — Evolution scoring formulas, decision metrics, weak signal detection, play-position scoring, climate pattern impact weighting
ArcKit Integration
This skill handles conversational Wardley Mapping — quick questions, evolution stage lookups, doctrine assessments, and interactive map creation.
For formal architecture documents with document control, project integration, UK Government compliance (TCoP, GDS, AI Playbook), and OnlineWardleyMaps syntax for https://create.wardleymaps.ai, use the ArcKit Wardley suite:
/arckit:wardley.value-chain — Decompose user needs into value chains (WVCH artifact)/arckit:wardley — Create strategic Wardley Maps (WARD artifact)/arckit:wardley.doctrine — Assess organizational doctrine maturity across 4 phases, 40+ principles (WDOC artifact)/arckit:wardley.gameplay — Analyze strategic plays from 60+ gameplay patterns with D&D alignment (WGAM artifact)/arckit:wardley.climate — Assess 32 climatic patterns across 6 categories with prediction horizons (WCLM artifact)
These generate versioned artifacts saved to your project directory with full traceability to requirements and architecture principles. Each command works standalone but gets richer when sibling artifacts exist.
