Supply Chain Forecast Diagnosis — Claude Skill

A Claude custom skill that analyzes finished-goods quantity forecast vs actuals data for supply chain and operations teams. Upload a CSV or Excel file and get a full diagnostic report: operational WMAPE, demand-only WMAPE reconciliation, forecast variance, FVA, ABC segmentation, ADI/CV² demand patterns with confidence, denominator coverage, preflight validation, charts, and a formatted Excel workbook with a prioritized actions worklist.

---

What it does

1. Loads your data — CSV or Excel, flexible column naming
2. Applies optional exclusions — exclude_flag, exclude_reason, or --exclude-months for known disruptions/outliers
3. Computes core metrics — operational Detail-Level WMAPE, Demand-Only WMAPE, Forecast Accuracy, Forecast Variance %, and FVA (if planner forecast data is present)
4. Segments SKUs — ABC tiering by actual volume and ADI/CV² demand-pattern classification with confidence
5. Location and area breakdowns — per-branch/location and per-region WMAPE when those optional columns exist
6. Exports supply_chain_forecast_diagnosis_report.xlsx with these sheets:
   • Executive Narrative (plain-English findings and top actions)
   • Executive Summary (metrics, status flags, and charts)
   • Preflight Validation (column mappings, grain detection, warnings)
   • Coverage Diagnostics (zero-actual and denominator checks)
   • Monthly Summary and SKU Month Detail
   • SKU Detail and Actions
   • Location Breakdown (if location/branch column present)
   • Area Breakdown (if area/region column present)
   • How to Read This and Methodology
7. Delivers a narrative summary with root-cause analysis and top priorities

---

Required input columns

Column	Required	Description
sku	Yes	SKU or stock code identifier
date	Yes	Any common date format (2025-01-01, Jan 2025, 01/01/2025)
forecast_qty	Yes	Statistical or system forecast quantity
actual_qty	Yes	Actual demand / invoiced quantity
description	No	SKU name or description
product_class	No	Product category or class
location	No	Branch, warehouse, site, depot, or operating location
area	No	Region, state, territory, province, or market
final_forecast_qty	No	Planner's final forecast quantity (enables FVA calculation)
exclude_flag	No	Mark known disruptions/outliers to exclude before metrics run
exclude_reason	No	Audit note explaining why a row was excluded

Flexible column naming — the skill performs exact and conservative fuzzy mapping for common aliases such as stock_code, item, region, state, branch, warehouse, forecast, actual, sales_qty, units_sold, planner_qty, and final_qty. All mappings are written to the Preflight Validation sheet.

---

How to install

Option A — Download from Releases (easiest)

1. Go to the Releases page and download supply-chain-forecast-diagnosis.zip
2. Go to claude.ai → Settings → Custom Skills → Add Skill
3. Upload the ZIP

Do not use the green Code → Download ZIP button — GitHub wraps the files in a -main folder that breaks the upload.

Option B — Clone and zip

git clone https://github.com/ESFlow97/supply-chain-forecast-diagnosis.git
cd ..
zip -r supply-chain-forecast-diagnosis.zip supply-chain-forecast-diagnosis/

Then upload supply-chain-forecast-diagnosis.zip via claude.ai → Settings → Custom Skills.

Requirements

• Claude Pro, Max, Team, or Enterprise plan
• Code execution must be enabled in your Claude settings
• Python packages (pandas, numpy, openpyxl) are installed automatically on first run

---

How to use

Once the skill is installed, start a new Claude conversation and either:

• Type /supply-chain-forecast-diagnosis
• Or just describe what you want: "I want to diagnose my forecast accuracy" — Claude will invoke the skill automatically

Claude will ask for your industry (for macro context) and whether you have data ready. If you need a template, it will generate one. Upload your CSV or Excel file and the skill runs the full analysis.

---

Example output

Console summary:

-- Preflight Validation --------------------------------------------------
  Source file:       forecast_actuals.xlsx
  Rows / columns:    1,240 / 8
  Detected grain:    monthly
  Column mappings:   Item->sku, Month->date, Forecast->forecast_qty, Actual->actual_qty

Loaded 1,240 rows | 87 SKUs | 12 months
Locations: ['Calgary Branch', 'Toronto Branch', 'Vancouver Branch']
Areas: ['AB', 'BC', 'ON', 'QC']

-- Core Metrics ----------------------------------------------------------
Detail-Level WMAPE:       24.3%
Supply Chain Accuracy:    75.7%
Demand-Only WMAPE:        19.8%
Finance/Sales Accuracy:   91.9%
Forecast Variance %:      -8.1%  (under-forecasting)
Under-Forecast Qty:       4,820
Over-Forecast Qty:        2,310
FVA (planner-touched rows only): +3.2pp  (planner forecast HELPED)

-- ABC Segmentation ------------------------------------------------------
  Tier A: 18 SKUs
  Tier B: 26 SKUs
  Tier C: 43 SKUs

Excel report — an executive narrative sheet, preflight checks, charts, coverage diagnostics, monthly detail, SKU/location detail when available, sorted action items, glossary-style reading guidance, and methodology notes embedded directly in the workbook.

---

Data privacy

Your data never leaves your machine (unless your Claude environment is configured to store conversation history). The scripts run entirely within Claude's code execution sandbox.

• Do not upload files containing personally identifiable information (PII)
• Do not upload confidential pricing, margin, customer, inventory, or supplier data unless you understand your organization's Claude data handling policy
• If you are on a Team or Enterprise Claude plan, check your admin's data retention settings before uploading sensitive files

---

Metric definitions

Full formula definitions and rationale are in reference/metrics.md, including:

• Why WMAPE uses actuals (not forecast) as the denominator
• How FVA is scoped to planner-touched rows only
• Detail-Level WMAPE vs Group-Level Monthly WMAPE
• Demand-Only WMAPE as a secondary reconciliation view, not the headline KPI
• Finance/Sales Accuracy = 100% - ABS(Forecast Variance %)
• ABC classification by finished-goods quantity
• ADI/CV² demand-pattern classification using a complete SKU × month grid, plus confidence
• Optional location handling and exclusion audit rules
• Why the skill does not calculate safety stock, reorder points, inventory excess, or stockouts without inventory/on-hand, lead-time, and service-level data

---

License

Apache 2.0 — free to use, modify, and distribute. Copyright 2026 Flowmatic AI Inc. Attribution required; derivatives must state changes.