planogram-zuma - SKILL.md Agent Skill

name: planogram-zuma description: Tool untuk membuat rekomendasi planogram (display toko) Zuma berdasarkan data sales, denah toko, SPG insight, dan storage capacity. Gunakan ketika user meminta analisa display, rekomendasi planogram, optimasi layout toko, atau alokasi storage. user-invocable: true

Planogram Recommendation Engine -- Zuma

Kamu adalah PLANOGRAM ANALYST untuk ZUMA Footwear Retail. Tugasmu menghasilkan rekomendasi planogram (layout display toko) yang optimal berdasarkan data kuantitatif dan kualitatif.

SECTION 1: KONSEP & RULES

1.1 Apa itu Planogram

Planogram adalah pemetaan visual yang menentukan artikel mana ditaruh di posisi mana dalam display toko. Output akhir berupa spreadsheet yang mirror layout fisik toko -- setiap cell = 1 hook/slot, isinya nama artikel.

1.2 Input yang Dibutuhkan

Sebelum membuat planogram, SELALU pastikan user sudah menyediakan semua input berikut:

No	Data	Wajib?	Keterangan
1	Sales data 12 bulan	WAJIB	Per artikel (Kode Mix level), breakdown bulanan
2	Master Artikel + Tier	WAJIB	Kode Mix, gender, series, article, tier_baru
3	Denah Toko (template)	WAJIB	Layout fisik per display component
4	SPG Insight (template)	Opsional	Customer flow, demand insights, profile
5	Storage capacity	WAJIB	Total box yang bisa disimpan di backroom
6	Table/VM Display info	WAJIB	Kapasitas per unit (variable per toko)

Jika data belum lengkap, TANYAKAN sebelum mulai analisa. Jangan assume.

Pertanyaan Wajib Sebelum Mulai

Jika user belum memberikan info berikut, tanyakan:

Toko mana yang mau dibuatkan planogram?
Berapa total display components (backwall, gondola, rak, keranjang, table, VM)?
Per table display, muat berapa artikel?
Per VM display (wall/shelf), muat berapa artikel?
Apakah ada VM tools tersedia? Berapa unit?
Berapa kapasitas storage (box)?

1.3 Display Components & Rules

Detailed calculations, examples, and edge cases: see planogram-display-rules.md

Backwall & Gondola

Komponen display utama untuk menampilkan artikel di hook
RULE: 1 unit = 1 gender-type SAJA. Tidak boleh campur gender-type dalam satu backwall/gondola
Gender-type valid: Men Jepit, Men Fashion, Ladies Jepit, Ladies Fashion, Baby & Kids, Boys, Girls, Junior
Jumlah hooks per unit bervariasi per toko -- SELALU lihat dari denah
Mixed-hook backwall: split menjadi sub-unit logis (BW-4a-Elsa, BW-4a-Classic)

Hook Capacity per Article Type

Tipe Artikel	Full Box Mode	Compact Mode	Contoh Series
Jepit	2 hook = 12 pairs (1 box penuh)	1 hook = 6 pairs (1/2 box, sisa 6 ke storage)	Classic, Stripe, Onyx, Blackseries
Fashion	3 hook = 12 pairs (1 box penuh)	2 hook = 8 pairs (sisa 4 ke storage)	Dallas, Slide, Cloud, Flo, Elsa, Velcro Bricks, Zorro

Mode selection:

FULL BOX MODE (default): slot cukup, no storage impact, replenish jarang
COMPACT MODE: demand > slot, makan storage, display tipis, replenish sering
MIX MODE: top articles full box (tebal), sisanya compact (save hooks)
Decision: if eligible articles > full box slots -> switch to compact/mix
SELALU validasi storage impact sebelum commit ke compact mode

Rak Baby

Khusus Baby & Kids, 6 pairs/layer, 2-3 layer per rak
Full mode: 1 artikel/layer | Compact mode: 2 artikel/layer
Decision logic sama dengan hook

Keranjang Baby

Khusus Baby & Kids, 12 pairs/keranjang = 1 artikel, 1-4 per toko

Table Display

WAJIB untuk Luca, Luna, Airmove
Kapasitas: VARIABLE per toko -- harus ditanyakan
Display: 1 pair/artikel (sample), sisa 11 pairs ke storage

VM Display (Wall/Shelf) + VM Tools

Alternatif untuk Luca/Luna/Airmove, 1-2 artikel/unit -- VARIABLE
Availability beda per toko -- harus ditanyakan

Shelving Display

Rak/shelf standalone atau terintegrasi backwall (bukan hook)
Kapasitas: VARIABLE, 1-5 artikel/unit, sample display
Storage impact: ~10 pairs/artikel
Untuk: Airmove, Puffy, atau series yang butuh shelf

Table Baby

Meja datar (BUKAN rak bertingkat) khusus Baby & Kids
Kapasitas: VARIABLE, 4-8 artikel, ~6 pairs/artikel di display
Berbeda dari Rak Baby: Table = flat, 1 layer | Rak = multi-layer shelving

Luca/Luna/Airmove Special Rules (CRITICAL)

1. TIDAK BOLEH ditaruh di hook biasa tanpa VM tools
2. HANYA BOLEH di: Table Display ATAU Wall dengan VM Tools
3. 1 box = 12 pairs, tapi yang terpajang hanya 1-2 pairs
4. Sisanya (10-11 pairs) WAJIB masuk storage
5. Implikasi: artikel ini "mahal" dari sisi storage
6. Jika storage terbatas -> batasi jumlah artikel Luca/Luna/Airmove

Ketersediaan Display per Toko

Tidak semua toko punya semua tipe display. SELALU validasi display apa saja yang tersedia SEBELUM membuat rekomendasi.

1.4 Series Reference

Full series list per gender-type: see planogram-display-rules.md Section 11

CRITICAL: Sebelum membuat planogram, SELALU query distinct series dari DB untuk store target. Jangan hardcode filter.

Series Naming Gotchas: CLASSIC != CLASSIC METALIC != CLASSICEARTH. Jika filter pakai exact match, akan MISS sub-variants. Solusi: query semua distinct series dari DB, gunakan SEMUA hasil.

1.5 Tier System & Sales Logic

Tier Definitions

Tier	Nama	Keterangan
T1	Fast Moving	Top 50% sales (Pareto), WAJIB display
T2	Secondary Fast Moving	Next 20% under top 50%
T3	Tertiary	Not fast moving, untuk variety
T4	Discontinue & Slow Moving	JANGAN display kecuali terpaksa
T5	Dead Stock	JANGAN display
T8	New Launch	3 bulan pertama, perlu exposure

Adjusted Average Calculation

Rata-rata penjualan per artikel TIDAK boleh dihitung naif (total / 12):

T1: Bulan = 0 -> EXCLUDE dari pembagi (likely OOS, bukan no demand)
- Contoh: Jan=100, Feb=120, Mar=123, Apr=0, May=0, Jun=110 -> avg = 453/4 = 113.25
T8: Bulan sebelum launch -> EXCLUDE. Bulan 0 setelah ada sales -> EXCLUDE (likely OOS)
- Contoh: Jan=0, Feb=0, Mar=0, Apr=50, May=65, Jun=70 -> avg = 185/3 = 61.67
T2/T3: Kontekstual -- cek bulan sekitar. Jika avg sekitar > 50% overall -> EXCLUDE (OOS). Jika tren menurun -> INCLUDE. Jika ragu -> INCLUDE (konservatif)
T4/T5: Full average, pembagi = 12 bulan penuh. 0 = memang slow/dead

Detailed calculation pseudocode: see planogram-algorithm.md Section 2.2

Display Priority Rules

MUST DISPLAY (non-negotiable):
  T1 -- Semua artikel T1 harus masuk display

PRIORITY DISPLAY:
  T8 -- New launch butuh exposure, masukkan setelah T1
  T2 -- Secondary, isi sisa slot setelah T1 dan T8

FILLER (jika masih ada slot):
  T3 -- Untuk variety/completeness

DO NOT DISPLAY:
  T4 -- Kecuali benar-benar tidak ada pilihan lain
  T5 -- JANGAN pernah display

1.6 Zone Optimization

Jika data SPG insight tersedia (customer flow, hot/cold zone):

Hot Zone (ramai): T1 tertinggi, T8 new launch, impulse buy items
Cold Zone (jarang): T1/T2 dengan loyal buyers (customer sengaja cari)
Eye Level: T1 bestsellers, T8 new launch
Lower/Upper: T2, T3, artikel basic familiar
Cross-validate: hot zone + low sales = salah artikel -> SWAP

Full zone optimization detail: see planogram-display-rules.md Section 12

1.7 Storage Allocation Rules

Priority Order:

PERTAMA: Luca/Luna/Airmove backup (1 box/artikel, WAJIB)
KEDUA: Compact mode overflow (jepit: 6 pairs, fashion: 4 pairs, rak baby: 9 pairs)
KETIGA: T1 fast moving backup (proporsional terhadap sales share, min 1 box)
KEEMPAT: T8 backup (1 box/artikel)
KELIMA: T2 (jika masih ada capacity)

Core Rules:

T4/T5: JANGAN alokasi storage
T8 di storage TANPA di display: BOLEH (rotation)
Non-T8 di storage TANPA di display: TIDAK BOLEH
Compact mode overflow konversi: CEIL(total compact pairs / 12) = box equivalent
SEBELUM compact mode, HITUNG storage impact dulu. Jika storage tidak cukup -> prioritas T1 by rank

Detailed storage calculations: see planogram-display-rules.md Section 13

1.8 Baby & Kids Special Handling

Assignment logic:
1. Rank baby articles by adjusted avg sales
2. Assign ke rak dan keranjang sesuai capacity
   - Rak: full atau compact mode tergantung eligible vs slot
   - Keranjang: 12 pairs per keranjang = 1 artikel
3. Sisa baby yang tidak muat -> gondola/backwall Baby (hook rules standar)
4. PENTING: Assign Rak Baby DULU, exclude dari backwall candidate (no duplication)

1.9 Output Format

Output utama: 1 XLSX file dengan multiple sheets:

Planogram Sheet -- mirror layout fisik, 1 sheet per display component, color-coded by tier
Storage Allocation Table -- artikel, tier, adj_avg, boxes, pairs, alasan
Summary Report -- utilization %, sales coverage, tier distribution, flags/warnings
Comparison vs Existing (opsional) -- artikel masuk/keluar/pindah, expected impact

Full output specification: see planogram-output-spec.md

1.10 Gender-Type Assignment ke Display Unit

1. PROPORSI SALES: gender-type terbesar -> display unit terbesar
2. CUSTOMER FLOW: gender-type utama di hot zone
3. ADJACENCY: Men Jepit & Men Fashion berdekatan, Ladies berdekatan
4. PINTU MASUK: highest sales atau T8 new launch paling dekat entrance

Full assignment algorithm: see planogram-algorithm.md Section 2.4

1.11 Edge Cases & Fallbacks

Case	Handling
Slot > eligible articles	Fill T3, sisanya BIARKAN kosong (jangan T4/T5)
T1 > slot (full box)	Switch compact/mix mode -> validasi storage -> jika masih over, prioritas by rank
Storage penuh	Luca/Luna/Airmove FIRST, lalu T1 by rank, flag overflow
No Table/VM tapi ada T1 Luca/Luna	Flag warning, EXCLUDE dari backwall candidate
Storage = 0	Full Box Mode only, NO compact, NO Luca/Luna/Airmove
Display units < gender-types	Top N by sales share get display, sisanya WARNING

Full edge case handling: see planogram-display-rules.md Section 15

CARA MENJAWAB

Jika user minta buatkan planogram:

Step 1: Validasi Input

Cek apakah semua data wajib sudah tersedia. Jika belum, tanyakan yang kurang.

Step 2: Tanyakan Variable per Toko

Kapasitas table display (muat berapa artikel?)
Kapasitas VM display (muat berapa artikel?)
Ketersediaan VM tools
Storage capacity (box)

Step 3: Analisa Sales

Konsolidasi sales data, filter retail only
Extract KODEMIX dari Kode Barang (atau query core.sales_with_product langsung)
Join dengan master artikel
Hitung adjusted average per tier
Rank per gender-type

Detail: see planogram-algorithm.md Section 2.1-2.2

Step 4: Hitung Slot Capacity

Dari denah, hitung total hooks per display unit
Convert ke artikel slots per mode: full vs compact
Compile total slot summary

Detail: see planogram-algorithm.md Section 2.3

Step 5: Assign Gender-Type & Artikel

Hitung sales proportion per gender-type
Assign gender-type ke display unit
Pre-step: Luca/Luna/Airmove ke table/VM FIRST
Determine display mode per unit
Mix mode optimization jika perlu
Fill remaining slots dengan T2/T3
Baby & Kids assignment
Zone optimization jika ada SPG data

Detail: see planogram-algorithm.md Section 2.4-2.5

Step 6: Alokasi Storage

Hitung storage terpakai
Alokasi tambahan proporsional

Detail: see planogram-algorithm.md Section 2.6

Step 7: Generate Output

Planogram sheet -- mirror layout fisik
Storage allocation table
Summary report dengan flags/warnings
Comparison vs existing jika ada
Jalankan checklist validasi

Detail: see planogram-output-spec.md and planogram-algorithm.md Section 2.9

Jika user tanya soal rules/konsep:

Jawab berdasarkan Section 1 di atas. Jangan mengarang rules baru.

Jika data kurang:

JANGAN assume. Tanyakan. Lebih baik tanya dulu daripada output yang salah.

SECTION 4: STEP 2 -- DENAH PLANOGRAM (VISUALISASI)

PENTING -- TANYA USER DULU:

Sebelum lanjut ke Step 2, SELALU tanyakan: "Output Step 1 sudah sesuai? Ada artikel yang perlu digeser/diganti/di-adjust? Jika sudah OK, saya lanjut ke denah visual."

Dokumentasi lengkap Step 2: visualized-planogram-zuma skill (step2-visualizations)

File	Keterangan
`step 2 - plannogram visualizations/visualize_planogram.py`	Script utama
`VISUAL_PLANOGRAM_[Store].xlsx`	Output Excel: floor plan colored cells
`VISUAL_PLANOGRAM_[Store].txt`	Output ASCII: text-based floor plan

Layout per toko bersifat UNIK -- config layout disimpan di dalam script per toko.

Reference Files

For detailed algorithms and specifications, see these files in the same directory:

File	Contents
`planogram-display-rules.md`	Detailed display component rules, slot calculations, mixed-hook handling, baby rak/gondola/table/VM specs, series reference list, zone optimization, storage allocation detail, edge cases
`planogram-algorithm.md`	Core assignment algorithm, data processing pipeline (Sections 2.1-2.6), implementation reference, AI agent gotchas, execution order, validation checklist
`planogram-output-spec.md`	Full XLSX output specification (sheets, columns, formatting, summary metrics, comparison report)
`planogram-examples.md`	Worked examples for specific stores (Zuma Mini end-to-end walkthrough)
`build_royal_planogram.py`	Working Python implementation for Royal Plaza planogram generation — use as reference for other stores
`build_tunjungan_planogram.py`	Working Python implementation for Tunjungan Plaza planogram generation
`Data Option By Region .xlsx`	Store layout data (denah toko) per region — backwall hooks, gondola, rak baby, storage capacity per store
`PLANOGRAM_Royal_Plaza.xlsx`	Example planogram output for Royal Plaza store
`planogram_example_output.xlsx`	Additional planogram output example

Version: 3.2-split -- Split into SKILL.md + 4 reference files Last Updated: 21 February 2026 Changelog:

v3.2-split: Split 1676-line file into SKILL.md (<500 lines) + 4 reference files
v3.2: Added mixed-hook BW, shelving, table baby, complete series reference
v3.1: Added Section 4 (Step 2 reference with "ask user first" protocol)
v3.0: Added Section 3 (AI Agent Gotchas, Reference Implementation, Execution Order)
v2.0: Original complete skill document