wardley-mapping

name	wardley-mapping
description	Wardley Mapping reference for a map, a positioning question or a strategic read: value-chain decomposition, evolution stages, OnlineWardleyMaps syntax, gameplay, doctrine and climatic patterns, build-versus-buy and inertia. Also loaded while a WARD artefact is being written. Not needed when the request is for a governed Wardley artefact with document control; the /arckit:wardley, wardley.value-chain, wardley.doctrine, wardley.gameplay and wardley.climate commands produce those.
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:

1. Evolution Scoring — Calculate precise X-axis positions using Ubiquity and Certainty scores
2. Decision Metrics — Differentiation Pressure, Commodity Leverage, and Dependency Risk
3. 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:

• Gameplay Patterns for offensive/defensive moves and build vs. buy guidance
• Climatic Patterns for external forces affecting the landscape
• Doctrine for organizational maturity weaknesses

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: 

  
    
       
    
       
    
       

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.