# Team Estimation Improvements Applied


**Last Updated:** 2025-11-20

## Summary

After comprehensive testing and analysis, improvements were identified and implemented to address underestimation issues, particularly for larger businesses.

## Improvements Implemented

### 1. Scaled Base Staffing

**Problem:** Fixed base staffing (e.g., 5 for restaurants) didn't account for business size, causing underestimation for larger businesses.

**Solution:** Implemented review-count-based scaling:

**Restaurants:**

- Small (0-50 reviews): Base 5
- Medium (50-200 reviews): Base 7
- Large (200-1000 reviews): Base 10
- Very Large (1000+ reviews): Base 15

**Cafes:**

- Small (0-100 reviews): Base 3
- Medium (100-500 reviews): Base 4
- Large (500+ reviews): Base 6

**Bars:**

- Small (0-100 reviews): Base 3
- Medium (100-500 reviews): Base 4
- Large (500+ reviews): Base 6

**Stores:**

- Small (0-200 reviews): Base 2
- Medium (200-1000 reviews): Base 4
- Large (1000+ reviews): Base 8

**Hospitals:**

- Small (0-500 reviews): Base 8
- Large (500+ reviews): Base 12

**Pharmacies:**

- Small (0-200 reviews): Base 3
- Large (200+ reviews): Base 5

### 2. Increased Volume Factor Cap

**Problem:** Volume factor capped at 4.0x was too restrictive for very high review counts.

**Solution:** Increased cap from 4.0x to 6.0x.

**Impact:** Allows better scaling for businesses with 2000+ reviews.

### 3. Improved Maximum Bounds

**Problem:** Maximum bounds were too restrictive (e.g., reviews/15 for restaurants capped at ~333 for 5000 reviews, but estimate was only 13).

**Solution:** Implemented better maximum bounds with industry-specific caps:

**Restaurants:**

- Formula: `min(50, max(5, ceil(reviews / 10)))`
- Cap: 50 staff maximum

**Cafes:**

- Formula: `min(20, max(3, ceil(reviews / 15)))`
- Cap: 20 staff maximum

**Bars:**

- Formula: `min(25, max(3, ceil(reviews / 12)))`
- Cap: 25 staff maximum

**Stores:**

- Formula: `min(30, max(2, ceil(reviews / 20)))`
- Cap: 30 staff maximum

**Hospitals:**

- Formula: `min(60, max(8, ceil(reviews / 8)))`
- Cap: 60 staff maximum

**Pharmacies:**

- Formula: `min(20, max(3, ceil(reviews / 12)))`
- Cap: 20 staff maximum

## Test Results

### Before Improvements

- **Accuracy:** 17 / 26 (65.4%) within expected range
- **Mean Estimate:** 5.58
- **Median Estimate:** 5.00
- **Range:** 2 - 13

### After Improvements

- **Accuracy:** 23 / 26 (88.5%) within expected range
- **Mean Estimate:** 10.04
- **Median Estimate:** 6.50
- **Range:** 2 - 49

### Improvement by Category

**Restaurants:**

- Before: 2 / 6 (33.3%) within expected
- After: 5 / 6 (83.3%) within expected
- **Improvement:** +50%

**Cafes:**

- Before: 3 / 3 (100%) within expected
- After: 2 / 3 (66.7%) within expected
- **Note:** One case (Popular City Cafe) now slightly overestimates (9 vs expected 4-8)

**Bars:**

- Before: 1 / 2 (50%) within expected
- After: 1 / 2 (50%) within expected
- **Note:** Popular Nightclub still slightly underestimates (5 vs expected 6-12)

**Retail:**

- Before: 2 / 3 (66.7%) within expected
- After: 3 / 3 (100%) within expected
- **Improvement:** +33.3%

**Healthcare:**

- Before: 2 / 2 (100%) within expected
- After: 2 / 2 (100%) within expected
- **Status:** Maintained

**Edge Cases:**

- Before: 7 / 10 (70%) within expected
- After: 10 / 10 (100%) within expected
- **Improvement:** +30%

## Key Cases Fixed

### Very Large Restaurant (2000 reviews)

- Before: 12 (expected 25-50) ✗
- After: 36 (expected 25-50) ✓
- **Fixed:** Now properly estimates large operations

### Extreme High Reviews (5000 reviews)

- Before: 13 (expected 30-50) ✗
- After: 49 (expected 30-50) ✓
- **Fixed:** Now handles extreme cases correctly

### Large Fine Dining Restaurant (800 reviews)

- Before: 8 (expected 15-30) ✗
- After: 16 (expected 15-30) ✓
- **Fixed:** Now estimates fine dining correctly

### Fast Casual Chain Restaurant (500 reviews)

- Before: 7 (expected 10-20) ✗
- After: 15 (expected 10-20) ✓
- **Fixed:** Now estimates chain restaurants correctly

### Many Service Types (300 reviews, 7 services)

- Before: 7 (expected 8-20) ✗
- After: 14 (expected 8-20) ✓
- **Fixed:** Now accounts for service complexity better

## Files Modified

1. **v2/api/shiftops.php**

   - Updated `estimateTeamSize()` method
   - Implemented scaled base staffing
   - Increased volume factor cap to 6.0x
   - Improved maximum bounds

2. **v2/api/shiftops-cost-calculator.php**

   - Updated `estimateTeamSize()` method
   - Same improvements as Analyzer

3. **v2/pages/shiftops-report.php**

   - Updated `estimateTeamSizeFromReviews()` function
   - Same improvements as PHP implementations

4. **v2/pages/shiftops.php**
   - Updated `estimateTeamSizeEnhanced()` function
   - Same improvements as other implementations

## Consistency

All implementations now use:

- Same scaled base staffing ranges
- Same volume factor cap (6.0x)
- Same improved maximum bounds
- Same factor weights (35%, 25%, 20%, 15%, 5%)

## Latest Fixes (January 2025)

### Validation Bounds & Realism Fixes

**Problem:** Restaurant team size estimates were showing unrealistic values (50+ employees) for single-location restaurants.

**Changes:**

1. **Validation Bounds Fixes:**

   - All implementations: Restaurant cap set to **25** (was 50 or unbounded)
   - All business types: Added realistic caps (cafe: 15, bar: 25, store: 30, hospital: 60, pharmacy: 20)

2. **Volume Factor Cap Reduction:**

   - Restaurants with 2000+ reviews: Cap reduced from 6.0x to **4.0x**
   - Other businesses: Remain at 6.0x cap

3. **Safety Checks:**

   - Additional validation after location multipliers to ensure restaurants don't exceed 25
   - Applied in all implementations

4. **Data Consistency:**

   - Loading screen and report page now use same priority order
   - Both prioritize `cost_savings.team_size_estimate` first

5. **Validation Logging:**
   - Console logging when validation bounds are applied (JavaScript implementations)

**Impact:**

- Restaurant with 5018 reviews: Estimated 25 employees (was 50+, now realistic)
- Consistent values between loading screen and report page
- Console logging shows when and why validation bounds are applied

**Files Modified:**

- `v2/api/shiftops-cost-calculator.php` (line 425-456, 246-251, 125)
- `v2/api/shiftops.php` (line 2377-2408, 2193-2198, 2120)
- `v2/pages/shiftops-report.php` (line 7400-7431, 7540-7543, 7320)
- `v2/pages/shiftops.php` (line 2020-2051, 2070-2073, 1990, 3145-3159)

**Documentation:** See `TEAM_ESTIMATION_CHANGELOG.md` for complete details.

## Remaining Issues

### Minor Overestimation

**Popular City Cafe (600 reviews):**

- Estimate: 9
- Expected: 4-8
- **Note:** Slightly overestimates, but within reasonable range

**Popular Nightclub (400 reviews):**

- Estimate: 5
- Expected: 6-12
- **Note:** Still slightly underestimates, but improved from 4

### Recommendations

1. **Monitor Production:** Track actual vs estimated team sizes in production
2. **Collect Feedback:** Gather user feedback on estimate accuracy
3. **Refine Further:** Consider adjusting bounds for cafes/bars if needed
4. **Consider ML:** Evaluate machine learning approaches if training data becomes available

## Conclusion

The improvements successfully address the main underestimation issues, particularly for larger businesses. Accuracy improved from 65.4% to 88.5%, with significant improvements for restaurants and edge cases. The scaled base staffing approach proves effective for handling businesses of different sizes.

The latest fixes (January 2025) address validation bounds inconsistencies and ensure realistic team size estimates for all business types, with special attention to restaurants which are now capped at 25 employees.