Skip to content

Assessment Scoring Engine

UCMI Engine | Command-line tool for computing the Unified Commerce Maturity Index from a retailer assessment profile
Classification: tool · Script: scripts/assess.py

Overview

The UC-BoK Assessment Engine takes a structured assessment profile (a YAML file scoring a retailer's current capability maturity) and produces:

  1. UCMI score (0.0–4.0) — the Unified Commerce Maturity Index
  2. Critical gap list — capabilities below the RA MVP threshold, weighted by strategic importance
  3. Important gap list — secondary priority gaps
  4. Strengths — capabilities already at or above MVP level
  5. Full scorecard — all capabilities sorted by priority and gap

The engine is RA-aware: gap analysis is performed against the selected Reference Architecture baseline (RA-001, RA-002, or RA-003), so maturity thresholds reflect the specific priorities of that vertical.

Quick Start

# Terminal report (colour output)
python3 scripts/assess.py --profile catalogs/assessment-profiles/acme-electronics-2026.yaml

# JSON output (for downstream tooling / dashboards)
python3 scripts/assess.py --profile <profile> --output json

# Markdown report (for export to docs or Confluence)
python3 scripts/assess.py --profile <profile> --output markdown

# List available profiles
python3 scripts/assess.py --list-profiles

UCMI Formula

UCMI = Σ(capability_score × priority_weight) / Σ(priority_weight)

Priority Weights

Priority Weight When Applied
critical 3× RA-critical capabilities not meeting MVP threshold drive score down proportionally more
important 2× RA-important capabilities contribute at double the standard weight
standard 1× Baseline weight for standard capabilities

Maturity Levels

Level Label Definition
0 Absent Capability does not exist
1 Ad hoc Single channel, manual, inconsistent
2 Fragmented Multi-system, partial automation, not unified
3 Integrated Cross-channel, automated, consistently applied
4 Optimised Real-time, data-driven, continuously improving

UCMI Bands

Band UCMI Interpretation
⛔ 0.0 – 1.0 Not Started — foundational investment required
🟥 1.0 – 2.0 Fragmented — critical capability gaps present
🟧 2.0 – 2.5 Developing — core unified commerce partially in place
🟨 2.5 – 3.0 Integrated — multi-channel unified, optimisation gaps remain
🟩 3.0 – 3.5 Advanced — strong unified commerce foundation
🟦 3.5 – 4.0 Optimised — best-in-class unified commerce

Gap Identification Rules

Condition Classification
priority = critical AND current-level < 3 🔴 Critical Gap
priority = important AND current-level < 2 🟠 Important Gap
priority = critical/important AND current-level ≥ MVP ✅ Strength

Assessment Profile Format

Assessment profiles are YAML files in catalogs/assessment-profiles/. They are validated against schemas/assessment-profile.schema.json.

id: acme-electronics-2026
retailer: Acme Electronics
vertical: Specialty Retail
ra-baseline: RA-003
assessed-by: UC-BoK Assessment Team
assessment-date: "2026-07-05"
notes: >
  Optional free-text context about the retailer and assessment scope.

capabilities:
  - capability: clienteling
    current-level: 1          # 0–4
    evidence: "No CRM at POS" # optional — supports the score
    target-level: 3           # optional — 12-month target
  - capability: checkout
    current-level: 2
  # ... one entry per capability

Required fields per capability entry: capability, current-level
Optional: evidence (supports peer review), target-level (roadmap planning)

Assessment Output — Acme Electronics vs RA-003 Specialty Retail

``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ UC-BoK UNIFIED COMMERCE MATURITY ASSESSMENT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Retailer : Acme Electronics Vertical : Specialty Retail RA Baseline : RA-003

UCMI Score [████████████░░░░░░░░░░░░░░░░░░] 1.65/4.00 (41%) 🟥 Fragmented — Critical capability gaps present

🔴 Critical Gaps (RA MVP not met — immediate priority) 🟥 clienteling current: 1 mvp: 3 gap: -2 🟥 customer-profile current: 1 mvp: 3 gap: -2 🟧 basket-management current: 2 mvp: 3 gap: -1 ...

🟠 Important Gaps (below MVP threshold — next priority) ⬜ subscription-management current: 0 mvp: 2 gap: -2 🟥 order-orchestration current: 1 mvp: 2 gap: -1 ...

✅ Strengths 🟨 payment-processing level: 3 [critical]

UCMI = 1.65 / 4.00 Critical gaps: 9 Important gaps: 6 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 

---

## Available Profiles

| Profile ID | Retailer | Vertical | RA | Date |
|---|---|---|---|---|
| `acme-electronics-2026` | Acme Electronics *(example)* | Specialty Retail | RA-003 | 2026-07-05 |

---

## Creating a New Profile

1. Copy an existing profile from `catalogs/assessment-profiles/`
2. Update `id`, `retailer`, `vertical`, `ra-baseline`, `assessed-by`, `assessment-date`
3. Score each capability (0–4) using the maturity level definitions
4. Add `evidence` notes to support the score (recommended for consultant use)
5. Run the engine to validate the output

```bash
python3 scripts/assess.py --profile catalogs/assessment-profiles/<your-profile>.yaml

Integration with the Knowledge Graph

The Assessment Engine is standalone. Future integration with the Knowledge Graph will enable:

  • Cross-capability impact analysis: "If I fix clienteling, which processes unlock?"
  • RA gap-to-journey mapping: "Which journeys are blocked by my critical gaps?"
  • Vendor recommendation: "Which vendors cover my top 3 critical gaps for RA-003?"