Common questions
What does this skill do? + −
It scans a Shopify product CSV for inconsistent option values (color aliases, size label variants, case issues), fixes them, reorders size sequences, flags duplicates and missing images, and returns a corrected CSV plus a change log.
What input does it need? + −
A Shopify product export CSV. Upload the file directly. The skill works with partial exports (a subset of products).
Will it change my SKUs or prices? + −
No. The skill only modifies Option Name and Option Value columns plus variant row ordering. SKUs, prices, inventory, and all other fields are preserved exactly.
What if I disagree with a proposed canonical value? + −
The skill presents its normalization plan before writing output and asks for confirmation on any ambiguous cases. You can override any proposed canonical value before the corrected CSV is produced.
Example skill output + −
Example Output: SummitGear Co. Variant Normalization
This example demonstrates the full output of the Normalize and Repair Variant Options skill using fictional data from SummitGear Co., an outdoor apparel brand.
The audit is generated by running the deterministic Python script first, then interpreting its JSON output. Structural issues (whitespace, case, duplicates, missing images, size ordering) come from the script. Semantic issues (alias reasoning, brand voice alignment) come from LLM analysis on top of the script results.
Turn 1: Audit Report
The script ran successfully:
python3 scripts/normalize_audit.py summitgear-products.csv --assets-dir assets/
{
"metadata": {
"products_scanned": 4,
"variants_scanned": 22,
"total_issues_found": 11,
"has_variant_image_column": true,
"csv_encoding": "utf-8-sig",
"bom_detected": false
}
}
The script detected all 11 issues, including both alias pairs (Grey/Gray via the color alias map, XL/Extra Large via the size alias map).
Variant Option Audit
Products scanned: 4 Variants scanned: 22 Issues found: 11
1. Option Value Aliases
| Values Found | Products Affected | Suggested Canonical Value |
|---|---|---|
| Grey, Gray | alpine-wind-jacket, ridgeline-fleece | Gray (US English standard) |
| XL, Extra Large | ridgeline-fleece | XL |
2. Case Inconsistencies
| Values Found | Suggested Canonical Value | Products Affected |
|---|---|---|
| NAVY, Navy, navy | Navy | alpine-wind-jacket, basecamp-tee |
3. Whitespace Issues
| Field | Value | Product Handle |
|---|---|---|
| Option2 Value | "Stone " (trailing space) | basecamp-tee |
| Option1 Value | " M" (leading space) | ridgeline-fleece |
4. Size Sequence Issues
| Product Handle | Current Order | Expected Order |
|---|---|---|
| basecamp-tee | L, S, M, XL | S, M, L, XL |
5. Duplicate Variants
| Product Handle | Option Combination | SKUs | Note |
|---|---|---|---|
| alpine-wind-jacket | M / Navy | SG-101-M-NAV, SG-101-M-NAV-2 | Same options, same price ($139.00) |
6. Missing Variant Images
| Product Handle | SKU | Option Values |
|---|---|---|
| ridgeline-fleece | SG-102-L-GRY | L / Grey |
| ridgeline-fleece | SG-102-XL-GRY | XL / Grey |
7. Option Name Inconsistencies
| Option Names Found | Products Using Each | Suggested Canonical Name |
|---|---|---|
| Color (3 products), Colour (1 product) | Colour: trail-shorts. Color: all others | Color |
8. Handle/Title Drift
No issues found.
Turn 2: Normalization Plan
Based on the audit, here is the proposed normalization plan:
Canonical value mapping:
| Original Value | Canonical Value | Reason |
|---|---|---|
| Grey | Gray | US English standard |
| Extra Large | XL | Consistent with other products |
| NAVY | Navy | Title case standard |
| navy | Navy | Title case standard |
| "Stone " | "Stone" | Trailing whitespace removed |
| " M" | "M" | Leading whitespace removed |
| Colour | Color | Matches 3 of 4 products |
Choices needed from you:
- Grey vs Gray: I defaulted to "Gray" (US English). Would you prefer "Grey" (UK English)?
- Duplicate M/Navy on alpine-wind-jacket: Both rows have the same price ($139.00). Should I remove the second row (SG-101-M-NAV-2) or keep both?
Size reordering:
- basecamp-tee: L, S, M, XL will become S, M, L, XL
Turn 3: Output
Assuming the merchant confirmed defaults and chose to remove the duplicate.
Corrected CSV
Handle,Title,Body (HTML),Vendor,Option1 Name,Option1 Value,Option2 Name,Option2 Value,Variant SKU,Variant Price,Variant Image
alpine-wind-jacket,Alpine Wind Jacket,<p>Lightweight wind protection.</p>,SummitGear Co.,Size,S,Color,Gray,SG-101-S-GRY,139.00,https://cdn.summitgear.co/alpine-wind-s-gray.jpg
alpine-wind-jacket,,,,Size,S,Color,Navy,SG-101-S-NAV,139.00,https://cdn.summitgear.co/alpine-wind-s-navy.jpg
alpine-wind-jacket,,,,Size,M,Color,Gray,SG-101-M-GRY,139.00,https://cdn.summitgear.co/alpine-wind-m-gray.jpg
alpine-wind-jacket,,,,Size,M,Color,Navy,SG-101-M-NAV,139.00,https://cdn.summitgear.co/alpine-wind-m-navy.jpg
alpine-wind-jacket,,,,Size,L,Color,Gray,SG-101-L-GRY,139.00,https://cdn.summitgear.co/alpine-wind-l-gray.jpg
alpine-wind-jacket,,,,Size,L,Color,Navy,SG-101-L-NAV,139.00,https://cdn.summitgear.co/alpine-wind-l-navy.jpg
ridgeline-fleece,Ridgeline Fleece,<p>Midweight fleece pullover.</p>,SummitGear Co.,Size,S,Color,Gray,SG-102-S-GRY,89.00,https://cdn.summitgear.co/ridgeline-s-gray.jpg
ridgeline-fleece,,,,Size,M,Color,Gray,SG-102-M-GRY,89.00,https://cdn.summitgear.co/ridgeline-m-gray.jpg
ridgeline-fleece,,,,Size,L,Color,Gray,SG-102-L-GRY,89.00,
ridgeline-fleece,,,,Size,XL,Color,Gray,SG-102-XL-GRY,89.00,
basecamp-tee,Basecamp Tee,<p>Everyday trail tee.</p>,SummitGear Co.,Size,S,Color,Navy,SG-103-S-NAV,35.00,https://cdn.summitgear.co/basecamp-s-navy.jpg
basecamp-tee,,,,Size,S,Color,Stone,SG-103-S-STN,35.00,https://cdn.summitgear.co/basecamp-s-stone.jpg
basecamp-tee,,,,Size,M,Color,Navy,SG-103-M-NAV,35.00,https://cdn.summitgear.co/basecamp-m-navy.jpg
basecamp-tee,,,,Size,M,Color,Stone,SG-103-M-STN,35.00,https://cdn.summitgear.co/basecamp-m-stone.jpg
basecamp-tee,,,,Size,L,Color,Navy,SG-103-L-NAV,35.00,https://cdn.summitgear.co/basecamp-l-navy.jpg
basecamp-tee,,,,Size,L,Color,Stone,SG-103-L-STN,35.00,https://cdn.summitgear.co/basecamp-l-stone.jpg
basecamp-tee,,,,Size,XL,Color,Navy,SG-103-XL-NAV,35.00,https://cdn.summitgear.co/basecamp-xl-navy.jpg
basecamp-tee,,,,Size,XL,Color,Stone,SG-103-XL-STN,35.00,https://cdn.summitgear.co/basecamp-xl-stone.jpg
trail-shorts,Trail Shorts,<p>Quick-dry hiking shorts.</p>,SummitGear Co.,Size,M,Color,Olive,SG-104-M-OLV,55.00,https://cdn.summitgear.co/trail-shorts-m-olive.jpg
trail-shorts,,,,Size,L,Color,Olive,SG-104-L-OLV,55.00,https://cdn.summitgear.co/trail-shorts-l-olive.jpg
trail-shorts,,,,Size,XL,Color,Olive,SG-104-XL-OLV,55.00,https://cdn.summitgear.co/trail-shorts-xl-olive.jpg
Note: The above CSV is simplified for readability. The actual output preserves all 51 columns from the original Shopify export.
Change Log
# Variant Normalization Change Log
**Source file:** summitgear-products.csv
**Products scanned:** 4
**Variants scanned:** 22
**Total changes made:** 11
---
## Canonical Option Values Established
| Original Value | Canonical Value | Products Affected | Reason |
|---|---|---|---|
| Grey | Gray | alpine-wind-jacket, ridgeline-fleece | US English standard (merchant confirmed) |
| Extra Large | XL | ridgeline-fleece | Consistent with abbreviated form used across catalog |
| NAVY | Navy | alpine-wind-jacket | Title case normalization |
| navy | Navy | basecamp-tee | Title case normalization |
| Colour | Color | trail-shorts | Matches 3 of 4 products in catalog |
## Issues Fixed
### Option Value Aliases Merged
- **Grey to Gray:** 4 variants across alpine-wind-jacket and ridgeline-fleece updated. All instances of "Grey" replaced with "Gray."
- **Extra Large to XL:** 2 variants on ridgeline-fleece updated. "Extra Large" replaced with "XL" to match catalog standard.
### Case Normalized
- **NAVY to Navy:** 2 variants on alpine-wind-jacket updated.
- **navy to Navy:** 2 variants on basecamp-tee updated.
### Whitespace Removed
- **"Stone " to "Stone":** 4 variants on basecamp-tee. Trailing space removed.
- **" M" to "M":** 1 variant on ridgeline-fleece. Leading space removed.
### Size Order Corrected
| Product Handle | Previous Order | Corrected Order |
|---|---|---|
| basecamp-tee | L, S, M, XL | S, M, L, XL |
### Duplicate Variants Flagged
| Product Handle | Option Combination | SKUs | Action Taken |
|---|---|---|---|
| alpine-wind-jacket | M / Navy | SG-101-M-NAV, SG-101-M-NAV-2 | Removed SG-101-M-NAV-2 (merchant confirmed) |
### Missing Variant Images Flagged
| Product Handle | SKU | Option Values | Note |
|---|---|---|---|
| ridgeline-fleece | SG-102-L-GRY | L / Gray | No variant image. Other variants on this product have images. |
| ridgeline-fleece | SG-102-XL-GRY | XL / Gray | No variant image. Other variants on this product have images. |
### Option Names Standardized
- **Colour to Color:** All variants on trail-shorts updated. "Colour" replaced with "Color" to match the other 3 products in the file.
---
## Skipped / Needs Review
- **Missing variant images on ridgeline-fleece:** The skill cannot generate image URLs. The merchant should upload images for L/Gray and XL/Gray variants and add the URLs to the Variant Image column before importing.