# ShiftOps Team Estimation - Quick Reference


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

Quick lookup guide for team size estimation validation bounds, volume factor caps, data source priority, and common debugging scenarios.

## Validation Bounds by Business Type

| Business Type | Min | Max Formula                           | Max Cap |
| ------------- | --- | ------------------------------------- | ------- |
| Restaurant    | 5   | `min(25, max(5, ceil(reviews / 15)))` | 25      |
| Cafe          | 3   | `min(15, max(3, ceil(reviews / 20)))` | 15      |
| Bar           | 3   | `min(25, max(3, ceil(reviews / 18)))` | 25      |
| Store         | 2   | `min(30, max(2, ceil(reviews / 25)))` | 30      |
| Hospital      | 8   | `min(60, max(8, ceil(reviews / 10)))` | 60      |
| Pharmacy      | 3   | `min(20, max(3, ceil(reviews / 15)))` | 20      |
| General       | 3   | `min(30, max(3, ceil(reviews / 20)))` | 30      |

## Volume Factor Caps

| Business Type | Review Count | Max Volume Factor |
| ------------- | ------------ | ----------------- |
| Restaurant    | > 2000       | 4.0x              |
| Restaurant    | ≤ 2000       | 6.0x              |
| All Others    | Any          | 6.0x              |

## Data Source Priority Order

**Both loading screen and report page use same priority:**

1. `cost_savings.team_size_estimate` (from API)
2. `online_presence.team_size_estimate` (from API)
3. Fallback calculation (same function with same parameters)

**This ensures consistent values between loading screen and report page.**

## Code Locations

### PHP Implementations

- **Backend:** `v2/api/shiftops-cost-calculator.php`

  - `estimateTeamSize()`: line 110
  - `getValidationBoundsForTeamSize()`: line 425
  - Safety check: line 246-251
  - Volume factor cap: line 125

- **API:** `v2/api/shiftops.php`
  - `estimateTeamSize()`: line 2047
  - `getValidationBoundsForTeamSize()`: line 2377
  - Safety check: line 2193-2198
  - Volume factor cap: line 2120

### JavaScript Implementations

- **Report Page:** `v2/pages/shiftops-report.php`

  - `estimateTeamSizeFromReviews()`: line 7288
  - `getValidationBounds()`: line 7400
  - Safety check: line 7540-7543
  - Volume factor cap: line 7320
  - Validation logging: line 7545-7548

- **Loading Screen:** `v2/pages/shiftops.php`
  - `estimateTeamSizeEnhanced()`: line 1949
  - `getValidationBounds()`: line 2020
  - Safety check: line 2070-2073
  - Volume factor cap: line 1990
  - Validation logging: line 2075-2078
  - Data priority: line 3145-3159

## Common Debugging Scenarios

### Restaurant Showing 50+ Employees

**Problem:** Restaurant estimate exceeds 25 employees.

**Check:**

1. Verify validation bounds are applied (check console logs)
2. Check if safety check is working (should cap at 25)
3. Verify volume factor cap (should be 4.0x for restaurants with 2000+ reviews)
4. Check location multipliers aren't inflating values

**Solution:** All implementations should cap restaurants at 25. If not, check:

- Validation bounds method returns correct max (25 for restaurants)
- Safety check is applied after location multipliers
- Volume factor cap is correctly applied

### Loading Screen vs Report Mismatch

**Problem:** Different team size values shown on loading screen vs report page.

**Check:**

1. Verify data source priority order matches (both should prioritize `cost_savings.team_size_estimate` first)
2. Check if fallback calculation is used (should be same function)
3. Verify API data is available in localStorage

**Solution:** Both pages should use same priority order:

```javascript
const teamSize = costSavings.team_size_estimate ||
                onlinePresence.team_size_estimate ||
                estimateTeamSizeEnhanced(...);
```

### Very High Review Counts (5000+)

**Problem:** Restaurant with 5000+ reviews showing unrealistic estimate.

**Check:**

1. Volume factor cap should be 4.0x (not 6.0x) for restaurants with 2000+ reviews
2. Validation bounds should cap at 25
3. Safety check should ensure final value doesn't exceed 25

**Solution:**

- Volume factor: `maxVolumeCap = (reviewCount > 2000 && primaryType === 'restaurant') ? 4.0 : 6.0`
- Validation bounds: `max: min(25, max(5, ceil(reviewCount / 15)))`
- Safety check: `if (primaryType === 'restaurant' && estimatedTeam > 25) { estimatedTeam = 25; }`

### Validation Bounds Not Applied

**Problem:** Team size exceeds maximum bounds.

**Check:**

1. Verify `getValidationBounds()` returns correct max value
2. Check if bounds are applied after all calculations
3. Verify safety check is applied after location multipliers

**Solution:** Bounds should be applied in this order:

1. Calculate estimated team size
2. Apply location multipliers
3. Apply validation bounds
4. Apply safety check (for restaurants)

### Console Logging Not Showing

**Problem:** Validation logging not appearing in console.

**Check:**

1. Verify logging code is present (JavaScript implementations only)
2. Check if bounds were actually applied (logging only shows when bounds change value)
3. Verify browser console is open

**Solution:** Logging appears when:

```javascript
if (beforeBounds !== estimatedTeam) {
  console.log(
    `🔧 Team size validation applied: ${beforeBounds.toFixed(
      1
    )} → ${estimatedTeam} (bounds: ${bounds.min}-${
      bounds.max
    }, type: ${primaryType}, reviews: ${reviewCount})`
  );
}
```

## Factor Weights

| Factor             | Weight |
| ------------------ | ------ |
| Customer Volume    | 35%    |
| Operating Hours    | 25%    |
| Service Complexity | 20%    |
| Quality/Scale      | 15%    |
| Review Velocity    | 5%     |

## Industry Benchmarks

### Reviews Per Employee Per Month

| Industry   | Reviews/Employee/Month |
| ---------- | ---------------------- |
| Restaurant | 10                     |
| Cafe       | 6                      |
| Bar        | 8                      |
| Store      | 4                      |
| Hospital   | 12                     |
| Pharmacy   | 7                      |
| General    | 6                      |

## Related Documentation

- `TEAM_ESTIMATION_CHANGELOG.md` - Complete changelog of all changes
- `TEAM_ESTIMATION_CURRENT_LOGIC.md` - Detailed implementation documentation
- `TEAM_ESTIMATION_ENHANCED_MODEL.md` - Enhanced model design
- `TEAM_ESTIMATION_SUMMARY.md` - High-level summary