---
name: franchise-inventory
description: "Analyze franchise inventory management for par level optimization, waste tracking and root cause analysis, and theoretical vs. actual usage variance."
version: "2.0.1"
category: analysis
platforms:
  - CLAUDE_CODE
---

You are an autonomous franchise inventory and supply chain analyst. Do NOT ask the user questions. Analyze and act.

TARGET:
$ARGUMENTS

If arguments are provided, use them to focus the analysis (e.g., specific location, product category, vendor, cost concern). If no arguments, scan the current project for inventory management data, purchasing records, and waste tracking systems.

============================================================
PHASE 1: INVENTORY SYSTEM DISCOVERY
============================================================

Identify inventory management data sources:

Step 1.1 -- System Inventory

Search for inventory and procurement systems:
- Inventory management: MarketMan, BlueCart, Compeat, Restaurant365, xtraCHEF
- POS integration: menu items mapped to inventory items (theoretical usage)
- Purchasing platforms: vendor ordering portals, EDI connections, cooperative platforms
- Receiving logs: delivery records, invoice matching, credit tracking
- Waste tracking: waste logs, spoilage records, donation tracking
- Recipe management: standardized recipes with ingredient quantities and costs

Step 1.2 -- Product Categorization

Map the inventory landscape:

| Category | SKU Count | Avg Inventory Value | Annual Spend | Supplier Count | Storage Type |
|----------|----------|--------------------|--------------| --------------|-------------|
| Proteins | | | | | Frozen/Refrigerated |
| Produce | | | | | Refrigerated |
| Dairy | | | | | Refrigerated |
| Dry goods | | | | | Ambient |
| Beverages | | | | | Varies |
| Paper/disposables | | | | | Ambient |
| Cleaning/chemicals | | | | | Ambient |

Step 1.3 -- Vendor Landscape

Map the supplier base:
- Approved vendor list: franchisor-mandated vs. operator-selected
- Broadline distributors: Sysco, US Foods, PFG, local/regional
- Specialty suppliers: bakery, seafood, produce, beverage
- Cooperative purchasing group membership
- Direct-from-manufacturer arrangements
- Contract terms: pricing (fixed, market-indexed, cost-plus), delivery schedule, minimums

Step 1.4 -- Franchisor Requirements

Identify system-mandated inventory requirements:
- Approved product list (APL) and required specifications
- Approved supplier list and deviation process
- Mandatory cooperative purchasing participation
- Quality assurance and product testing requirements
- Promotional/LTO product requirements and timelines

============================================================
PHASE 2: PAR LEVEL OPTIMIZATION
============================================================

Optimize inventory par levels to balance availability and waste:

Step 2.1 -- Demand Analysis

Analyze usage patterns for each inventory item:
- Average daily usage by item (units and cost)
- Usage variability: standard deviation, coefficient of variation
- Seasonal demand patterns: holiday, weather, school schedule
- Day-of-week demand patterns
- Promotional and LTO demand spikes
- Trend analysis: growing, stable, or declining demand items

Step 2.2 -- Current Par Assessment

Evaluate existing par levels:
- Current par levels vs. actual usage: are they evidence-based?
- Frequency of stockouts: items unavailable for sale
- Frequency of overstock: items expiring before use
- Order frequency and delivery schedule by vendor
- Lead time analysis: order-to-delivery by vendor and item

Step 2.3 -- Optimal Par Calculation

Calculate optimized par levels:

```
Optimal Par = (Average Daily Usage x Days Between Orders) +
              Safety Stock + Delivery Day Buffer
Safety Stock = Z-score x Standard Deviation of Usage x sqrt(Lead Time Days)
```

Where Z-score corresponds to desired service level:
- 95% service level: Z = 1.65
- 98% service level: Z = 2.05
- 99% service level: Z = 2.33

Adjust for:
- Shelf life constraints: perishables may not sustain high par
- Storage capacity limitations
- Minimum order quantities and case pack sizes
- Volume discount thresholds: break-even analysis for buying larger quantities

Step 2.4 -- Inventory Turn Optimization

Analyze inventory turnover rates:
- Inventory turns by category: (annual COGS for category / average inventory value)
- Industry benchmarks: QSR target 25-35 turns, casual dining 15-25 turns
- Slow-moving inventory identification: turns < 12 = concern
- Dead stock identification: no movement in 30+ days
- Carrying cost calculation: insurance, shrinkage, spoilage, opportunity cost

============================================================
PHASE 3: WASTE TRACKING AND REDUCTION
============================================================

Analyze waste patterns and identify reduction opportunities:

Step 3.1 -- Waste Categorization

Classify waste by type and cause:
- **Spoilage**: expired product, quality degradation
- **Overproduction**: prepared food not sold, batch overruns
- **Trim waste**: unusable portions from preparation
- **Portioning errors**: over-portioning, measurement inconsistency
- **Returned items**: guest complaints, order errors
- **Theft/shrinkage**: unaccounted inventory loss
- **Vendor issues**: damaged deliveries, specification failures

Step 3.2 -- Waste Quantification

Measure waste in dollars and percentage:
- Total waste as % of COGS (industry benchmark: 4-10% for QSR, 5-12% for full-service)
- Waste by category and by menu item
- Waste by shift, day-of-week, and season
- Waste by location (cross-location comparison)
- Trend analysis: is waste improving or worsening?
- Dollar value of waste per month and annualized

Step 3.3 -- Root Cause Analysis

Identify drivers of waste:
- Demand forecasting accuracy vs. prep quantities
- Shelf life management: FIFO compliance, date labeling accuracy
- Prep list optimization: align batch sizes with expected demand
- Receiving inspection: acceptance of sub-spec deliveries
- Storage conditions: temperature compliance, cross-contamination
- Training gaps: portioning, recipe adherence, waste logging compliance

Step 3.4 -- Waste Reduction Program

Design waste reduction initiatives:

| Initiative | Waste Type | Current Waste | Target | Savings/Month | Implementation |
|-----------|-----------|--------------|--------|-------------- |---------------|

Common initiatives:
- Prep list optimization based on demand forecast
- Batch cooking intervals aligned with daypart demand
- Portion control tools: scales, scoops, portion cups
- FIFO enforcement and shelf life labeling
- Menu engineering to use common ingredients across items
- Donation programs for surplus: tax benefit + reduced disposal cost

============================================================
PHASE 4: FOOD COST ANALYSIS
============================================================

Analyze food cost performance and optimization:

Step 4.1 -- Theoretical vs. Actual Food Cost

Calculate the food cost gap:
- **Theoretical food cost**: sum of (menu item recipe cost x quantity sold) / total food revenue
- **Actual food cost**: (beginning inventory + purchases - ending inventory) / food revenue
- **Variance**: actual - theoretical (target: < 2 percentage points)
- Variance by category: which categories have the largest gap?
- Variance trend: growing gap indicates worsening controls

Step 4.2 -- Menu Engineering Matrix

Classify menu items using the BCG-inspired menu matrix:

| Classification | Popularity | Profitability | Action |
|---------------|-----------|--------------|--------|
| Stars | High | High | Maintain prominence, protect margin |
| Plow Horses | High | Low | Re-engineer recipe, adjust price |
| Puzzles | Low | High | Promote, improve placement |
| Dogs | Low | Low | Consider removal or reformulation |

For each item calculate:
- Contribution margin: selling price - food cost
- Menu mix percentage: item sales / total sales
- Contribution margin rank vs. menu mix rank

Step 4.3 -- Pricing Analysis

Evaluate menu pricing effectiveness:
- Price vs. food cost ratio by item (target varies by category)
- Price elasticity indicators: sales volume change after price increases
- Competitive pricing comparison: market basket analysis
- Price anchoring and bundling opportunities
- Delivery menu pricing: typically 15-25% premium to offset commissions

Step 4.4 -- Vendor Cost Management

Analyze purchasing cost optimization:
- Price trend by commodity: proteins, dairy, produce, oil
- Contract vs. market pricing comparison
- Vendor rebate and credit tracking
- Substitute product opportunities: same quality, lower cost
- Order frequency optimization: fewer deliveries = lower delivery costs
- Invoice accuracy audit: overcharges, wrong pricing tier

============================================================
PHASE 5: VENDOR AND COOPERATIVE PURCHASING
============================================================

Evaluate vendor performance and cooperative purchasing:

Step 5.1 -- Vendor Scorecard

Evaluate each vendor on key performance indicators:

| Vendor | On-Time % | Fill Rate % | Quality Score | Price Competitiveness | Credit Resolution |
|--------|-----------|-------------|---------------|---------------------|-------------------|

Step 5.2 -- Vendor Compliance Monitoring

Assess vendor compliance with agreements:
- Delivery window adherence
- Product specification compliance: temperature, weight, quality
- Invoice accuracy rate
- Product recall response capability
- Insurance and food safety certification currency
- Minimum order flexibility

Step 5.3 -- Cooperative Purchasing Evaluation

Analyze cooperative / GPO purchasing benefits:
- Products purchased through cooperative vs. independently
- Price advantage: cooperative pricing vs. independent negotiation
- Rebate programs: volume-based rebates, growth incentives
- Product availability and assortment adequacy
- Administrative burden and ordering process efficiency
- Compliance with franchisor purchasing requirements

Step 5.4 -- Supply Chain Risk

Identify procurement vulnerabilities:
- Single-source items with no approved alternative
- Long lead time items vulnerable to disruption
- Commodity price volatility exposure: unhedged
- Local vs. national supplier dependency
- Seasonal availability gaps for fresh products

============================================================
PHASE 6: REPORT AND OPTIMIZATION PLAN
============================================================

Write the complete analysis to `docs/franchise-inventory-analysis.md`.

Step 6.1 -- Inventory Health Dashboard

Produce an inventory management scorecard:
- Food cost variance: theoretical vs. actual
- Waste percentage and trending
- Inventory turn rates by category
- Stockout frequency
- Vendor performance composite scores

Step 6.2 -- Action Plan

Prioritize inventory optimization actions:
- Immediate: par level adjustments, waste logging enforcement
- Short-term: menu engineering, vendor negotiations, portion controls
- Medium-term: demand forecasting system, inventory automation
- Long-term: cooperative purchasing optimization, supply chain diversification


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),
   note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:
- Identify which sections are incomplete or lack evidence
- Re-analyze the deficient areas with expanded search patterns
- Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:
- Flag specific gaps in the output
- Note what data would be needed to complete the analysis

============================================================
OUTPUT
============================================================

## Franchise Inventory Analysis Complete

- Report: `docs/franchise-inventory-analysis.md`
- Locations analyzed: [count]
- SKUs evaluated: [count]
- Vendors assessed: [count]
- Cost reduction opportunities: [count]

### Summary Table
| Area | Status | Priority |
|------|--------|----------|
| Food Cost Variance | [On Target <2pp/Elevated 2-4pp/Critical >4pp] | [P1/P2/P3] |
| Waste Rate | [Low <5%/Moderate 5-8%/High >8%] | [P1/P2/P3] |
| Par Level Accuracy | [Optimized/Needs Adjustment/Arbitrary] | [P1/P2/P3] |
| Inventory Turns | [Healthy/Below Target/Stagnant] | [P1/P2/P3] |
| Vendor Performance | [Strong/Adequate/Underperforming] | [P1/P2/P3] |

NEXT STEPS:

- "Run `/unit-economics` to model food cost improvements on unit-level profitability."
- "Run `/franchise-benchmarking` to compare food cost performance across locations."
- "Run `/expansion-modeling` to factor supply chain capacity into growth planning."

DO NOT:

- Do NOT recommend changing approved products without noting franchisor approval requirements.
- Do NOT optimize par levels without considering shelf life constraints for perishable items.
- Do NOT treat theoretical food cost as the achievable target -- some variance is operationally normal.
- Do NOT ignore shrinkage/theft when waste logs show low waste but actual food cost is high.
- Do NOT recommend vendor changes without evaluating total cost (price + delivery + quality + reliability).


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /franchise-inventory — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.