gd-rebalance

Cross-Channel Rebalance Skill

What This Skill Does

Multi-channel brands using GoodDay segment inventory by Channel to prevent oversells. But segmentation can strand units — eCommerce might have excess Available units for a slow SKU while Wholesale has an open Sales Order that can't be fulfilled for that same SKU, or vice versa.

This Skill automates the analysis and drafts virtual Transfer Orders to rebalance inventory across Channels at the same Location. Five sequential steps; each produces a distinct output that feeds the next.

Before You Start

1. Read the shared launch configuration: ../Configuration — Shared.md — schedule, delivery, output shape, Data Source contract (Section 16), failure handling (Section 12).
2. Read this Skill's configuration: ./Configuration - Cross-Channel Rebalance.md — channel pairs, demand-analysis thresholds, reserved-units policy, transfer execution policy, inbound-PO lookback, slack delivery mode.
3. Read the merchant-context overrides (if populated): ../Configuration — Merchant Context.md — Section 1 (Channels), Section 2 (Locations), Section 3 (Slack channel destinations), Section 6 (ignore lists).
4. Apply the Brand Guide: ../🖼️ Brand Guidelines.pdf.

Data Source

This Skill describes the business entities each step needs. The concrete mapping — which production MCP tool, verified query, or CSV column populates each entity — lives in ../MCP Tool Catalog.md. When the GoodDay MCP renames a tool or publishes a new verified query, only the catalog changes; this Skill does not.

Session context (merchant id, today's date, channels, locations) comes from the connected MCP's standard surface — no explicit bootstrap call required.

Entities this Skill needs — look each one up in the catalog:

Step	Entity needed
1 — Wholesale Demand Gaps	Open Wholesale Sales Orders with at least one line item showing uncommitted units > 0; for each, the SO header ship-window dates and Block-level allocation state
1 — SO drill detail	Full SO detail: Blocks, allocation state (isAllocated, allocationDate, inventoryStatus), line items (unitsOrdered, committedUnits, uncommittedUnits, availableUnits, inventoryDisplayStatus)
2 — eCommerce velocity	Trailing-window weekly fulfillment velocity per SKU at the in-scope Location(s)
2 — Channel imbalance scan	SKUs with deficit in one Channel and excess in another (fast first-pass scan)
2 — Inventory positions	Per-SKU rows across all Channels and Locations: On Hand Available, Reserved, Committed, Unsellable, Inbound — used for cross-Channel comparison and $-exposure rendering
3 — Inbound PO coverage	Next inbound PO per flagged SKU with ETA and units; gates transfer recommendations against incoming supply that would cover the gap
4 — Transfer drafting	Mutation: create a virtual Transfer Order (same Location, source Channel → destination Channel), add line items with calculated quantities, leave in draft (per Configuration transfer_mode)
5 — Slack delivery	Post summary via the connected Slack MCP — channel from Merchant Context Section 3

Drill links to created Transfer Orders come from each mutation tool's per-row deep_link field — no separate URL composer needed.

Catalog binding may be partial. If the catalog's current binding for the channel-imbalance, item-velocity, or inventory-valuation entities returns VALIDATION_ERROR: not_found, follow ../Configuration — Shared.md Section 12b: surface a routine-specific notice and do not attempt a fallback.

Workflow Overview

Step 1: Wholesale Demand Gaps     → SKUs where Wholesale needs units it doesn't have
Step 2: eCommerce Stockout Risk   → SKUs where eCommerce is running low based on velocity
Step 3: Cross-Channel Matching    → Pair demand gaps with excess inventory in other Channels
Step 4: Transfer Recommendations  → Recommended Transfers with line-item reasoning
Step 5: Summary & Communication   → Consolidated output + Slack draft

---

Step 1: Wholesale Demand Gaps

Goal: Find open Wholesale Sales Orders where demand exceeds available inventory.

Procedure:

1. Fetch open Wholesale SOs with uncommitted units (catalog entity: "Open Wholesale SOs with uncommitted demand").

2. For each SO returned, fetch full SO detail (catalog entity: "SO drill detail").

3. For each SO Block, classify its state:

   Case A — Block is Allocated: For each line item, compare committedUnits vs unitsOrdered. If uncommittedUnits > 0 or inventoryDisplayStatus is "Needs some" or "Needs all", this SKU has a demand gap.

   Case B — Block is NOT Allocated but Ship Window is approaching: Check the SO's shipAfterDate and shipBeforeDate. If the Ship Window starts within ship_window_proximity_days from Configuration, or has already started/passed, treat this as active demand even though the Block isn't formally allocated. The gap is unitsOrdered − availableUnits (where availableUnits is what's in Wholesale at the origin Location).

   Side recommendation: When a Block is Unallocated and the Ship Window is imminent, note in the output that the user should consider Allocating the Block in the GoodDay UI so commitment visibility becomes explicit. Allocation is a UI-only action.

4. For each demand gap, record: SO number, account, block position, SKU, units ordered, committed, uncommitted, gap, origin Location, ship window start/end.

Output: A list of Wholesale demand gaps by SKU at each Location.

---

Step 2: eCommerce Stockout Risk

Goal: Find eCommerce SKUs projected to stock out within the stockout_horizon_days window.

Procedure:

1. First-pass fast scan: fetch the channel-imbalance entity from the catalog. This returns SKUs with deficit in one Channel and excess in another. Filter to the configured location_ids and channel_pairs. Quick candidate list.

2. For deeper analysis on the candidates, fetch eCommerce velocity over velocity_lookback_weeks from Configuration.

3. For each candidate SKU, fetch current inventory positions across all Channels (catalog entity: "Inventory positions").

4. Calculate days of supply per SKU at the Location:

   daily_velocity = weekly_velocity / 7
   days_of_supply = on_hand_available / daily_velocity
   

   If daily_velocity = 0 or the SKU has no fulfillment history, exclude from stockout projection but note in the "Skipped / Incomplete" section.

5. Flag any SKU where days_of_supply < stockout_horizon_days.

Output: A list of eCommerce stockout risks per SKU per Location.

---

Step 3: Cross-Channel Matching

Goal: For each demand gap from Step 1 and stockout risk from Step 2, find excess inventory in other Channels that could be transferred.

Procedure:

1. For Wholesale demand gaps: Look at inventory positions across all Channels for the same SKU at the same Location. Check eCommerce (and other configured Channels) for Available units.

   Determine "excess" in the source Channel: units Available that are not needed for that Channel's own demand. If velocity data exists, calculate the source Channel's own days-of-supply. Only recommend transferring units that would leave the source Channel with at least stockout_horizon_days of supply.

   If include_reserved_in_available is true in Configuration, include Reserved units in the available pool. Otherwise, exclude them and note any Reserved units in the output.

2. For eCommerce stockout risks: Look at Wholesale (and other configured Channels) for Available units. But don't blindly pull — check whether those units are needed for open Wholesale SOs.

   For each SKU, check: are there open Wholesale SOs at this Location that need this SKU? If yes, calculate Wholesale's "excess" as on_hand_available − sum(unitsOrdered on open SO line items for this SKU). Only the positive remainder is available for transfer to eCommerce.

   If there are Unallocated Wholesale Blocks with Ship Windows within ship_window_proximity_days, treat those ordered units as spoken for, even if not formally committed.

3. Check inbound POs: For each SKU with a gap, fetch the next inbound PO (catalog entity: "Inbound PO coverage").

   • For Wholesale gaps: If a PO Block's ETA is before the SO's Ship Window start, recommend holding. Note: "PO expected to cover this gap before Ship Window."
   • For eCommerce gaps: If a PO Block's ETA is before the projected stockout date, recommend holding.

   If a PO exists but arrives AFTER the critical date, proceed with the Transfer recommendation and note the PO for context. POs with an undefined ETA method do not count as cover.

Output: Matched transfer opportunities with direction (eCom → WS or WS → eCom), source Channel, destination Channel, Location, units to transfer, reason, inbound PO if any, hold recommendation if PO covers.

---

Step 4: Transfer Recommendations

Goal: Present clear, actionable Transfer recommendations with line-item reasoning, and optionally draft Transfer Orders.

Procedure:

Group recommendations into three sections

Section A — Recommended Transfers (Act Now): SKUs where a demand gap exists, no inbound PO will cover it in time, and excess units are available in another Channel.

For each recommendation, include:

• SKU and product name
• Direction: e.g., "eCommerce → Wholesale" or "Wholesale → eCommerce"
• Units to transfer
• Why: reference the specific SO (number, account, ship window) or stockout projection (days of supply, velocity)
• Source availability: how many units are available in the source Channel, and how many will remain after the Transfer
• Confidence context: was the source Channel's own demand considered? Any caveats?

Section B — Approaching (Monitor / Likely Soon): SKUs where a Transfer isn't needed yet but will likely be needed in the coming days:

• Inbound PO expected to cover the gap, but hasn't arrived
• eCommerce velocity trending up but hasn't hit the stockout threshold
• Wholesale Blocks Unallocated but Ship Window approaching
• Brief reason why it didn't trigger and what would change it

Section C — Skipped / Incomplete:

• SKUs with Reserved units excluded (note the count) when include_reserved_in_available = false
• SKUs with no velocity data (no fulfillment history in lookback)
• Data gaps or tool errors encountered
• Wholesale demand based only on open SO commitments (no velocity-based Wholesale forecasting)

Execute Transfers (per Configuration transfer_mode)

For each recommended Transfer in Section A, draft a virtual Transfer Order:

• Origin: source Channel at the in-scope Location
• Destination: destination Channel at the same Location (virtual same-Location, cross-Channel)
• Line items: per recommendation
• Notes: include the rebalance context (SO number, stockout projection, etc.) so the operator and gd-onhand-ops Routine 2 can pick it up

Behavior by transfer_mode:

• recommend — output recommendations only; user creates TOs manually
• draft (default) — draft the Transfer Orders in GoodDay for user review before submit
• execute — draft and immediately submit. Caution: virtual transfers close instantly on submit; there is no approval gate between submit and ledger impact

Catalog binding handles the specific mutation calls. Drill links come from each created TO's per-row deep_link.

Present the created TOs to the user with their numbers and status.

---

Step 5: Summary & Communication

Goal: Produce a consolidated summary and draft a Slack message.

Procedure:

1. Present the summary to the user with all three sections from Step 4, formatted as tables for quick scanning.

2. If the user modified or skipped any recommended Transfers, highlight those changes clearly:

   • Modified: "BLU-TEE-M: Transferred 60 instead of recommended 80 — ⚠️ [user to add context]"
   • Skipped: "GRN-SHORT-M: Transfer recommended but held — ⚠️ [user to add context]"

3. Draft a Slack message for the configured channel (from Merchant Context Section 3) using Slack mrkdwn:

   📦 *Cross-Channel Rebalance — [Location Name] ([Date])*
   
   Ran the OHIO channel rebalancing analysis for [Channel Pair]. Here's what was proposed and what's on the radar.
   
   *Transfers Proposed*
   • [SKU]: [units] [direction] _([reason])_ [modification flag if any]
   
   *On the Radar (Next Few Days)*
   • [SKU]: [brief status and why not yet]
   
   *Skipped / Notes*
   • [Any data gaps or excluded items]
   
   _[slack_footer from config]_
   

   Note: the Slack summary reports what was proposed (drafted for human review), not auto-executed. Even in transfer_mode = "execute", the framing should make clear that the operator is the source of authority on what shipped.

4. Post or present the draft per Configuration slack_mode:

   • draft — show the message to the user and wait for confirmation before posting
   • auto — post immediately after analysis completes

---

Important Caveats to Always Include

1. eCommerce demand is velocity-based, not order-based. Trailing fulfillment velocity is a proxy. Actual demand may differ due to promotions, seasonality, or marketing campaigns not reflected in history.

2. Wholesale demand is based on open SO commitments only. No trailing velocity analysis for Wholesale. Recurring reorder patterns not captured in open SOs are not reflected.

3. Allocation is a UI-only action. This Skill can flag that a Block should be Allocated, but cannot allocate via MCP. Direct the user to the SO detail page in GoodDay.

4. Reserved units are excluded by default. If the merchant's SOP allows pulling from Reserved for cross-Channel rebalancing, toggle include_reserved_in_available in Configuration.

5. Virtual transfers close instantly on submit. There is no approval step between submit and ledger impact in execute mode. Default transfer_mode is draft for safety.

---

Edge Cases

• No velocity data for a SKU: exclude from eCommerce stockout analysis. Note in Skipped section. Common for new or seasonal SKUs.
• SKU exists in only one Channel: no rebalancing possible. Skip silently.
• Available units in source Channel are less than the demand gap: recommend transferring what's available. Note that the Transfer partially covers the gap.
• Multiple SOs competing for the same SKU: when multiple Wholesale SOs need the same SKU, prioritize by Ship Window (soonest first). Note the prioritization in the output.
• Inbound PO with uncertain ETA: if a PO Block's ETA method is undefined, do not count it as inbound cover. Note its existence but recommend the Transfer.