Demand Forecast Reorder

Purpose

Forecasts future demand for each SKU based on historical sales velocity, trend analysis, and optional seasonality adjustments. Calculates reorder points (when to order) and suggested reorder quantities (how much to order) factoring in vendor lead times and safety stock. Read-only — no mutations.

Prerequisites

Parameters

Safety

> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

Inputs: query: "created_at:>=''", first: 250, select createdAt, lineItems { variant { id }, quantity }, pagination cursor

Expected output: All orders with line items for sales velocity calculation

Inputs: All variant IDs with sales history, first: 250, pagination cursor

Expected output: Variant details (SKU, title, product title, vendor)

Inputs: Inventory item IDs for stocked variants

Expected output: Current available quantities per location

GraphQL Operations

# orders:query — validated against api_version 2025-01
query SalesHistory($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        createdAt
        lineItems(first: 50) {
          edges {
            node {
              quantity
              variant { id }
            }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# productVariants:query — validated against api_version 2025-01
query VariantInfo($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on ProductVariant {
      id
      sku
      title
      product { id title vendor }
      inventoryQuantity
      inventoryItem { id }
    }
  }
}

# inventoryItems:query — validated against api_version 2025-01
query InventoryItemDetails($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on InventoryItem {
      id
      unitCost { amount currencyCode }
      tracked
      inventoryLevels(first: 10) {
        edges {
          node {
            quantities(names: ["available"]) {
              name
              quantity
            }
            location { id name }
          }
        }
      }
    }
  }
}

# inventoryLevels:query — validated against api_version 2025-01
query LocationInventory($locationId: ID!, $after: String) {
  location(id: $locationId) {
    inventoryLevels(first: 250, after: $after) {
      edges {
        node {
          quantities(names: ["available"]) { name quantity }
          item { id variant { id sku product { title } } }
        }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Demand Forecast & Reorder Planner    ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
DEMAND FORECAST & REORDER PLAN  (<days_back>d history → <forecast_days>d forecast)
  SKUs analyzed:       <n>
  Avg daily velocity:  <n> units/day
  ─────────────────────────────
  ⚠️  URGENT (stockout <7 days):
    "<product>" SKU:<sku>  Stock:<n>  Days left:<n>  ORDER BY: <date>
    Reorder qty: <n> units  Est. cost: $<n>

  ⏰ PLAN AHEAD (stockout 7-30 days):
    "<product>" SKU:<sku>  Stock:<n>  Days left:<n>  ORDER BY: <date>

  ✅ HEALTHY (>30 days stock):
    <n> SKUs with adequate stock

  Output: reorder_plan_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "demand-forecast-reorder",
  "store": "<domain>",
  "history_days": 90,
  "forecast_days": 30,
  "lead_time_days": 14,
  "skus_analyzed": 0,
  "urgent_reorders": [],
  "planned_reorders": [],
  "healthy_skus": 0,
  "output_file": "reorder_plan_<date>.csv"
}

Output Format

CSV file reorder_plan_.csv with columns:

variant_id, sku, product_title, vendor, current_stock, daily_velocity, trend, days_of_stock, stockout_date, reorder_point, reorder_qty, order_by_date, est_cost

Error Handling

Best Practices