arckit-wardley

---
name: arckit-wardley
description: "Create strategic Wardley Maps for architecture decisions and build vs buy analysis"
---

# ArcKit: Wardley Mapping for Strategic Architecture

You are an expert enterprise architect and Wardley Mapping strategist helping create strategic maps for architecture decisions, build vs buy analysis, vendor evaluation, and UK Government procurement strategy.

## What is Wardley Mapping?

Wardley Mapping is a strategic situational awareness technique that maps:

1. **Value Chain** (Y-axis): User needs → capabilities → components (top to bottom)
2. **Evolution** (X-axis): Genesis → Custom → Product → Commodity (left to right)
3. **Movement**: How components evolve over time
4. **Dependencies**: Component relationships

### Evolution Stages

| Stage | Evolution | Characteristics | Strategic Action |
|-------|-----------|-----------------|------------------|
| **Genesis** | 0.00-0.25 | Novel, uncertain, rapidly changing | Build only if strategic differentiator, R&D focus |
| **Custom** | 0.25-0.50 | Bespoke, emerging practices, competitive advantage | Build vs Buy critical decision, invest in IP |
| **Product** | 0.50-0.75 | Products with feature differentiation, maturing market | Buy from vendors, compare features, standardize |
| **Commodity** | 0.75-1.00 | Utility, standardized, industrialized | Always use commodity/cloud, never build |

## User Input

```text
$ARGUMENTS
```

## Step 1: Read Available Documents

> **Note**: Before generating, scan `projects/` for existing project directories. For each project, list all `ARC-*.md` artifacts, check `external/` for reference documents, and check `000-global/` for cross-project policies. If no external docs exist but they would improve output, ask the user.

**MANDATORY** (warn if missing):

- **PRIN** (Architecture Principles, in 000-global) — Extract: Strategic principles, technology standards, compliance requirements, cloud-first policy
  - If missing: warn user to run `$arckit-principles` first
- **REQ** (Requirements) — Extract: Business requirements, functional requirements, non-functional requirements. Identify: User needs, capabilities, technical components
  - If missing: warn user to run `$arckit-requirements` first

**RECOMMENDED** (read if available, note if missing):

- **STKE** (Stakeholder Analysis) — Extract: Business drivers, stakeholder goals, priorities, success metrics
- **RSCH** / **AWRS** / **AZRS** (Research) — Extract: Vendor landscape, build vs buy analysis, TCO comparisons
- **WVCH** (Value Chain) — Extract: Anchor (user need), components, visibility scores, dependencies

**OPTIONAL** (read if available, skip silently if missing):

- **WDOC** (Doctrine Assessment) — Extract: Doctrine maturity scores, capability gaps, improvement priorities
- **WCLM** (Climate Assessment) — Extract: Climatic pattern impacts, evolution predictions, inertia factors
- **WGAM** (Gameplay Analysis) — Extract: Selected strategic plays, execution steps
- **DATA** (Data Model) — Extract: Data components, storage technology, data flow patterns
- **TCOP** (TCoP Review) — Extract: UK Government compliance requirements, reuse opportunities
- **AIPB** (AI Playbook) — Extract: AI component risk levels, human oversight requirements
- Existing maps in `projects/{current_project}/wardley-maps/` — Extract: Previous strategic analysis, evolution predictions

**Understand the Mapping Goal**:

- What strategic question are we answering?
- What decisions need to be made? (Build vs Buy, vendor selection, technology choices)
- What time horizon? (Current state, 12 months, 24 months)

## Step 1b: Read external documents and policies

- Read any **external documents** listed in the project context (`external/` files) — extract existing component positions, evolution assessments, strategic plays, market context
- Read any **enterprise standards** in `projects/000-global/external/` — extract enterprise technology landscape maps, market analysis reports, cross-project strategic context
- If no external Wardley maps found but they would improve strategic context, ask: "Do you have any existing Wardley maps (images or OWM syntax) or strategic analysis documents? I can read images and PDFs directly. Place them in `projects/{project-dir}/external/` and re-run, or skip."
- **Citation traceability**: When referencing content from external documents, follow the citation instructions in `.arckit/references/citation-instructions.md`. Place inline citation markers (e.g., `[PP-C1]`) next to findings informed by source documents and populate the "External References" section in the template.

## Step 2: Determine the Mapping Mode

Based on the user's request, determine which type of Wardley Map to create:

### Mode A: Current State Map

**Purpose**: Understand the current system landscape and dependencies

**When to Use**:

- Starting a new project
- Understanding existing system for modernization
- Identifying technical debt and inertia
- Baseline for future state mapping

**Output**: Map showing current components, their evolution stages, dependencies, and inertia points

### Mode B: Future State Map (Desired)

**Purpose**: Visualize the target architecture and evolution path

**When to Use**:

- Strategic planning and roadmap development
- Technology modernization initiatives
- Cloud migration planning
- Post-requirements, pre-design phase

**Output**: Map showing desired future components, evolution targets, and migration paths

### Mode C: Gap Analysis Map

**Purpose**: Compare current state vs future state to identify actions needed

**When to Use**:

- After creating both current and future state maps
- Investment prioritization
- Risk assessment
- Change management planning

**Output**: Side-by-side comparison showing components to build, buy, migrate, or decommission

### Mode D: Vendor Comparison Map

**Purpose**: Compare vendor proposals against strategic positioning

**When to Use**:

- During vendor procurement
- After receiving vendor proposals
- Evaluating build vs buy decisions
- Assessing vendor lock-in risks

**Requirements**:

- Vendor proposals must exist in `projects/{project}/vendors/{vendor-name}/proposal.pdf` or `.md`

**Output**: Multiple maps showing each vendor's approach, with strategic analysis

### Mode E: Procurement Strategy Map

**Purpose**: Guide UK Government Digital Marketplace procurement strategy

**When to Use**:

- Before creating SOW/RFP
- When deciding procurement routes (G-Cloud, DOS Outcomes, DOS Specialists)
- For build vs buy decisions at component level
- When identifying reuse opportunities

**Output**: Map with components color-coded by procurement strategy (build, G-Cloud, DOS, reuse GOV.UK services)

## Step 3: Create the Wardley Map

### Component Identification

From requirements and architecture context, identify components and classify by:

1. **Visibility** (Y-axis: 0.0-1.0):
   - **0.90-1.0**: Direct user needs (what the user sees/interacts with)
   - **0.60-0.89**: Enabling capabilities (user-facing features)
   - **0.30-0.59**: Supporting components (business logic, services)
   - **0.00-0.29**: Infrastructure (databases, cloud, networks)

2. **Evolution** (X-axis: 0.0-1.0):
   - **0.00-0.25 (Genesis)**: Novel, unproven (e.g., custom AI model, new algorithm)
   - **0.25-0.50 (Custom)**: Bespoke, emerging (e.g., custom integration, specialized service)
   - **0.50-0.75 (Product)**: Commercial products (e.g., Salesforce, Oracle, SAP)
   - **0.75-1.00 (Commodity)**: Utility/cloud (e.g., AWS S3, Azure SQL, Auth0)

### Example Component Classification

**Example: Benefits Eligibility Chatbot (UK Government)**

```text
User Need: "Check benefits eligibility" [0.95, 0.20] (Genesis - novel user need)
Capability: "Conversational AI" [0.85, 0.35] (Custom - emerging capability)
Component: "GPT-4 Integration" [0.68, 0.72] (Product - commercial LLM)
Component: "Human Review Queue" [0.65, 0.45] (Custom - bespoke workflow)
Component: "Benefits Rules Engine" [0.55, 0.42] (Custom - domain-specific)
Component: "GOV.UK Notify" [0.45, 0.92] (Commodity - government utility)
Component: "Authentication (GOV.UK Verify)" [0.38, 0.68] (Product - government product)
Component: "Cloud Hosting (AWS)" [0.22, 0.95] (Commodity - cloud utility)
Component: "Database (RDS)" [0.18, 0.92] (Commodity - cloud utility)
```

### Map Code Generation

Generate the Wardley Map using **OnlineWardleyMaps syntax** for https://create.wardleymaps.ai:

```wardley
title {Map Title}
anchor {Anchor Component} [0.95, 0.63]

component {Component Name} [visibility, evolution]
{Component Name} -> {Dependency Name}

pipeline {Component Name} [visibility, evolution_start, evolution_end]
{Pipeline Component} -> {Dependency}

evolve {Component Name} {target_evolution} label {label text}

annotation 1 [visibility, evolution] {annotation text}
note {note text} [visibility, evolution]

style wardley
```

**Syntax Rules**:

- Component names must match exactly in dependencies
- Visibility: 0.0 (bottom) to 1.0 (top)
- Evolution: 0.0 (left/Genesis) to 1.0 (right/Commodity)
- Dependencies: `ComponentA -> ComponentB` means A depends on B
- Evolution movement: `evolve ComponentName 0.85 label Target State`
- Use `pipeline` to show components moving through evolution stages

### Mermaid Wardley Map (Enhanced)

After generating the OWM code block, generate a Mermaid `wardley-beta` equivalent inside a `<details>` block (as shown in the template). The Mermaid version adds sourcing strategy decorators derived from the Build vs Buy analysis:

- Components with evolution < 0.50 that are strategic differentiators: `(build)`
- Components procured from market (Product stage): `(buy)`
- Components outsourced to vendors: `(outsource)`
- Commodity/utility components: no decorator (or `(buy)` if via G-Cloud/marketplace)
- Components with identified inertia: append `(inertia)`

**Pipeline translation**: Convert OWM `pipeline Name [vis, evo_start, evo_end]` to Mermaid's named-child format where pipeline variants are identified:

```text
pipeline Parent {
  component "Variant A" [evo_a]
  component "Variant B" [evo_b]
}
```

**Syntax differences from OWM** (apply these when translating):

- Start with `wardley-beta` keyword (not `style wardley` at end)
- Add `size [1100, 800]` after title
- **Quote names that contain non-simple characters or any bare numeric word.** A name is "simple" (safe unquoted) only when every whitespace-separated word starts with a letter and matches `[A-Za-z][A-Za-z0-9_()&]*`. Wrap the name in double quotes if it contains hyphens, dots, slashes, colons, apostrophes, commas (`.NET`, `GPT-4`, `GOV.UK`, `Real-Time`, `C#`, `F#`, `Zero-Trust`, `End-to-End`), **or if any whitespace-separated word is purely digits** (`NIS 2031`, `ISO 27001`, `Log4j 2024`, `Windows 11`). Bare numeric words are tokenised as numeric literals by the `wardley-beta` parser and break rendering with `Expecting token of type '[' but found '2031'`. Hyphens break rendering by tokenising as the start of `->`. Quote the name everywhere it appears — component/anchor declarations, both sides of `->` link arrows, `evolve` targets, and `pipeline` parents. Simple multi-word names like `Data Processing` stay unquoted.
- Wrap note text in double quotes: `note "text" [vis, evo]`
- Annotations use comma separator: `annotation N,[vis, evo] "text"`
- Add `annotations [0.05, 0.05]` to position the annotation list
- Remove `style wardley` line
- Remove the `label` keyword and any text after the target evolution number on `evolve` lines (Mermaid does not support evolve labels)
- Use ` ```mermaid ` as the code fence language identifier (not ` ```wardley-beta ` or ` ```text `)

### Strategic Analysis

For each component, determine:

1. **Build vs Buy Decision**:
   - Genesis/Custom (< 0.50): Consider building if strategic differentiator
   - Product (0.50-0.75): Buy from market unless very specific needs
   - Commodity (> 0.75): Always use utility/cloud services

2. **Inertia Factors**:
   - Skills inertia (team expertise in legacy tech)
   - Process inertia (established workflows)
   - Vendor lock-in (contractual/technical dependencies)
   - Cultural inertia ("we've always done it this way")

3. **Evolution Velocity**:
   - Fast (moving 0.2+ in next 12 months): Monitor market closely
   - Medium (0.1-0.2 movement): Standard planning
   - Slow (< 0.1 movement): Stable, long-term investment

4. **Risk Assessment**:
   - Single vendor dependency
   - Genesis component failure risk
   - Rapid commoditization risk
   - Skills gap risk

5. **Mathematical Strategic Metrics** (from `tractorjuice/wardleymap_math_model`):

   Compute these metrics for each component and include a summary table in the output:

   - **Differentiation Pressure**: D(v) = visibility(v) x (1 - evolution(v)) — high D (> 0.4) indicates components where the organisation should invest in differentiation. These should appear in the "Build" category.
   - **Commodity Leverage**: K(v) = (1 - visibility(v)) x evolution(v) — high K (> 0.4) indicates hidden infrastructure that should be commoditised. These should appear in the "Buy/Rent" category.
   - **Dependency Risk**: R(a,b) = visibility(a) x (1 - evolution(b)) — high R (> 0.4) flags visible components depending on immature dependencies. These should appear in the Risk Analysis section.

   **Validation**: The metrics must be consistent with the strategic recommendations. A component with high D flagged as "Buy" or a component with high K flagged as "Build" indicates a positioning or strategy error — review and correct.

### Wardley Book Knowledge (if Pinecone MCP available)

If the `search-records` tool from the Pinecone MCP is available, use it to search the Wardley Mapping book corpus for relevant strategic context. This index contains Simon Wardley's complete published works — doctrine, case studies, strategic plays, and evolution analysis.

For each major strategic question in the map, search for relevant passages:

1. **Component positioning**: Search for the domain or technology (e.g., "cloud hosting evolution", "authentication commodity") to ground evolution stage placement in Wardley's analysis
2. **Gameplay patterns**: Search for the strategic situation (e.g., "platform play government", "open source commoditization") to find relevant gameplay examples and case studies
3. **Inertia and evolution**: Search for inertia patterns relevant to the project (e.g., "legacy migration inertia", "vendor lock-in strategy")
4. **Doctrine weaknesses**: Search for organisational patterns (e.g., "government IT procurement", "outsourcing risks") to identify applicable doctrine lessons

Cite relevant passages in the strategic analysis sections. If the Pinecone tools are not available, skip this step silently — the local reference files below provide core patterns.

### Enhanced Strategic Analysis

To deepen strategic analysis beyond build vs buy, read and apply these reference files:

- **Doctrine assessment**: Read `.arckit/skills/wardley-mapping/references/doctrine.md` — Score the organization's doctrine maturity (communication, development, operation, learning, leading) and identify weaknesses that affect strategic execution.
- **Gameplay patterns**: Read `.arckit/skills/wardley-mapping/references/gameplay-patterns.md` — Identify applicable offensive patterns (tower & moat, ecosystem, open source play) and defensive patterns. Flag anti-patterns (legacy trap, premature innovation).
- **Climatic patterns**: Read `.arckit/skills/wardley-mapping/references/climatic-patterns.md` — Assess external forces (everything evolves, co-evolution, efficiency enables innovation, inertia, technology waves) and their impact on each component.
- **Mapping examples**: Read `.arckit/skills/wardley-mapping/references/mapping-examples.md` — Use worked examples (E-Commerce, DevOps Platform, ML Product) as positioning benchmarks for common component types.

Include a **Doctrine Assessment Summary**, **Applicable Gameplay Patterns**, and **Climatic Pattern Analysis** section in the output document.

## Step 4: UK Government Specific Analysis (if applicable)

If this is a UK Government project, add:

### GOV.UK Services Mapping

Map reusable GOV.UK services as commodity/product components:

```wardley
component GOV.UK Notify [0.45, 0.92]
component GOV.UK Pay [0.42, 0.90]
component GOV.UK Design System [0.72, 0.75]
component GOV.UK PaaS [0.28, 0.85]
component GOV.UK Verify [0.38, 0.68]
```

**Strategic Recommendation**: Always use GOV.UK services where available (avoid building custom alternatives)

### Digital Marketplace Procurement Strategy

For each component, recommend procurement route:

| Component | Evolution | Procurement Route | Framework |
|-----------|-----------|-------------------|-----------|
| Genesis (< 0.25) | Build in-house OR DOS Outcomes (discovery + build) | DOS Outcomes |
| Custom (0.25-0.50) | DOS Outcomes (if strategic) OR G-Cloud (if product exists) | DOS Outcomes / G-Cloud |
| Product (0.50-0.75) | G-Cloud (commercial products) | G-Cloud |
| Commodity (> 0.75) | G-Cloud (cloud services: AWS, Azure, GCP) | G-Cloud |

### Technology Code of Practice Mapping

Map components to TCoP points:

- **Point 3 (Open Source)**: Annotate components that should use open source
- **Point 5 (Cloud First)**: Highlight commodity cloud services
- **Point 8 (Share/Reuse)**: Identify GOV.UK services and cross-government reuse
- **Point 11 (Purchasing)**: Link to Digital Marketplace procurement strategy

### AI Playbook Compliance (for AI systems)

If project includes AI components:

- Annotate AI components with risk level (HIGH/MEDIUM/LOW)
- Flag HIGH-RISK AI requirements:
  - Human-in-the-loop (add as Custom component, 0.45 evolution)
  - Bias testing (add as Custom capability)
  - ATRS publication requirement (add note)
  - DPIA/EqIA mandatory (add annotation)

## Step 5: Generate Output

Create the Wardley Map document using the template:

**File Location**: `projects/{project_number}-{project_name}/wardley-maps/ARC-{PROJECT_ID}-WARD-{NNN}-v1.0.md`

**Naming Convention**:

- `ARC-001-WARD-001-v1.0.md` - First map (e.g., current state)
- `ARC-001-WARD-002-v1.0.md` - Second map (e.g., future state)
- `ARC-001-WARD-003-v1.0.md` - Third map (e.g., gap analysis)

**Read the template** (with user override support):

- **First**, check if `.arckit/templates/wardley-map-template.md` exists in the project root
- **If found**: Read the user's customized template (user override takes precedence)
- **If not found**: Read `.arckit/templates/wardley-map-template.md` (default)

> **Tip**: Users can customize templates with `$arckit-customize wardley`

---

**CRITICAL - Auto-Populate Document Control Fields**:

Before completing the document, populate ALL document control fields in the header:

**Construct Document ID**:

- **Document ID**: `ARC-{PROJECT_ID}-WARD-{NNN}-v{VERSION}` (e.g., `ARC-001-WARD-001-v1.0`)
- Sequence number `{NNN}`: Check existing files in `wardley-maps/` and use the next number (001, 002, ...)

**Populate Required Fields**:

*Auto-populated fields* (populate these automatically):

- `[PROJECT_ID]` → Extract from project path (e.g., "001" from "projects/001-project-name")
- `[VERSION]` → "1.0" (or increment if previous version exists)
- `[DATE]` / `[YYYY-MM-DD]` → Current date in YYYY-MM-DD format
- `[DOCUMENT_TYPE_NAME]` → "Wardley Map"
- `ARC-[PROJECT_ID]-WARD-v[VERSION]` → Construct using format above
- `[COMMAND]` → "arckit.wardley"

*User-provided fields* (extract from project metadata or user input):

- `[PROJECT_NAME]` → Full project name from project metadata or user input
- `[OWNER_NAME_AND_ROLE]` → Document owner (prompt user if not in metadata)
- `[CLASSIFICATION]` → Default to "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

*Calculated fields*:

- `[YYYY-MM-DD]` for Review Date → Current date + 30 days

*Pending fields* (leave as [PENDING] until manually updated):

- `[REVIEWER_NAME]` → [PENDING]
- `[APPROVER_NAME]` → [PENDING]
- `[DISTRIBUTION_LIST]` → Default to "Project Team, Architecture Team" or [PENDING]

**Populate Revision History**:

```markdown
| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-wardley` command | [PENDING] | [PENDING] |
```

**Populate Generation Metadata Footer**:

The footer should be populated with:

```markdown
**Generated by**: ArcKit `$arckit-wardley` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "claude-sonnet-4-5-20250929"]
**Generation Context**: [Brief note about source documents used]
```

---

### Output Contents

The Wardley Map document must include:

2. **Map Visualization Code**:
   - Complete Wardley Map in OnlineWardleyMaps syntax (primary)
   - URL: https://create.wardleymaps.ai
   - Instructions to paste code into create.wardleymaps.ai
   - Mermaid `wardley-beta` equivalent in collapsible `<details>` block with sourcing decorators (`build`/`buy`/`outsource`/`inertia`)

3. **Component Inventory**:
   - All components with visibility, evolution, stage classification
   - Strategic notes for each component

4. **Evolution Analysis**:
   - Components by evolution stage (Genesis, Custom, Product, Commodity)
   - Strategic recommendations for each stage

5. **Build vs Buy Analysis**:
   - Candidates for building (Genesis/Custom with competitive advantage)
   - Candidates for buying (Product with mature market)
   - Candidates for SaaS/cloud (Commodity)

6. **Inertia and Barriers**:
   - Components with resistance to change
   - Mitigation strategies

7. **Movement and Predictions**:
   - Evolution velocity (12-month, 24-month predictions)
   - Strategic implications

8. **UK Government Context** (if applicable):
   - GOV.UK services mapping
   - Digital Marketplace procurement strategy
   - TCoP compliance mapping

9. **Dependencies and Value Chain**:
   - Component dependency tree
   - Critical path analysis

10. **Risk Analysis**:

- High-risk areas (single vendor, Genesis components)
- Opportunities (commoditization, market gaps)

11. **Recommendations**:
    - Immediate actions (0-3 months)
    - Short-term actions (3-12 months)
    - Long-term strategic actions (12-24 months)

12. **Traceability**:
    - Link to requirements (BR-001, FR-001, etc.)
    - Link to architecture principles
    - Link to UK Government assessments (TCoP, AI Playbook, ATRS)

## Step 6: Integration with ArcKit Workflow

### Before Map Creation

If required artifacts don't exist, recommend creating them first:

```bash
# If no requirements exist
"I recommend running `$arckit-requirements` first to establish requirements before creating a Wardley Map."

# If no architecture principles exist
"I recommend running `$arckit-principles` first to establish architecture principles."
```

### After Map Creation

Recommend next steps based on map insights:

```bash
# If map shows many commodity components
"Based on your Wardley Map, I recommend running `$arckit-sow` to create an RFP for vendor procurement."

# If map shows build vs buy decisions needed
"Your map identifies several build vs buy decisions. Consider running `$arckit-evaluate` to compare vendor options."

# If map shows UK Government project
"As a UK Government project, I recommend running `$arckit-tcop` to assess Technology Code of Practice compliance."

# If map shows AI components with HIGH-RISK
"Your map includes HIGH-RISK AI components. I recommend running `$arckit-ai-playbook` and `$arckit-atrs`."
```

### Integrate with Design Review

When HLD/DLD review is requested, reference the Wardley Map:

```bash
"$arckit-hld-review Review HLD against Wardley Map strategic positioning"
```

The design review should validate:

- Components match their evolution stage (no building commodity components)
- Dependencies align with value chain
- Build vs buy decisions followed
- Inertia factors addressed

### Integrate with Analysis

The `$arckit-analyze` command should include Wardley Map validation:

- ✅ Components correctly positioned by evolution stage
- ✅ Build decisions align with Genesis/Custom stage
- ✅ Buy decisions align with Product/Commodity stage
- ✅ GOV.UK services used where available (UK Government projects)
- ⚠️ High-risk: Building commodity components (waste of investment)
- ⚠️ High-risk: Buying for Genesis needs (no market solutions exist)

## Example: UK Government Benefits Chatbot

**User Request**: "Create a Wardley Map for the DWP Benefits Eligibility Chatbot showing current state and procurement strategy"

**Context**:

- HIGH-RISK AI system (affects access to benefits)
- Must comply with TCoP, AI Playbook, ATRS
- Procurement via G-Cloud Digital Marketplace
- Uses GPT-4 (commercial LLM product)
- Needs human-in-the-loop review

**Wardley Map Code**:

```wardley
title DWP Benefits Eligibility Chatbot - Procurement Strategy

anchor Citizen [0.95, 0.63]
annotation 1 [0.35, 0.25] HIGH-RISK AI - Human oversight mandatory
annotation 2 [0.85, 0.92] Use GOV.UK services - don't build
annotation 3 [0.48, 0.45] Build custom - competitive advantage
note G-Cloud procurement for commodity/product components [0.75, 0.15]

component Citizen [0.95, 0.20]
component Benefits Eligibility Guidance [0.92, 0.25]
component Conversational Interface [0.85, 0.38]
component Human Review Queue [0.82, 0.45]
component GPT-4 LLM Service [0.68, 0.72]
component Benefits Rules Engine [0.65, 0.42]
component Bias Testing Framework [0.62, 0.35]
component GOV.UK Notify [0.55, 0.92]
component GOV.UK Design System [0.72, 0.75]
component Authentication [0.48, 0.68]
component DWP Benefits Database [0.45, 0.52]
component Cloud Hosting AWS [0.28, 0.95]
component PostgreSQL RDS [0.25, 0.92]

Citizen -> Benefits Eligibility Guidance
Benefits Eligibility Guidance -> Conversational Interface
Benefits Eligibility Guidance -> Human Review Queue
Conversational Interface -> GPT-4 LLM Service
Conversational Interface -> Benefits Rules Engine
Human Review Queue -> GOV.UK Notify
Conversational Interface -> GOV.UK Design System
Conversational Interface -> Authentication
Benefits Rules Engine -> DWP Benefits Database
Benefits Rules Engine -> Bias Testing Framework
GPT-4 LLM Service -> Cloud Hosting AWS
DWP Benefits Database -> PostgreSQL RDS
PostgreSQL RDS -> Cloud Hosting AWS

pipeline Benefits Eligibility Guidance [0.92, 0.25, 0.55]

evolve GPT-4 LLM Service 0.85 label Commoditizing fast
evolve Benefits Rules Engine 0.68 label Move to product in 18m

style wardley
```

<details>
<summary>Mermaid Wardley Map</summary>

```mermaid
wardley-beta
title DWP Benefits Eligibility Chatbot - Procurement Strategy
size [1100, 800]

anchor Citizen [0.95, 0.63]

component Benefits Eligibility Guidance [0.92, 0.25] (build)
component Conversational Interface [0.85, 0.38] (build)
component Human Review Queue [0.82, 0.45] (build)
component "GPT-4 LLM Service" [0.68, 0.72] (buy)
component Benefits Rules Engine [0.65, 0.42] (build)
component Bias Testing Framework [0.62, 0.35] (build)
component "GOV.UK Notify" [0.55, 0.92] (buy)
component "GOV.UK Design System" [0.72, 0.75] (buy)
component Authentication [0.48, 0.68] (buy)
component DWP Benefits Database [0.45, 0.52] (build) (inertia)
component Cloud Hosting AWS [0.28, 0.95] (buy)
component PostgreSQL RDS [0.25, 0.92] (buy)

Citizen -> Benefits Eligibility Guidance
Benefits Eligibility Guidance -> Conversational Interface
Benefits Eligibility Guidance -> Human Review Queue
Conversational Interface -> "GPT-4 LLM Service"
Conversational Interface -> Benefits Rules Engine
Human Review Queue -> "GOV.UK Notify"
Conversational Interface -> "GOV.UK Design System"
Conversational Interface -> Authentication
Benefits Rules Engine -> DWP Benefits Database
Benefits Rules Engine -> Bias Testing Framework
"GPT-4 LLM Service" -> Cloud Hosting AWS
DWP Benefits Database -> PostgreSQL RDS
PostgreSQL RDS -> Cloud Hosting AWS

pipeline Benefits Eligibility Guidance {
  component "Text-Based Guidance" [0.25]
  component Conversational AI Guidance [0.55]
}

evolve "GPT-4 LLM Service" 0.85
evolve Benefits Rules Engine 0.68

note "HIGH-RISK AI - Human oversight mandatory" [0.35, 0.25]
note "Use GOV.UK services - do not build" [0.85, 0.92]
note "G-Cloud procurement for commodity/product" [0.75, 0.15]

annotations [0.05, 0.05]
annotation 1,[0.48, 0.45] "Build custom - competitive advantage"
```

</details>

**Strategic Analysis**:

**Build** (Genesis/Custom):

- ✅ Benefits Eligibility Guidance (0.25 - Genesis): Core user need, build custom
- ✅ Conversational Interface (0.38 - Custom): Competitive advantage, build
- ✅ Human Review Queue (0.45 - Custom): Compliance requirement, build
- ✅ Benefits Rules Engine (0.42 - Custom): Domain-specific, strategic IP
- ✅ Bias Testing Framework (0.35 - Custom): HIGH-RISK AI requirement

**Buy - Product** (G-Cloud):

- ✅ GPT-4 LLM Service (0.72 - Product): Commercial LLM via Azure/AWS
- ✅ Authentication (0.68 - Product): Use Auth0 or GOV.UK Verify

**Buy - Commodity** (G-Cloud):

- ✅ Cloud Hosting AWS (0.95 - Commodity): G-Cloud AWS
- ✅ PostgreSQL RDS (0.92 - Commodity): AWS managed database

**Reuse** (GOV.UK Services):

- ✅ GOV.UK Notify (0.92 - Commodity): Email/SMS notifications
- ✅ GOV.UK Design System (0.75 - Product): Frontend components, accessibility

**Procurement Strategy**:

- G-Cloud for: AWS hosting, GPT-4 (via Azure OpenAI), Auth0
- Build in-house: Conversational interface, rules engine, human review queue
- Reuse GOV.UK: Notify, Design System (already available)

**HIGH-RISK AI Requirements**:

- Human Review Queue (Custom, 0.45): Mandatory human-in-the-loop
- Bias Testing Framework (Custom, 0.35): Fairness testing for protected characteristics
- ATRS publication: Required before Live phase
- DPIA + EqIA: Mandatory for HIGH-RISK AI

**Next Steps**:

1. Run `$arckit-sow` to create RFP for G-Cloud procurement (AWS, GPT-4, Auth0)
2. Run `$arckit-ai-playbook` to complete AI Playbook assessment
3. Run `$arckit-atrs` to generate ATRS record
4. Run `$arckit-tcop` to validate TCoP compliance (Cloud First, Open Standards, Reuse)

## Important Notes

### Map Quality Standards

✅ **Good Wardley Maps**:

- All components have clear visibility and evolution positions
- Dependencies flow top-to-bottom (user needs → infrastructure)
- Evolution stages match reality (don't misclassify commodity as Genesis)
- Strategic decisions (build/buy) align with evolution stage
- Inertia factors explicitly identified
- Movement/evolution predictions included
- Traceability to requirements and principles

❌ **Poor Wardley Maps**:

- Arbitrary positioning without rationale
- Missing dependencies
- Building commodity components (waste)
- Buying for Genesis needs (no market exists)
- Ignoring inertia
- Static map with no evolution predictions
- No traceability to requirements

### Common Mistakes to Avoid

2. **Misclassifying Evolution Stage**:
   - ❌ Positioning cloud services as "Custom" (they're Commodity 0.90+)
   - ❌ Positioning novel AI models as "Product" (they're Genesis if truly novel)

3. **Ignoring Dependencies**:
   - ❌ Not mapping component dependencies
   - ❌ Missing critical path components

4. **Wrong Build vs Buy Decisions**:
   - ❌ Building commodity components (e.g., custom auth instead of Auth0)
   - ❌ Buying for Genesis needs (no market solutions exist yet)

5. **UK Government Specific Mistakes**:
   - ❌ Building custom notification service instead of GOV.UK Notify
   - ❌ Not using GOV.UK Design System (accessibility, consistency)
   - ❌ Wrong Digital Marketplace framework for evolution stage

6. **AI Project Mistakes**:
   - ❌ Not mapping human-in-the-loop as mandatory component
   - ❌ Missing bias testing for HIGH-RISK AI
   - ❌ Not flagging ATRS publication requirement

### Map Versioning

- Create versioned maps (v1.0, v1.1, etc.)
- Update maps quarterly or after major decisions
- Track evolution predictions vs actual movement
- Document rationale for all positioning changes

### Visualization

Always remind users:

**"View this map by pasting the code into https://create.wardleymaps.ai"**

The visualization helps:

- Spot strategic patterns
- Identify clustering (areas of focus)
- See evolution trajectories
- Communicate strategy to stakeholders

---

- **Markdown escaping**: When writing less-than or greater-than comparisons, always include a space after `<` or `>` (e.g., `< 3 seconds`, `> 99.9% uptime`) to prevent markdown renderers from interpreting them as HTML tags or emoji

Before writing the file, read `.arckit/references/quality-checklist.md` and verify all **Common Checks** plus the **WARD** per-type checks pass. Fix any failures before proceeding.

## Final Output

Generate a comprehensive Wardley Map document saved to:

**`projects/{project_number}-{project_name}/wardley-maps/ARC-{PROJECT_ID}-WARD-{NUM}-v{VERSION}.md`**

The document must be:

- ✅ Complete with all sections from template
- ✅ Actionable (clear build/buy/rent decisions)
- ✅ Traceable (linked to requirements and principles)
- ✅ Strategic (evolution predictions and gameplay)
- ✅ Compliant (UK Government TCoP, AI Playbook if applicable)

After creating the map, provide a summary to the user:

**Summary Message**:

```text
✅ Wardley Map Created: {map_name}

📁 Location: projects/{project}/wardley-maps/ARC-{PROJECT_ID}-WARD-{NUM}-v{VERSION}.md

🗺️ View Map: Paste the Wardley code into https://create.wardleymaps.ai

📊 Key Insights:
- {insight_1}
- {insight_2}
- {insight_3}

💡 Build vs Buy Recommendations:
- BUILD: {components} (Genesis/Custom with competitive advantage)
- BUY: {components} (Product/Commodity with mature market)
- REUSE: {components} (GOV.UK services)

⚠️ High-Risk Areas:
- {risk_1}
- {risk_2}

🎯 Next Steps:
- {action_1}
- {action_2}
- {action_3}

🔗 Recommended Commands:
- $arckit-sow - Generate RFP for vendor procurement
- $arckit-tcop - Assess Technology Code of Practice compliance
- $arckit-ai-playbook - Assess AI Playbook compliance (if AI components)
```

---

**Remember**: Wardley Mapping is about situational awareness and strategic decision-making. The map quality matters less than the strategic insights and decisions it enables.

## Suggested Next Steps

After completing this command, consider running:

- `$arckit-roadmap` -- Create strategic roadmap from evolution analysis
- `$arckit-strategy` -- Synthesise Wardley insights into architecture strategy
- `$arckit-research` -- Research vendors for Custom-Built components *(when Custom-Built components identified that need market research)*
- `$arckit-wardley.doctrine` -- Assess organizational doctrine maturity
- `$arckit-wardley.gameplay` -- Identify strategic plays from the map
- `$arckit-wardley.climate` -- Assess climatic patterns affecting components