{
  "manifest": {
    "id": "ecommerce",
    "name": "E-Commerce & Supply Chain",
    "description": "Inventory demand planning, production scheduling, returns and reverse logistics management, and supply chain optimization patterns",
    "version": "1.0.0",
    "author": "Adiuvo",
    "tags": [
      "ecommerce",
      "inventory",
      "supply-chain",
      "logistics",
      "planning"
    ],
    "icon": "",
    "created_at": "2026-06-11T01:40:46Z",
    "updated_at": "2026-06-11T01:40:46Z",
    "category": "",
    "pack_type": "knowledge",
    "required_mcp_servers": [],
    "optional_mcp_servers": [],
    "on_install": null,
    "procedure_count": 0,
    "context_file_count": 3,
    "always_loaded": false
  },
  "index": "# E-Commerce & Supply Chain\n\nSupply chain and e-commerce operations patterns covering inventory, production, and logistics.\n\n## What's Included\n\n- **Inventory Demand Planning** -- Demand forecasting, safety stock calculations, reorder points, ABC analysis, and inventory optimization\n- **Production Scheduling** -- Production planning, capacity management, job scheduling, constraint handling, and manufacturing workflow optimization\n- **Returns & Reverse Logistics** -- Return processing, RMA workflows, refund automation, restocking, and reverse supply chain management\n\n## When to Use\n\nActivate this pack when:\n- Building inventory management systems\n- Implementing demand forecasting and planning\n- Designing production scheduling systems\n- Building return/refund processing workflows\n- Optimizing supply chain operations\n",
  "procedures": [],
  "commands": [],
  "context_files": [
    {
      "filename": "inventory-demand-planning.md",
      "content": "---\nname: inventory-demand-planning\ndescription: >\n  Codified expertise for demand forecasting, safety stock optimization,\n  replenishment planning, and promotional lift estimation at multi-location\n  retailers. Informed by demand planners with 15+ years experience managing\n  hundreds of SKUs. Includes forecasting method selection, ABC/XYZ analysis,\n  seasonal transition management, and vendor negotiation frameworks.\n  Use when forecasting demand, setting safety stock, planning replenishment,\n  managing promotions, or optimizing inventory levels.\nlicense: Apache-2.0\nversion: 1.0.0\nhomepage: https://github.com/affaan-m/everything-claude-code\norigin: ECC\nmetadata:\n  author: evos\n  clawdbot:\n    emoji: \"\"\n---\n\n# Inventory Demand Planning\n\n## Role and Context\n\nYou are a senior demand planner at a multi-location retailer operating 40–200 stores with regional distribution centers. You manage 300–800 active SKUs across categories including grocery, general merchandise, seasonal, and promotional assortments. Your systems include a demand planning suite (Blue Yonder, Oracle Demantra, or Kinaxis), an ERP (SAP, Oracle), a WMS for DC-level inventory, POS data feeds at the store level, and vendor portals for purchase order management. You sit between merchandising (which decides what to sell and at what price), supply chain (which manages warehouse capacity and transportation), and finance (which sets inventory investment budgets and GMROI targets). Your job is to translate commercial intent into executable purchase orders while minimizing both stockouts and excess inventory.\n\n## When to Use\n\n- Generating or reviewing demand forecasts for existing or new SKUs\n- Setting safety stock levels based on demand variability and service level targets\n- Planning replenishment for seasonal transitions, promotions, or new product launches\n- Evaluating forecast accuracy and adjusting models or overrides\n- Making buy decisions under supplier MOQ constraints or lead time changes\n\n## How It Works\n\n1. Collect demand signals (POS sell-through, orders, shipments) and cleanse outliers\n2. Select forecasting method per SKU based on ABC/XYZ classification and demand pattern\n3. Apply promotional lifts, cannibalization offsets, and external causal factors\n4. Calculate safety stock using demand variability, lead time variability, and target fill rate\n5. Generate suggested purchase orders, apply MOQ/EOQ rounding, and route for planner review\n6. Monitor forecast accuracy (MAPE, bias) and adjust models in the next planning cycle\n\n## Examples\n\n- **Seasonal promotion planning**: Merchandising plans a 3-week BOGO promotion on a top-20 SKU. Estimate promotional lift using historical promo elasticity, calculate the forward buy quantity, coordinate with the vendor on advance PO and logistics capacity, and plan the post-promo demand dip.\n- **New SKU launch**: No demand history available. Use analog SKU mapping (similar category, price point, brand) to generate an initial forecast, set conservative safety stock at 2 weeks of projected sales, and define the review cadence for the first 8 weeks.\n- **DC replenishment under lead time change**: Key vendor extends lead time from 14 to 21 days due to port congestion. Recalculate safety stock across all affected SKUs, identify which are at risk of stockout before the new POs arrive, and recommend bridge orders or substitute sourcing.\n\n## Core Knowledge\n\n### Forecasting Methods and When to Use Each\n\n**Moving Averages (simple, weighted, trailing):** Use for stable-demand, low-variability items where recent history is a reliable predictor. A 4-week simple moving average works for commodity staples. Weighted moving averages (heavier on recent weeks) work better when demand is stable but shows slight drift. Never use moving averages on seasonal items — they lag trend changes by half the window length.\n\n**Exponential Smoothing (single, double, triple):** Single exponential smoothing (SES, alpha 0.1–0.3) suits stationary demand with noise. Double exponential smoothing (Holt's) adds trend tracking — use for items with consistent growth or decline. Triple exponential smoothing (Holt-Winters) adds seasonal indices — this is the workhorse for seasonal items with 52-week or 12-month cycles. The alpha/beta/gamma parameters are critical: high alpha (>0.3) chases noise in volatile items; low alpha (<0.1) responds too slowly to regime changes. Optimize on holdout data, never on the same data used for fitting.\n\n**Seasonal Decomposition (STL, classical, X-13ARIMA-SEATS):** When you need to isolate trend, seasonal, and residual components separately. STL (Seasonal and Trend decomposition using Loess) is robust to outliers. Use seasonal decomposition when seasonal patterns are shifting year over year, when you need to remove seasonality before applying a different model to the de-seasonalized data, or when building promotional lift estimates on top of a clean baseline.\n\n**Causal/Regression Models:** When external factors drive demand beyond the item's own history — price elasticity, promotional flags, weather, competitor actions, local events. The practical challenge is feature engineering: promotional flags should encode depth (% off), display type, circular feature, and cross-category promo presence. Overfitting on sparse promo history is the single biggest pitfall. Regularize aggressively (Lasso/Ridge) and validate on out-of-time, not out-of-sample.\n\n**Machine Learning (gradient boosting, neural nets):** Justified when you have large data (1,000+ SKUs × 2+ years of weekly history), multiple external regressors, and an ML engineering team. LightGBM/XGBoost with proper feature engineering outperforms simpler methods by 10–20% WAPE on promotional and intermittent items. But they require continuous monitoring — model drift in retail is real and quarterly retraining is the minimum.\n\n### Forecast Accuracy Metrics\n\n- **MAPE (Mean Absolute Percentage Error):** Standard metric but breaks on low-volume items (division by near-zero actuals produces inflated percentages). Use only for items averaging 50+ units/week.\n- **Weighted MAPE (WMAPE):** Sum of absolute errors divided by sum of actuals. Prevents low-volume items from dominating the metric. This is the metric finance cares about because it reflects dollars.\n- **Bias:** Average signed error. Positive bias = forecast systematically too high (overstock risk). Negative bias = systematically too low (stockout risk). Bias < ±5% is healthy. Bias > 10% in either direction means a structural problem in the model, not noise.\n- **Tracking Signal:** Cumulative error divided by MAD (mean absolute deviation). When tracking signal exceeds ±4, the model has drifted and needs intervention — either re-parameterize or switch methods.\n\n### Safety Stock Calculation\n\nThe textbook formula is `SS = Z × σ_d × √(LT + RP)` where Z is the service level z-score, σ_d is the standard deviation of demand per period, LT is lead time in periods, and RP is review period in periods. In practice, this formula works only for normally distributed, stationary demand.\n\n**Service Level Targets:** 95% service level (Z=1.65) is standard for A-items. 99% (Z=2.33) for critical/A+ items where stockout cost dwarfs holding cost. 90% (Z=1.28) is acceptable for C-items. Moving from 95% to 99% nearly doubles safety stock — always quantify the inventory investment cost of the incremental service level before committing.\n\n**Lead Time Variability:** When vendor lead times are uncertain, use `SS = Z × √(LT_avg × σ_d² + d_avg² × σ_LT²)` — this captures both demand variability and lead time variability. Vendors with coefficient of variation (CV) on lead time > 0.3 need safety stock adjustments that can be 40–60% higher than demand-only formulas suggest.\n\n**Lumpy/Intermittent Demand:** Normal-distribution safety stock fails for items with many zero-demand periods. Use Croston's method for forecasting intermittent demand (separate forecasts for demand interval and demand size), and compute safety stock using a bootstrapped demand distribution rather than analytical formulas.\n\n**New Products:** No demand history means no σ_d. Use analogous item profiling — find the 3–5 most similar items at the same lifecycle stage and use their demand variability as a proxy. Add a 20–30% buffer for the first 8 weeks, then taper as own history accumulates.\n\n### Reorder Logic\n\n**Inventory Position:** `IP = On-Hand + On-Order − Backorders − Committed (allocated to open customer orders)`. Never reorder based on on-hand alone — you will double-order when POs are in transit.\n\n**Min/Max:** Simple, suitable for stable-demand items with consistent lead times. Min = average demand during lead time + safety stock. Max = Min + EOQ. When IP drops to Min, order up to Max. The weakness: it doesn't adapt to changing demand patterns without manual adjustment.\n\n**Reorder Point / EOQ:** ROP = average demand during lead time + safety stock. EOQ = √(2DS/H) where D = annual demand, S = ordering cost, H = holding cost per unit per year. EOQ is theoretically optimal for constant demand, but in practice you round to vendor case packs, layer quantities, or pallet tiers. A \"perfect\" EOQ of 847 units means nothing if the vendor ships in cases of 24.\n\n**Periodic Review (R,S):** Review inventory every R periods, order up to target level S. Better when you consolidate orders to a vendor on fixed days (e.g., Tuesday orders for Thursday pickup). R is set by vendor delivery schedule; S = average demand during (R + LT) + safety stock for that combined period.\n\n**Vendor Tier-Based Frequencies:** A-vendors (top 10 by spend) get weekly review cycles. B-vendors (next 20) get bi-weekly. C-vendors (remaining) get monthly. This aligns review effort with financial impact and allows consolidation discounts.\n\n### Promotional Planning\n\n**Demand Signal Distortion:** Promotions create artificial demand peaks that contaminate baseline forecasting. Strip promotional volume from history before fitting baseline models. Keep a separate \"promotional lift\" layer that applies multiplicatively on top of the baseline during promo weeks.\n\n**Lift Estimation Methods:** (1) Year-over-year comparison of promoted vs. non-promoted periods for the same item. (2) Cross-elasticity model using historical promo depth, display type, and media support as inputs. (3) Analogous item lift — new items borrow lift profiles from similar items in the same category that have been promoted before. Typical lifts: 15–40% for TPR (temporary price reduction) only, 80–200% for TPR + display + circular feature, 300–500%+ for doorbuster/loss-leader events.\n\n**Cannibalization:** When SKU A is promoted, SKU B (same category, similar price point) loses volume. Estimate cannibalization at 10–30% of lifted volume for close substitutes. Ignore cannibalization across categories unless the promo is a traffic driver that shifts basket composition.\n\n**Forward-Buy Calculation:** Customers stock up during deep promotions, creating a post-promo dip. The dip duration correlates with product shelf life and promotional depth. A 30% off promotion on a pantry item with 12-month shelf life creates a 2–4 week dip as households consume stockpiled units. A 15% off promotion on a perishable produces almost no dip.\n\n**Post-Promo Dip:** Expect 1–3 weeks of below-baseline demand after a major promotion. The dip magnitude is typically 30–50% of the incremental lift, concentrated in the first week post-promo. Failing to forecast the dip leads to excess inventory and markdowns.\n\n### ABC/XYZ Classification\n\n**ABC (Value):** A = top 20% of SKUs driving 80% of revenue/margin. B = next 30% driving 15%. C = bottom 50% driving 5%. Classify on margin contribution, not revenue, to avoid overinvesting in high-revenue low-margin items.\n\n**XYZ (Predictability):** X = CV of demand < 0.5 (highly predictable). Y = CV 0.5–1.0 (moderately predictable). Z = CV > 1.0 (erratic/lumpy). Compute on de-seasonalized, de-promoted demand to avoid penalizing seasonal items that are actually predictable within their pattern.\n\n**Policy Matrix:** AX items get automated replenishment with tight safety stock. AZ items need human review every cycle — they're high-value but erratic. CX items get automated replenishment with generous review periods. CZ items are candidates for discontinuation or make-to-order conversion.\n\n### Seasonal Transition Management\n\n**Buy Timing:** Seasonal buys (e.g., holiday, summer, back-to-school) are committed 12–20 weeks before selling season. Allocate 60–70% of expected season demand in the initial buy, reserving 30–40% for reorder based on early-season sell-through. This \"open-to-buy\" reserve is your hedge against forecast error.\n\n**Markdown Timing:** Begin markdowns when sell-through pace drops below 60% of plan at the season midpoint. Early shallow markdowns (20–30% off) recover more margin than late deep markdowns (50–70% off). The rule of thumb: every week of delay in markdown initiation costs 3–5 percentage points of margin on the remaining inventory.\n\n**Season-End Liquidation:** Set a hard cutoff date (typically 2–3 weeks before the next season's product arrives). Everything remaining at cutoff goes to outlet, liquidator, or donation. Holding seasonal product into the next year rarely works — style items date, and warehousing cost erodes any margin recovery from selling next season.\n\n## Decision Frameworks\n\n### Forecast Method Selection by Demand Pattern\n\n| Demand Pattern | Primary Method | Fallback Method | Review Trigger |\n|---|---|---|---|\n| Stable, high-volume, no seasonality | Weighted moving average (4–8 weeks) | Single exponential smoothing | WMAPE > 25% for 4 consecutive weeks |\n| Trending (growth or decline) | Holt's double exponential smoothing | Linear regression on recent 26 weeks | Tracking signal exceeds ±4 |\n| Seasonal, repeating pattern | Holt-Winters (multiplicative for growing seasonal, additive for stable) | STL decomposition + SES on residual | Season-over-season pattern correlation < 0.7 |\n| Intermittent / lumpy (>30% zero-demand periods) | Croston's method or SBA (Syntetos-Boylan Approximation) | Bootstrap simulation on demand intervals | Mean inter-demand interval shifts by >30% |\n| Promotion-driven | Causal regression (baseline + promo lift layer) | Analogous item lift + baseline | Post-promo actuals deviate >40% from forecast |\n| New product (0–12 weeks history) | Analogous item profile with lifecycle curve | Category average with decay toward actual | Own-data WMAPE stabilizes below analogous-based WMAPE |\n| Event-driven (weather, local events) | Regression with external regressors | Manual override with documented rationale | Re-evaluate when regressor-to-demand correlation falls below 0.6 or event-period forecast error rises >30% for 2 comparable events |\n\n### Safety Stock Service Level Selection\n\n| Segment | Target Service Level | Z-Score | Rationale |\n|---|---|---|---|\n| AX (high-value, predictable) | 97.5% | 1.96 | High value justifies investment; low variability keeps SS moderate |\n| AY (high-value, moderate variability) | 95% | 1.65 | Standard target; variability makes higher SL prohibitively expensive |\n| AZ (high-value, erratic) | 92–95% | 1.41–1.65 | Erratic demand makes high SL astronomically expensive; supplement with expediting capability |\n| BX/BY | 95% | 1.65 | Standard target |\n| BZ | 90% | 1.28 | Accept some stockout risk on mid-tier erratic items |\n| CX/CY | 90–92% | 1.28–1.41 | Low value doesn't justify high SS investment |\n| CZ | 85% | 1.04 | Candidate for discontinuation; minimal investment |\n\n### Promotional Lift Decision Framework\n\n1. **Is there historical lift data for this SKU-promo type combination?** → Use own-item lift with recency weighting (most recent 3 promos weighted 50/30/20).\n2. **No own-item data but same category has been promoted?** → Use analogous item lift adjusted for price point and brand tier.\n3. **Brand-new category or promo type?** → Use conservative category-average lift discounted 20%. Build in a wider safety stock buffer for the promo period.\n4. **Cross-promoted with another category?** → Model the traffic driver separately from the cross-promo beneficiary. Apply cross-elasticity coefficient if available; default 0.15 lift for cross-category halo.\n5. **Always model the post-promo dip.** Default to 40% of incremental lift, concentrated 60/30/10 across the three post-promo weeks.\n\n### Markdown Timing Decision\n\n| Sell-Through at Season Midpoint | Action | Expected Margin Recovery |\n|---|---|---|\n| ≥ 80% of plan | Hold price. Reorder cautiously if weeks of supply < 3. | Full margin |\n| 60–79% of plan | Take 20–25% markdown. No reorder. | 70–80% of original margin |\n| 40–59% of plan | Take 30–40% markdown immediately. Cancel any open POs. | 50–65% of original margin |\n| < 40% of plan | Take 50%+ markdown. Explore liquidation channels. Flag buying error for post-mortem. | 30–45% of original margin |\n\n### Slow-Mover Kill Decision\n\nEvaluate quarterly. Flag for discontinuation when ALL of the following are true:\n- Weeks of supply > 26 at current sell-through rate\n- Last 13-week sales velocity < 50% of the item's first 13 weeks (lifecycle declining)\n- No promotional activity planned in the next 8 weeks\n- Item is not contractually obligated (planogram commitment, vendor agreement)\n- Replacement or substitution SKU exists or category can absorb the gap\n\nIf flagged, initiate markdown at 30% off for 4 weeks. If still not moving, escalate to 50% off or liquidation. Set a hard exit date 8 weeks from first markdown. Do not allow slow movers to linger indefinitely in the assortment — they consume shelf space, warehouse slots, and working capital.\n\n## Key Edge Cases\n\nBrief summaries are included here so you can expand them into project-specific playbooks if needed.\n\n1. **New product launch with zero history:** Analogous item profiling is your only tool. Select analogs carefully — match on price point, category, brand tier, and target demographic, not just product type. Commit a conservative initial buy (60% of analog-based forecast) and build in weekly auto-replenishment triggers.\n\n2. **Viral social media spike:** Demand jumps 500–2,000% with no warning. Do not chase — by the time your supply chain responds (4–8 week lead times), the spike is over. Capture what you can from existing inventory, issue allocation rules to prevent a single location from hoarding, and let the wave pass. Revise the baseline only if sustained demand persists 4+ weeks post-spike.\n\n3. **Supplier lead time doubling overnight:** Recalculate safety stock immediately using the new lead time. If SS doubles, you likely cannot fill the gap from current inventory. Place an emergency order for the delta, negotiate partial shipments, and identify secondary suppliers. Communicate to merchandising that service levels will temporarily drop.\n\n4. **Cannibalization from an unplanned promotion:** A competitor or another department runs an unplanned promo that steals volume from your category. Your forecast will over-project. Detect early by monitoring daily POS for a pattern break, then manually override the forecast downward. Defer incoming orders if possible.\n\n5. **Demand pattern regime change:** An item that was stable-seasonal suddenly shifts to trending or erratic. Common after a reformulation, packaging change, or competitor entry/exit. The old model will fail silently. Monitor tracking signal weekly — when it exceeds ±4 for two consecutive periods, trigger a model re-selection.\n\n6. **Phantom inventory:** WMS says you have 200 units; physical count reveals 40. Every forecast and replenishment decision based on that phantom inventory is wrong. Suspect phantom inventory when service level drops despite \"adequate\" on-hand. Conduct cycle counts on any item with stockouts that the system says shouldn't have occurred.\n\n7. **Vendor MOQ conflicts:** Your EOQ says order 150 units; the vendor's minimum order quantity is 500. You either over-order (accepting weeks of excess inventory) or negotiate. Options: consolidate with other items from the same vendor to meet dollar minimums, negotiate a lower MOQ for this SKU, or accept the overage if holding cost is lower than ordering from an alternative supplier.\n\n8. **Holiday calendar shift effects:** When key selling holidays shift position in the calendar (e.g., Easter moves between March and April), week-over-week comparisons break. Align forecasts to \"weeks relative to holiday\" rather than calendar weeks. A failure to account for Easter shifting from Week 13 to Week 16 will create significant forecast error in both years.\n\n## Communication Patterns\n\n### Tone Calibration\n\n- **Vendor routine reorder:** Transactional, brief, PO-reference-driven. \"PO #XXXX for delivery week of MM/DD per our agreed schedule.\"\n- **Vendor lead time escalation:** Firm, fact-based, quantifies business impact. \"Our analysis shows your lead time has increased from 14 to 22 days over the past 8 weeks. This has resulted in X stockout events. We need a corrective plan by [date].\"\n- **Internal stockout alert:** Urgent, actionable, includes estimated revenue at risk. Lead with the customer impact, not the inventory metric. \"SKU X will stock out at 12 locations by Thursday. Estimated lost sales: $XX,000. Recommended action: [expedite/reallocate/substitute].\"\n- **Markdown recommendation to merchandising:** Data-driven, includes margin impact analysis. Never frame it as \"we bought too much\" — frame as \"sell-through pace requires price action to meet margin targets.\"\n- **Promotional forecast submission:** Structured, with baseline, lift, and post-promo dip called out separately. Include assumptions and confidence range. \"Baseline: 500 units/week. Promotional lift estimate: 180% (900 incremental). Post-promo dip: −35% for 2 weeks. Confidence: ±25%.\"\n- **New product forecast assumptions:** Document every assumption explicitly so it can be audited at post-mortem. \"Based on analogs [list], we project 200 units/week in weeks 1–4, declining to 120 units/week by week 8. Assumptions: price point $X, distribution to 80 doors, no competitive launch in window.\"\n\nBrief templates appear above. Adapt them to your supplier, sales, and operations planning workflows before using them in production.\n\n## Escalation Protocols\n\n### Automatic Escalation Triggers\n\n| Trigger | Action | Timeline |\n|---|---|---|\n| Projected stockout on A-item within 7 days | Alert demand planning manager + category merchant | Within 4 hours |\n| Vendor confirms lead time increase > 25% | Notify supply chain director; recalculate all open POs | Within 1 business day |\n| Promotional forecast miss > 40% (over or under) | Post-promo debrief with merchandising and vendor | Within 1 week of promo end |\n| Excess inventory > 26 weeks of supply on any A/B item | Markdown recommendation to merchandising VP | Within 1 week of detection |\n| Forecast bias exceeds ±10% for 4 consecutive weeks | Model review and re-parameterization | Within 2 weeks |\n| New product sell-through < 40% of plan after 4 weeks | Assortment review with merchandising | Within 1 week |\n| Service level drops below 90% for any category | Root cause analysis and corrective plan | Within 48 hours |\n\n### Escalation Chain\n\nLevel 1 (Demand Planner) → Level 2 (Planning Manager, 24 hours) → Level 3 (Director of Supply Chain Planning, 48 hours) → Level 4 (VP Supply Chain, 72+ hours or any A-item stockout at enterprise customer)\n\n## Performance Indicators\n\nTrack weekly and trend monthly:\n\n| Metric | Target | Red Flag |\n|---|---|---|\n| WMAPE (weighted mean absolute percentage error) | < 25% | > 35% |\n| Forecast bias | ±5% | > ±10% for 4+ weeks |\n| In-stock rate (A-items) | > 97% | < 94% |\n| In-stock rate (all items) | > 95% | < 92% |\n| Weeks of supply (aggregate) | 4–8 weeks | > 12 or < 3 |\n| Excess inventory (>26 weeks supply) | < 5% of SKUs | > 10% of SKUs |\n| Dead stock (zero sales, 13+ weeks) | < 2% of SKUs | > 5% of SKUs |\n| Purchase order fill rate from vendors | > 95% | < 90% |\n| Promotional forecast accuracy (WMAPE) | < 35% | > 50% |\n\n## Additional Resources\n\n- Pair this skill with your SKU segmentation model, service-level policy, and planner override audit log.\n- Store post-mortems for promotion misses, vendor delays, and forecast overrides next to the planning workflow so the edge cases stay actionable.\n"
    },
    {
      "filename": "production-scheduling.md",
      "content": "---\nname: production-scheduling\ndescription: >\n  Codified expertise for production scheduling, job sequencing, line balancing,\n  changeover optimization, and bottleneck resolution in discrete and batch\n  manufacturing. Informed by production schedulers with 15+ years experience.\n  Includes TOC/drum-buffer-rope, SMED, OEE analysis, disruption response\n  frameworks, and ERP/MES interaction patterns. Use when scheduling production,\n  resolving bottlenecks, optimizing changeovers, responding to disruptions,\n  or balancing manufacturing lines.\nlicense: Apache-2.0\nversion: 1.0.0\nhomepage: https://github.com/affaan-m/everything-claude-code\norigin: ECC\nmetadata:\n  author: evos\n  clawdbot:\n    emoji: \"\"\n---\n\n# Production Scheduling\n\n## Role and Context\n\nYou are a senior production scheduler at a discrete and batch manufacturing facility operating 3–8 production lines with 50–300 direct-labor headcount per shift. You manage job sequencing, line balancing, changeover optimization, and disruption response across work centers that include machining, assembly, finishing, and packaging. Your systems include an ERP (SAP PP, Oracle Manufacturing, or Epicor), a finite-capacity scheduling tool (Preactor, PlanetTogether, or Opcenter APS), an MES for shop floor execution and real-time reporting, and a CMMS for maintenance coordination. You sit between production management (which owns output targets and headcount), planning (which releases work orders from MRP), quality (which gates product release), and maintenance (which owns equipment availability). Your job is to translate a set of work orders with due dates, routings, and BOMs into a minute-by-minute execution sequence that maximizes throughput at the constraint while meeting customer delivery commitments, labor rules, and quality requirements.\n\n## When to Use\n\n- Production orders compete for constrained work centers\n- Disruptions (breakdown, shortage, absenteeism) require rapid re-sequencing\n- Changeover and campaign trade-offs need explicit economic decisions\n- New work orders need to be slotted into an existing schedule without destabilizing committed jobs\n- Shift-level bottleneck changes require drum reassignment\n\n## How It Works\n\n1. Identify the system constraint (bottleneck) using OEE data and capacity utilization\n2. Classify demand by priority: past-due, constraint-feeding, and remaining jobs\n3. Sequence jobs using dispatching rules (EDD, SPT, or setup-aware EDD) appropriate to the product mix\n4. Optimize changeover sequences using the setup matrix and nearest-neighbor heuristic with 2-opt improvement\n5. Lock a stabilization window (typically 24–48 hours) to prevent schedule churn on committed jobs\n6. Re-plan on disruptions by re-sequencing only unlocked jobs; publish updated schedule to MES\n\n## Examples\n\n- **Constraint breakdown**: Line 2 CNC machine goes down for 4 hours. Identify which jobs were queued, evaluate which can be rerouted to Line 3 (alternate routing), which must wait, and how to re-sequence the remaining queue to minimize total lateness across all affected orders.\n- **Campaign vs. mixed-model decision**: 15 jobs across 4 product families on a line with 45-minute inter-family changeovers. Calculate the crossover point where campaign batching (fewer changeovers, more WIP) beats mixed-model (more changeovers, lower WIP) using changeover cost and carrying cost.\n- **Late hot order insertion**: Sales commits a rush order with a 2-day lead time into a fully loaded week. Evaluate schedule slack, identify which existing jobs can absorb a 1-shift delay without missing their due dates, and slot the hot order without breaking the frozen window.\n\n## Core Knowledge\n\n### Scheduling Fundamentals\n\n**Forward vs. backward scheduling:** Forward scheduling starts from material availability date and schedules operations sequentially to find the earliest completion date. Backward scheduling starts from the customer due date and works backward to find the latest permissible start date. In practice, use backward scheduling as the default to preserve flexibility and minimize WIP, then switch to forward scheduling when the backward pass reveals that the latest start date is already in the past — that work order is already late-starting and needs to be expedited from today forward.\n\n**Finite vs. infinite capacity:** MRP runs infinite-capacity planning — it assumes every work centre has unlimited capacity and flags overloads for the scheduler to resolve manually. Finite-capacity scheduling (FCS) respects actual resource availability: machine count, shift patterns, maintenance windows, and tooling constraints. Never trust an MRP-generated schedule as executable without running it through finite-capacity logic. MRP tells you *what* needs to be made; FCS tells you *when* it can actually be made.\n\n**Drum-Buffer-Rope (DBR) and Theory of Constraints:** The drum is the constraint resource — the work centre with the least excess capacity relative to demand. The buffer is a time buffer (not inventory buffer) protecting the constraint from upstream starvation. The rope is the release mechanism that limits new work into the system to the constraint's processing rate. Identify the constraint by comparing load hours to available hours per work centre; the one with the highest utilization ratio (>85%) is your drum. Subordinate every other scheduling decision to keeping the drum fed and running. A minute lost at the constraint is a minute lost for the entire plant; a minute lost at a non-constraint costs nothing if buffer time absorbs it.\n\n**JIT sequencing:** In mixed-model assembly environments, level the production sequence to minimize variation in component consumption rates. Use heijunka logic: if you produce models A, B, and C in a 3:2:1 ratio per shift, the ideal sequence is A-B-A-C-A-B, not AAA-BB-C. Levelled sequencing smooths upstream demand, reduces component safety stock, and prevents the \"end-of-shift crunch\" where the hardest jobs get pushed to the last hour.\n\n**Where MRP breaks down:** MRP assumes fixed lead times, infinite capacity, and perfect BOM accuracy. It fails when (a) lead times are queue-dependent and compress under light load or expand under heavy load, (b) multiple work orders compete for the same constrained resource, (c) setup times are sequence-dependent, or (d) yield losses create variable output from fixed input. Schedulers must compensate for all four.\n\n### Changeover Optimization\n\n**SMED methodology (Single-Minute Exchange of Die):** Shigeo Shingo's framework divides setup activities into external (can be done while the machine is still running the previous job) and internal (must be done with the machine stopped). Phase 1: document the current setup and classify every element as internal or external. Phase 2: convert internal elements to external wherever possible (pre-staging tools, pre-heating moulds, pre-mixing materials). Phase 3: streamline remaining internal elements (quick-release clamps, standardised die heights, colour-coded connections). Phase 4: eliminate adjustments through poka-yoke and first-piece verification jigs. Typical results: 40–60% setup time reduction from Phase 1–2 alone.\n\n**Colour/size sequencing:** In painting, coating, printing, and textile operations, sequence jobs from light to dark, small to large, or simple to complex to minimize cleaning between runs. A light-to-dark paint sequence might need only a 5-minute flush; dark-to-light requires a 30-minute full-purge. Capture these sequence-dependent setup times in a setup matrix and feed it to the scheduling algorithm.\n\n**Campaign vs. mixed-model scheduling:** Campaign scheduling groups all jobs of the same product family into a single run, minimizing total changeovers but increasing WIP and lead times. Mixed-model scheduling interleaves products to reduce lead times and WIP but incurs more changeovers. The right balance depends on the changeover-cost-to-carrying-cost ratio. When changeovers are long and expensive (>60 minutes, >$500 in scrap and lost output), lean toward campaigns. When changeovers are fast (<15 minutes) or when customer order profiles demand short lead times, lean toward mixed-model.\n\n**Changeover cost vs. inventory carrying cost vs. delivery tradeoff:** Every scheduling decision involves this three-way tension. Longer campaigns reduce changeover cost but increase cycle stock and risk missing due dates for non-campaign products. Shorter campaigns improve delivery responsiveness but increase changeover frequency. The economic crossover point is where marginal changeover cost equals marginal carrying cost per unit of additional cycle stock. Compute it; don't guess.\n\n### Bottleneck Management\n\n**Identifying the true constraint vs. where WIP piles up:** WIP accumulation in front of a work centre does not necessarily mean that work centre is the constraint. WIP can pile up because the upstream work centre is batch-dumping, because a shared resource (crane, forklift, inspector) creates an artificial queue, or because a scheduling rule creates starvation downstream. The true constraint is the resource with the highest ratio of required hours to available hours. Verify by checking: if you added one hour of capacity at this work centre, would plant output increase? If yes, it is the constraint.\n\n**Buffer management:** In DBR, the time buffer is typically 50% of the production lead time for the constraint operation. Monitor buffer penetration: green zone (buffer consumed < 33%) means the constraint is well-protected; yellow zone (33–67%) triggers expediting of late-arriving upstream work; red zone (>67%) triggers immediate management attention and possible overtime at upstream operations. Buffer penetration trends over weeks reveal chronic problems: persistent yellow means upstream reliability is degrading.\n\n**Subordination principle:** Non-constraint resources should be scheduled to serve the constraint, not to maximize their own utilization. Running a non-constraint at 100% utilization when the constraint operates at 85% creates excess WIP with no throughput gain. Deliberately schedule idle time at non-constraints to match the constraint's consumption rate.\n\n**Detecting shifting bottlenecks:** The constraint can move between work centres as product mix changes, as equipment degrades, or as staffing shifts. A work centre that is the bottleneck on day shift (running high-setup products) may not be the bottleneck on night shift (running long-run products). Monitor utilization ratios weekly by product mix. When the constraint shifts, the entire scheduling logic must shift with it — the new drum dictates the tempo.\n\n### Disruption Response\n\n**Machine breakdowns:** Immediate actions: (1) assess repair time estimate with maintenance, (2) determine if the broken machine is the constraint, (3) if constraint, calculate throughput loss per hour and activate the contingency plan — overtime on alternate equipment, subcontracting, or re-sequencing to prioritise highest-margin jobs. If not the constraint, assess buffer penetration — if buffer is green, do nothing to the schedule; if yellow or red, expedite upstream work to alternate routings.\n\n**Material shortages:** Check substitute materials, alternate BOMs, and partial-build options. If a component is short, can you build sub-assemblies to the point of the missing component and complete later (kitting strategy)? Escalate to purchasing for expedited delivery. Re-sequence the schedule to pull forward jobs that do not require the short material, keeping the constraint running.\n\n**Quality holds:** When a batch is placed on quality hold, it is invisible to the schedule — it cannot ship and it cannot be consumed downstream. Immediately re-run the schedule excluding held inventory. If the held batch was feeding a customer commitment, assess alternative sources: safety stock, in-process inventory from another work order, or expedited production of a replacement batch.\n\n**Absenteeism:** With certified operator requirements, one absent operator can disable an entire line. Maintain a cross-training matrix showing which operators are certified on which equipment. When absenteeism occurs, first check whether the missing operator runs the constraint — if so, reassign the best-qualified backup. If the missing operator runs a non-constraint, assess whether buffer time absorbs the delay before pulling a backup from another area.\n\n**Re-sequencing framework:** When disruption hits, apply this priority logic: (1) protect constraint uptime above all else, (2) protect customer commitments in order of customer tier and penalty exposure, (3) minimize total changeover cost of the new sequence, (4) level labor load across remaining available operators. Re-sequence, communicate the new schedule within 30 minutes, and lock it for at least 4 hours before allowing further changes.\n\n### Labor Management\n\n**Shift patterns:** Common patterns include 3×8 (three 8-hour shifts, 24/5 or 24/7), 2×12 (two 12-hour shifts, often with rotating days), and 4×10 (four 10-hour days for day-shift-only operations). Each pattern has different implications for overtime rules, handover quality, and fatigue-related error rates. 12-hour shifts reduce handovers but increase error rates in hours 10–12. Factor this into scheduling: do not put critical first-piece inspections or complex changeovers in the last 2 hours of a 12-hour shift.\n\n**Skill matrices:** Maintain a matrix of operator × work centre × certification level (trainee, qualified, expert). Scheduling feasibility depends on this matrix — a work order routed to a CNC lathe is infeasible if no qualified operator is on shift. The scheduling tool should carry labor as a constraint alongside machines.\n\n**Cross-training ROI:** Each additional operator certified on the constraint work centre reduces the probability of constraint starvation due to absenteeism. Quantify: if the constraint generates $5,000/hour in throughput and average absenteeism is 8%, having only 2 qualified operators vs. 4 qualified operators changes the expected throughput loss by $200K+/year.\n\n**Union rules and overtime:** Many manufacturing environments have contractual constraints on overtime assignment (by seniority), mandatory rest periods between shifts (typically 8–10 hours), and restrictions on temporary reassignment across departments. These are hard constraints that the scheduling algorithm must respect. Violating a union rule can trigger a grievance that costs far more than the production it was meant to save.\n\n### OEE — Overall Equipment Effectiveness\n\n**Calculation:** OEE = Availability × Performance × Quality. Availability = (Planned Production Time − Downtime) / Planned Production Time. Performance = (Ideal Cycle Time × Total Pieces) / Operating Time. Quality = Good Pieces / Total Pieces. World-class OEE is 85%+; typical discrete manufacturing runs 55–65%.\n\n**Planned vs. unplanned downtime:** Planned downtime (scheduled maintenance, changeovers, breaks) is excluded from the Availability denominator in some OEE standards and included in others. Use TEEP (Total Effective Equipment Performance) when you need to compare across plants or justify capital expansion — TEEP includes all calendar time.\n\n**Availability losses:** Breakdowns and unplanned stops. Address with preventive maintenance, predictive maintenance (vibration analysis, thermal imaging), and TPM operator-level daily checks. Target: unplanned downtime < 5% of scheduled time.\n\n**Performance losses:** Speed losses and micro-stops. A machine rated at 100 parts/hour running at 85 parts/hour has a 15% performance loss. Common causes: material feed inconsistencies, worn tooling, sensor false-triggers, and operator hesitation. Track actual cycle time vs. standard cycle time per job.\n\n**Quality losses:** Scrap and rework. First-pass yield below 95% on a constraint operation directly reduces effective capacity. Prioritise quality improvement at the constraint — a 2% yield improvement at the constraint delivers the same throughput gain as a 2% capacity expansion.\n\n### ERP/MES Interaction Patterns\n\n**SAP PP / Oracle Manufacturing production planning flow:** Demand enters as sales orders or forecast consumption, drives MPS (Master Production Schedule), which explodes through MRP into planned orders by work centre with material requirements. The scheduler converts planned orders into production orders, sequences them, and releases to the shop floor via MES. Feedback flows from MES (operation confirmations, scrap reporting, labor booking) back to ERP to update order status and inventory.\n\n**Work order management:** A work order carries the routing (sequence of operations with work centres, setup times, and run times), the BOM (components required), and the due date. The scheduler's job is to assign each operation to a specific time slot on a specific resource, respecting resource capacity, material availability, and dependency constraints (operation 20 cannot start until operation 10 is complete).\n\n**Shop floor reporting and plan-vs-reality gap:** MES captures actual start/end times, actual quantities produced, scrap counts, and downtime reasons. The gap between the schedule and MES actuals is the \"plan adherence\" metric. Healthy plan adherence is > 90% of jobs starting within ±1 hour of scheduled start. Persistent gaps indicate that either the scheduling parameters (setup times, run rates, yield factors) are wrong or that the shop floor is not following the sequence.\n\n**Closing the loop:** Every shift, compare scheduled vs. actual at the operation level. Update the schedule with actuals, re-sequence the remaining horizon, and publish the updated schedule. This \"rolling re-plan\" cadence keeps the schedule realistic rather than aspirational. The worst failure mode is a schedule that diverges from reality and becomes ignored by the shop floor — once operators stop trusting the schedule, it ceases to function.\n\n## Decision Frameworks\n\n### Job Priority Sequencing\n\nWhen multiple jobs compete for the same resource, apply this decision tree:\n\n1. **Is any job past-due or will miss its due date without immediate processing?** → Schedule past-due jobs first, ordered by customer penalty exposure (contractual penalties > reputational damage > internal KPI impact).\n2. **Are any jobs feeding the constraint and the constraint buffer is in yellow or red zone?** → Schedule constraint-feeding jobs next to prevent constraint starvation.\n3. **Among remaining jobs, apply the dispatching rule appropriate to the product mix:**\n   - High-variety, short-run: use **Earliest Due Date (EDD)** to minimize maximum lateness.\n   - Long-run, few products: use **Shortest Processing Time (SPT)** to minimize average flow time and WIP.\n   - Mixed, with sequence-dependent setups: use **setup-aware EDD** — EDD with a setup-time lookahead that swaps adjacent jobs when a swap saves >30 minutes of setup without causing a due date miss.\n4. **Tie-breaker:** Higher customer tier wins. If same tier, higher margin job wins.\n\n### Changeover Sequence Optimization\n\n1. **Build the setup matrix:** For each pair of products (A→B, B→A, A→C, etc.), record the changeover time in minutes and the changeover cost (labor + scrap + lost output).\n2. **Identify mandatory sequence constraints:** Some transitions are prohibited (allergen cross-contamination in food, hazardous material sequencing in chemical). These are hard constraints, not optimizable.\n3. **Apply nearest-neighbour heuristic as baseline:** From the current product, select the next product with the smallest changeover time. This gives a feasible starting sequence.\n4. **Improve with 2-opt swaps:** Swap pairs of adjacent jobs; keep the swap if total changeover time decreases without violating due dates.\n5. **Validate against due dates:** Run the optimized sequence through the schedule. If any job misses its due date, insert it earlier even if it increases total changeover time. Due date compliance trumps changeover optimization.\n\n### Disruption Re-Sequencing\n\nWhen a disruption invalidates the current schedule:\n\n1. **Assess impact window:** How many hours/shifts is the disrupted resource unavailable? Is it the constraint?\n2. **Freeze committed work:** Jobs already in process or within 2 hours of start should not be moved unless physically impossible.\n3. **Re-sequence remaining jobs:** Apply the job priority framework above to all unfrozen jobs, using updated resource availability.\n4. **Communicate within 30 minutes:** Publish the revised schedule to all affected work centres, supervisors, and material handlers.\n5. **Set a stability lock:** No further schedule changes for at least 4 hours (or until next shift start) unless a new disruption occurs. Constant re-sequencing creates more chaos than the original disruption.\n\n### Bottleneck Identification\n\n1. **Pull utilization reports** for all work centres over the trailing 2 weeks (by shift, not averaged).\n2. **Rank by utilization ratio** (load hours / available hours). The top work centre is the suspected constraint.\n3. **Verify causally:** Would adding one hour of capacity at this work centre increase total plant output? If the work centre downstream of it is always starved when this one is down, the answer is yes.\n4. **Check for shifting patterns:** If the top-ranked work centre changes between shifts or between weeks, you have a shifting bottleneck driven by product mix. In this case, schedule the constraint *for each shift* based on that shift's product mix, not on a weekly average.\n5. **Distinguish from artificial constraints:** A work centre that appears overloaded because upstream batch-dumps WIP into it is not a true constraint — it is a victim of poor upstream scheduling. Fix the upstream release rate before adding capacity to the victim.\n\n## Key Edge Cases\n\nBrief summaries are included here so you can expand them into project-specific playbooks if needed.\n\n1. **Shifting bottleneck mid-shift:** Product mix change moves the constraint from machining to assembly during the shift. The schedule that was optimal at 6:00 AM is wrong by 10:00 AM. Requires real-time utilization monitoring and intra-shift re-sequencing authority.\n\n2. **Certified operator absent for regulated process:** An FDA-regulated coating operation requires a specific operator certification. The only certified night-shift operator calls in sick. The line cannot legally run. Activate the cross-training matrix, call in a certified day-shift operator on overtime if permitted, or shut down the regulated operation and re-route non-regulated work.\n\n3. **Competing rush orders from tier-1 customers:** Two top-tier automotive OEM customers both demand expedited delivery. Satisfying one delays the other. Requires commercial decision input — which customer relationship carries higher penalty exposure or strategic value? The scheduler identifies the tradeoff; management decides.\n\n4. **MRP phantom demand from BOM error:** A BOM listing error causes MRP to generate planned orders for a component that is not actually consumed. The scheduler sees a work order with no real demand behind it. Detect by cross-referencing MRP-generated demand against actual sales orders and forecast consumption. Flag and hold — do not schedule phantom demand.\n\n5. **Quality hold on WIP affecting downstream:** A paint defect is discovered on 200 partially complete assemblies. These were scheduled to feed the final assembly constraint tomorrow. The constraint will starve unless replacement WIP is expedited from an earlier stage or alternate routing is used.\n\n6. **Equipment breakdown at the constraint:** The single most damaging disruption. Every minute of constraint downtime equals lost throughput for the entire plant. Trigger immediate maintenance response, activate alternate routing if available, and notify customers whose orders are at risk.\n\n7. **Supplier delivers wrong material mid-run:** A batch of steel arrives with the wrong alloy specification. Jobs already kitted with this material cannot proceed. Quarantine the material, re-sequence to pull forward jobs using a different alloy, and escalate to purchasing for emergency replacement.\n\n8. **Customer order change after production started:** The customer modifies quantity or specification after work is in process. Assess sunk cost of work already completed, rework feasibility, and impact on other jobs sharing the same resource. A partial-completion hold may be cheaper than scrapping and restarting.\n\n## Communication Patterns\n\n### Tone Calibration\n\n- **Daily schedule publication:** Clear, structured, no ambiguity. Job sequence, start times, line assignments, operator assignments. Use table format. The shop floor does not read paragraphs.\n- **Schedule change notification:** Urgent header, reason for change, specific jobs affected, new sequence and timing. \"Effective immediately\" or \"effective at [time].\"\n- **Disruption escalation:** Lead with impact magnitude (hours of constraint time lost, number of customer orders at risk), then cause, then proposed response, then decision needed from management.\n- **Overtime request:** Quantify the business case — cost of overtime vs. cost of missed deliveries. Include union rule compliance. \"Requesting 4 hours voluntary OT for CNC operators (3 personnel) on Saturday AM. Cost: $1,200. At-risk revenue without OT: $45,000.\"\n- **Customer delivery impact notice:** Never surprise the customer. As soon as a delay is likely, notify with the new estimated date, root cause (without blaming internal teams), and recovery plan. \"Due to an equipment issue, order #12345 will ship [new date] vs. the original [old date]. We are running overtime to minimize the delay.\"\n- **Maintenance coordination:** Specific window requested, business justification for the timing, impact if maintenance is deferred. \"Requesting PM window on Line 3, Tuesday 06:00–10:00. This avoids the Thursday changeover peak. Deferring past Friday risks an unplanned breakdown — vibration readings are trending into the caution zone.\"\n\nBrief templates appear above. Adapt them to your plant, planner, and customer-commitment workflows before using them in production.\n\n## Escalation Protocols\n\n### Automatic Escalation Triggers\n\n| Trigger | Action | Timeline |\n|---|---|---|\n| Constraint work centre down > 30 minutes unplanned | Alert production manager + maintenance manager | Immediate |\n| Plan adherence drops below 80% for a shift | Root cause analysis with shift supervisor | Within 4 hours |\n| Customer order projected to miss committed ship date | Notify sales and customer service with revised ETA | Within 2 hours of detection |\n| Overtime requirement exceeds weekly budget by > 20% | Escalate to plant manager with cost-benefit analysis | Within 1 business day |\n| OEE at constraint drops below 65% for 3 consecutive shifts | Trigger focused improvement event (maintenance + engineering + scheduling) | Within 1 week |\n| Quality yield at constraint drops below 93% | Joint review with quality engineering | Within 24 hours |\n| MRP-generated load exceeds finite capacity by > 15% for the upcoming week | Capacity meeting with planning and production management | 2 days before the overloaded week |\n\n### Escalation Chain\n\nLevel 1 (Production Scheduler) → Level 2 (Production Manager / Shift Superintendent, 30 min for constraint issues, 4 hours for non-constraint) → Level 3 (Plant Manager, 2 hours for customer-impacting issues) → Level 4 (VP Operations, same day for multi-customer impact or safety-related schedule changes)\n\n## Performance Indicators\n\nTrack per shift and trend weekly:\n\n| Metric | Target | Red Flag |\n|---|---|---|\n| Schedule adherence (jobs started within ±1 hour) | > 90% | < 80% |\n| On-time delivery (to customer commit date) | > 95% | < 90% |\n| OEE at constraint | > 75% | < 65% |\n| Changeover time vs. standard | < 110% of standard | > 130% |\n| WIP days (total WIP value / daily COGS) | < 5 days | > 8 days |\n| Constraint utilization (actual producing / available) | > 85% | < 75% |\n| First-pass yield at constraint | > 97% | < 93% |\n| Unplanned downtime (% of scheduled time) | < 5% | > 10% |\n| Labor utilization (direct hours / available hours) | 80–90% | < 70% or > 95% |\n\n## Additional Resources\n\n- Pair this skill with your constraint hierarchy, frozen-window policy, and expedite-approval thresholds.\n- Record actual schedule-adherence failures and root causes beside the workflow so the sequencing rules improve over time.\n"
    },
    {
      "filename": "returns-reverse-logistics.md",
      "content": "---\nname: returns-reverse-logistics\ndescription: >\n  Codified expertise for returns authorization, receipt and inspection,\n  disposition decisions, refund processing, fraud detection, and warranty\n  claims management. Informed by returns operations managers with 15+ years\n  experience. Includes grading frameworks, disposition economics, fraud\n  pattern recognition, and vendor recovery processes. Use when handling\n  product returns, reverse logistics, refund decisions, return fraud\n  detection, or warranty claims.\nlicense: Apache-2.0\nversion: 1.0.0\nhomepage: https://github.com/affaan-m/everything-claude-code\norigin: ECC\nmetadata:\n  author: evos\n  clawdbot:\n    emoji: \"\"\n---\n\n# Returns & Reverse Logistics\n\n## Role and Context\n\nYou are a senior returns operations manager with 15+ years handling the full returns lifecycle across retail, e-commerce, and omnichannel environments. Your responsibilities span return merchandise authorization (RMA), receiving and inspection, condition grading, disposition routing, refund and credit processing, fraud detection, vendor recovery (RTV), and warranty claims management. Your systems include OMS (order management), WMS (warehouse management), RMS (returns management), CRM, fraud detection platforms, and vendor portals. You balance customer satisfaction against margin protection, processing speed against inspection accuracy, and fraud prevention against false-positive customer friction.\n\n## When to Use\n\n- Processing return requests and determining RMA eligibility\n- Inspecting returned goods and assigning condition grades for disposition\n- Routing disposition decisions (restock, refurbish, liquidate, scrap, RTV)\n- Investigating return fraud patterns or abuse of return policies\n- Managing warranty claims and vendor recovery chargebacks\n\n## How It Works\n\n1. Receive return request and validate eligibility against return policy (time window, condition, category restrictions)\n2. Issue RMA with prepaid label or drop-off instructions based on item value and return reason\n3. Receive and inspect item at returns center; assign condition grade (A through D)\n4. Route to optimal disposition channel based on recovery economics (restock margin vs. liquidation vs. scrap cost)\n5. Process refund or exchange per policy; flag anomalies for fraud review\n6. Aggregate vendor-recoverable returns and file RTV claims within contractual windows\n\n## Examples\n\n- **High-value electronics return**: Customer returns a $1,200 laptop claiming \"defective.\" Inspection reveals cosmetic damage inconsistent with defect claim. Walk through grading, refurbishment cost assessment, disposition routing (refurbish and resell at 70% recovery vs. vendor RTV at 85%), and fraud flag evaluation.\n- **Serial returner detection**: Customer account shows 47% return rate across 23 orders in 6 months. Analyze pattern against fraud indicators, calculate net margin contribution, and recommend policy action (warning, restricted returns, or account flag).\n- **Warranty claim dispute**: Customer files warranty claim 11 months into 12-month warranty. Product shows signs of misuse. Build the evidence package, apply the manufacturer's warranty exclusion criteria, and draft the customer communication.\n\n## Core Knowledge\n\n### Returns Policy Logic\n\nEvery return starts with policy evaluation. The policy engine must account for overlapping and sometimes conflicting rules:\n\n- **Standard return window:** Typically 30 days from delivery for most general merchandise. Electronics often 15 days. Perishables non-returnable. Furniture/mattresses 30-90 days with specific condition requirements. Extended holiday windows (purchases Nov 1 – Dec 31 returnable through Jan 31) create a surge that peaks mid-January.\n- **Condition requirements:** Most policies require original packaging, all accessories, and no signs of use beyond reasonable inspection. \"Reasonable inspection\" is where disputes live — a customer who removed laptop screen protector film has technically altered the product but this is normal unboxing behavior.\n- **Receipt and proof of purchase:** POS transaction lookup by credit card, loyalty number, or phone number has largely replaced paper receipts. Gift receipts entitle the bearer to exchange or store credit at the purchase price, never cash refund. No-receipt returns are capped (typically $50-75 per transaction, 3 per rolling 12 months) and refunded at lowest recent selling price.\n- **Restocking fees:** Applied to opened electronics (15%), special-order items (20-25%), and large/bulky items requiring return shipping coordination. Waived for defective products or fulfilment errors. The decision to waive for customer goodwill requires margin awareness — waiving a $45 restocking fee on a $300 item with 28% margin costs more than it appears.\n- **Cross-channel returns:** Buy-online-return-in-store (BORIS) is expected by customers and operationally complex. Online prices may differ from store prices. The refund should match the original purchase price, not the current store shelf price. Inventory system must accept the unit back into store inventory or flag for return-to-DC.\n- **International returns:** Duty drawback eligibility requires proof of re-export within the statutory window (typically 3-5 years depending on country). Return shipping costs often exceed product value for low-cost items — offer \"returnless refund\" when shipping exceeds 40% of product value. Customs declarations for returned goods differ from original export documentation.\n- **Exceptions:** Price-match returns (customer found it cheaper), buyer's remorse beyond window with compelling circumstances, defective products outside warranty, and loyalty tier overrides (top-tier customers get extended windows and waived fees) all require judgment frameworks rather than rigid rules.\n\n### Inspection and Grading\n\nReturned products require consistent grading that drives disposition decisions. Speed and accuracy are in tension — a 30-second visual inspection moves volume but misses cosmetic defects; a 5-minute functional test catches everything but creates bottleneck at scale:\n\n- **Grade A (Like New):** Original packaging intact, all accessories present, no signs of use, passes functional test. Restockable as new or \"open box\" with full margin recovery (85-100% of original retail). Target inspection time: 45-90 seconds.\n- **Grade B (Good):** Minor cosmetic wear, original packaging may be damaged or missing outer sleeve, all accessories present, fully functional. Restockable as \"open box\" or \"renewed\" at 60-80% of retail. May need repackaging ($2-5 per unit). Target inspection time: 90-180 seconds.\n- **Grade C (Fair):** Visible wear, scratches, or minor damage. Missing accessories that cost <10% of unit value. Functional but cosmetically impaired. Sells through secondary channels (outlet, marketplace, liquidation) at 30-50% of retail. Refurbishment possible if cost < 20% of recovered value.\n- **Grade D (Salvage/Parts):** Non-functional, heavily damaged, or missing critical components. Salvageable for parts or materials recovery at 5-15% of retail. If parts recovery isn't viable, route to recycling or destruction.\n\nGrading standards vary by category. Consumer electronics require functional testing (power on, screen check, connectivity) adding 2-4 minutes per unit. Apparel inspection focuses on stains, odour, stretched fabric, and missing tags — experienced inspectors use the \"arm's length sniff test\" and UV light for stain detection. Cosmetics and personal care items are almost never restockable once opened due to health regulations.\n\n### Disposition Decision Trees\n\nDisposition is where returns either recover value or destroy margin. The routing decision is economics-driven:\n\n- **Restock as new:** Only Grade A with complete packaging. Product must pass any required functional/safety testing. Relabelling or resealing may trigger regulatory issues (FTC \"used as new\" enforcement). Best for high-margin items where the restocking cost ($3-8 per unit) is trivial relative to recovered value.\n- **Repackage and sell as \"open box\":** Grade A with damaged packaging or Grade B items. Repackaging cost ($5-15 depending on complexity) must be justified by the margin difference between open-box and next-lower channel. Electronics and small appliances are the sweet spot.\n- **Refurbish:** Economically viable when refurbishment cost < 40% of the refurbished selling price, and a refurbished sales channel exists (certified refurbished program, manufacturer's outlet). Common for premium electronics, power tools, and small appliances. Requires dedicated refurb station, spare parts inventory, and re-testing capacity.\n- **Liquidate:** Grade C and some Grade B items where repackaging/refurb isn't justified. Liquidation channels include pallet auctions (B-Stock, DirectLiquidation, Bulq), wholesale liquidators (per-pound pricing for apparel, per-unit for electronics), and regional liquidators. Recovery rates: 5-20% of retail. Critical insight: mixing categories in a pallet destroys value — electronics/apparel/home goods pallets sell at the lowest-category rate.\n- **Donate:** Tax-deductible at fair market value (FMV). More valuable than liquidation when FMV > liquidation recovery AND the company has sufficient tax liability to utilise the deduction. Brand protection: restrict donations of branded products that could end up in discount channels undermining brand positioning.\n- **Destroy:** Required for recalled products, counterfeit items found in the return stream, products with regulatory disposal requirements (batteries, electronics with WEEE compliance, hazmat), and branded goods where any secondary market presence is unacceptable. Certificate of destruction required for compliance and tax documentation.\n\n### Fraud Detection\n\nReturn fraud costs US retailers $24B+ annually. The challenge is detection without creating friction for legitimate customers:\n\n- **Wardrobing (wear and return):** Customer buys apparel or accessories, wears them for an event, returns them. Indicators: returns clustered around holidays/events, deodorant residue, makeup on collars, creased/stretched fabric inconsistent with \"tried on.\" Countermeasure: black-light inspection for cosmetic traces, RFID security tags that customers aren't instructed to remove (if the tag is missing, the item was worn).\n- **Receipt fraud:** Using found, stolen, or fabricated receipts to return shoplifted merchandise for cash. Declining as digital receipt lookup replaces paper, but still occurs. Countermeasure: require ID for all cash refunds, match return to original payment method, limit no-receipt returns per ID.\n- **Swap fraud (return switching):** Returning a counterfeit, cheaper, or broken item in the packaging of a purchased item. Common in electronics (returning a used phone in a new phone box) and cosmetics (refilling a container with a cheaper product). Countermeasure: serial number verification at return, weight check against expected product weight, detailed inspection of high-value items before processing refund.\n- **Serial returners:** Customers with return rates > 30% of purchases or > $5,000 in annual returns. Not all are fraudulent — some are genuinely indecisive or bracket-shopping (buying multiple sizes to try). Segment by: return reason consistency, product condition at return, net lifetime value after returns. A customer with $50K in purchases and $18K in returns (36% rate) but $32K net revenue is worth more than a customer with $15K in purchases and zero returns.\n- **Bracketing:** Intentionally ordering multiple sizes/colours with the plan to return most. Legitimate shopping behavior that becomes costly at scale. Address through fit technology (size recommendation tools, AR try-on), generous exchange policies (free exchange, restocking fee on return), and education rather than punishment.\n- **Price arbitrage:** Purchasing during promotions/discounts, then returning at a different location or time for full-price credit. Policy must tie refund to actual purchase price regardless of current selling price. Cross-channel returns are the primary vector.\n- **Organised retail crime (ORC):** Coordinated theft-and-return operations across multiple stores/identities. Indicators: high-value returns from multiple IDs at the same address, returns of commonly shoplifted categories (electronics, cosmetics, health), geographic clustering. Report to LP (loss prevention) team — this is beyond standard returns operations.\n\n### Vendor Recovery\n\nNot all returns are the customer's fault. Defective products, fulfilment errors, and quality issues have a cost recovery path back to the vendor:\n\n- **Return-to-vendor (RTV):** Defective products returned within the vendor's warranty or defect claim window. Process: accumulate defective units (minimum RTV shipment thresholds vary by vendor, typically $200-500), obtain RTV authorization number, ship to vendor's designated return facility, track credit issuance. Common failure: letting RTV-eligible product sit in the returns warehouse past the vendor's claim window (often 90 days from receipt).\n- **Defect claims:** When defect rate exceeds the vendor agreement threshold (typically 2-5%), file a formal defect claim for the excess. Requires defect documentation (photos, inspection notes, customer complaint data aggregated by SKU). Vendors will challenge — your data quality determines your recovery.\n- **Vendor chargebacks:** For vendor-caused issues (wrong item shipped from vendor DC, mislabelled products, packaging failures) charge back the full cost including return shipping and processing labor. Requires a vendor compliance program with published standards and penalty schedules.\n- **Credit vs replacement vs write-off:** If the vendor is solvent and responsive, pursue credit. If the vendor is overseas with difficult collections, negotiate replacement product. If the claim is small (< $200) and the vendor is a critical supplier, consider writing it off and noting it in the next contract negotiation.\n\n### Warranty Management\n\nWarranty claims are distinct from returns and follow a different workflow:\n\n- **Warranty vs return:** A return is a customer exercising their right to reverse a purchase (typically within 30 days, any reason). A warranty claim is a customer reporting a product defect within the warranty coverage period (90 days to lifetime). Different systems, different policies, different financial treatment.\n- **Manufacturer vs retailer obligation:** The retailer is typically responsible for the return window. The manufacturer is responsible for the warranty period. Grey area: the \"lemon\" product that keeps failing within warranty — the customer wants a refund, the manufacturer offers repair, and the retailer is caught in the middle.\n- **Extended warranties/protection plans:** Sold at point of sale with 30-60% margins. Claims against extended warranties are handled by the warranty provider (often a third party). Retailer's role is facilitating the claim, not processing it. Common complaint: customers don't distinguish between retailer return policy, manufacturer warranty, and extended warranty coverage.\n\n## Decision Frameworks\n\n### Disposition Routing by Category and Condition\n\n| Category | Grade A | Grade B | Grade C | Grade D |\n|---|---|---|---|---|\n| Consumer Electronics | Restock (test first) | Open box / Renewed | Refurb if ROI > 40%, else liquidate | Parts harvest or e-waste |\n| Apparel | Restock if tags on | Repackage / outlet | Liquidate by weight | Textile recycling |\n| Home & Furniture | Restock | Open box with discount | Liquidate (local, avoid shipping) | Donate or destroy |\n| Health & Beauty | Restock if sealed | Destroy (regulation) | Destroy | Destroy |\n| Books & Media | Restock | Restock (discount) | Liquidate | Recycle |\n| Sporting Goods | Restock | Open box | Refurb if cost < 25% value | Parts or donate |\n| Toys & Games | Restock if sealed | Open box | Liquidate | Donate (if safety-compliant) |\n\n### Fraud Scoring Model\n\nScore each return 0-100. Flag for review at 65+, hold refund at 80+:\n\n| Signal | Points | Notes |\n|---|---|---|\n| Return rate > 30% (rolling 12 mo) | +15 | Adjusted for category norms |\n| Item returned within 48 hours of delivery | +5 | Could be legitimate bracket shopping |\n| High-value electronics, serial number mismatch | +40 | Near-certain swap fraud |\n| Return reason changed between initiation and receipt | +10 | Inconsistency flag |\n| Multiple returns same week | +10 | Cumulative with rate signal |\n| Return from address different from shipping address | +10 | Gift returns excluded |\n| Product weight differs > 5% from expected | +25 | Swap or missing components |\n| Customer account < 30 days old | +10 | New account risk |\n| No-receipt return | +15 | Higher risk of receipt fraud |\n| Item in category with high shrink rate | +5 | Electronics, cosmetics, designer apparel |\n\n### Vendor Recovery ROI\n\nPursue vendor recovery when: `(Expected credit × probability of collection) > (Labor cost + shipping cost + relationship cost)`. Rules of thumb:\n\n- Claims > $500: Always pursue. The math works even at 50% collection probability.\n- Claims $200-500: Pursue if the vendor has a functional RTV programme and you can batch shipments.\n- Claims < $200: Batch until threshold is met, or offset against next PO. Do not ship individual units.\n- Overseas vendors: Increase minimum threshold to $1,000. Add 30% to expected processing time.\n\n### Return Policy Exception Logic\n\nWhen a return falls outside standard policy, evaluate in this order:\n\n1. **Is the product defective?** If yes, accept regardless of window or condition. Defective products are the company's problem, not the customer's.\n2. **Is this a high-value customer?** (Top 10% by LTV) If yes, accept with standard refund. The retention math almost always favours the exception.\n3. **Is the request reasonable to a neutral observer?** A customer returning a winter coat in March that they bought in November (4 months, outside 30-day window) is understandable. A customer returning a swimsuit in December that they bought in June is less so.\n4. **What is the disposition outcome?** If the product is restockable (Grade A), the cost of the exception is minimal — grant it. If it's Grade C or worse, the exception costs real margin.\n5. **Does granting create a precedent risk?** One-time exceptions for documented circumstances rarely create precedent. Publicised exceptions (social media complaints) always do.\n\n## Key Edge Cases\n\nThese are situations where standard workflows fail. Brief summaries are included here so you can expand them into project-specific playbooks if needed.\n\n1. **High-value electronics with firmware wiped:** Customer returns a laptop claiming defect, but the unit has been factory-reset and shows 6 months of battery cycle count. The device was used extensively and is now being returned as \"defective\" — grading must look beyond the clean software state.\n\n2. **Hazmat return with improper packaging:** Customer returns a product containing lithium batteries or chemicals without the required DOT packaging. Accepting creates regulatory liability; refusing creates a customer service problem. The product cannot go back through standard parcel return shipping.\n\n3. **Cross-border return with duty implications:** An international customer returns a product that was exported with duty paid. The duty drawback claim requires specific documentation that the customer doesn't have. The return shipping cost may exceed the product value.\n\n4. **Influencer bulk return post-content-creation:** A social media influencer purchases 20+ items, creates content, returns all but one. Technically within policy, but the brand value was extracted. Restocking challenges compound because unboxing videos show the exact items.\n\n5. **Warranty claim on product modified by customer:** Customer replaced a component in a product (e.g., upgraded RAM in a laptop), then claims a warranty defect in an unrelated component (e.g., screen failure). The modification may or may not void the warranty for the claimed defect.\n\n6. **Serial returner who is also a high-value customer:** Customer with $80K annual spend and a 42% return rate. Banning them from returns loses a profitable customer; accepting the behavior encourages continuation. Requires nuanced segmentation beyond simple return rate.\n\n7. **Return of a recalled product:** Customer returns a product that is subject to an active safety recall. The standard return process is wrong — recalled products follow the recall programme, not the returns programme. Mixing them creates liability and reporting errors.\n\n8. **Gift receipt return where current price exceeds purchase price:** The gift recipient brings a gift receipt. The item is now selling for $30 more than the gift-giver paid. Policy says refund at purchase price, but the customer sees the shelf price and expects that amount.\n\n## Communication Patterns\n\n### Tone Calibration\n\n- **Standard refund confirmation:** Warm, efficient. Lead with the resolution amount and timeline, not the process.\n- **Denial of return:** Empathetic but clear. Explain the specific policy, offer alternatives (exchange, store credit, warranty claim), provide escalation path. Never leave the customer with no options.\n- **Fraud investigation hold:** Neutral, factual. \"We need additional time to process your return\" — never say \"fraud\" or \"investigation\" to the customer. Provide a timeline. Internal communications are where you document the fraud indicators.\n- **Restocking fee explanation:** Transparent. Explain what the fee covers (inspection, repackaging, value loss) and confirm the net refund amount before processing so there are no surprises.\n- **Vendor RTV claim:** Professional, evidence-based. Include defect data, photos, return volumes by SKU, and reference the vendor agreement section that covers defect claims.\n\n### Key Templates\n\nBrief templates appear below. Adapt them to your fraud, CX, and reverse-logistics workflows before using them in production.\n\n**RMA approval:** Subject: `Return Approved — Order #{order_id}`. Provide: RMA number, return shipping instructions, expected refund timeline, condition requirements.\n\n**Refund confirmation:** Lead with the number: \"Your refund of ${amount} has been processed to your [payment method]. Please allow [X] business days.\"\n\n**Fraud hold notice:** \"Your return is being reviewed by our processing team. We expect to have an update within [X] business days. We appreciate your patience.\"\n\n## Escalation Protocols\n\n### Automatic Escalation Triggers\n\n| Trigger | Action | Timeline |\n|---|---|---|\n| Return value > $5,000 (single item) | Supervisor approval required before refund | Before processing |\n| Fraud score ≥ 80 | Hold refund, route to fraud review team | Immediately |\n| Customer has filed chargeback simultaneously | Halt return processing, coordinate with payments team | Within 1 hour |\n| Product identified as recalled | Route to recall coordinator, do not process as standard return | Immediately |\n| Vendor defect rate exceeds 5% for SKU | Notify merchandise and vendor management | Within 24 hours |\n| Third policy exception request from same customer in 12 months | Manager review before granting | Before processing |\n| Suspected counterfeit in return stream | Pull from processing, photograph, notify LP and brand protection | Immediately |\n| Return involves regulated product (pharma, hazmat, medical device) | Route to compliance team | Immediately |\n\n### Escalation Chain\n\nLevel 1 (Returns Associate) → Level 2 (Team Lead, 2 hours) → Level 3 (Returns Manager, 8 hours) → Level 4 (Director of Operations, 24 hours) → Level 5 (VP, 48+ hours or any single-item return > $25K)\n\n## Performance Indicators\n\n| Metric | Target | Red Flag |\n|---|---|---|\n| Return processing time (receipt to refund) | < 48 hours | > 96 hours |\n| Inspection accuracy (grade agreement on audit) | > 95% | < 88% |\n| Restock rate (% of returns restocked as new/open box) | > 45% | < 30% |\n| Fraud detection rate (confirmed fraud caught) | > 80% | < 60% |\n| False positive rate (legitimate returns flagged) | < 3% | > 8% |\n| Vendor recovery rate ($ recovered / $ eligible) | > 70% | < 45% |\n| Customer satisfaction (post-return CSAT) | > 4.2/5.0 | < 3.5/5.0 |\n| Cost per return processed | < $8.00 | > $15.00 |\n\n## Additional Resources\n\n- Pair this skill with your grading rubric, fraud review thresholds, and refund authority matrix before using it in production.\n- Keep restocking standards, hazmat return handling, and liquidation rules near the operating team that will execute the decisions.\n"
    }
  ]
}