Star Rating Calculation Guide
How rep ratings work, how they're calculated, and how to override them
Overview
Every IC Rep receives a 0–5 star rating that reflects their real-world performance across scheduled visits, on-time completion, report compliance, and photo quality. The system calculates a score automatically from call report data and AI scans. Regional Managers and Admins can manually overridethe calculated score at any time — the override takes precedence and the system score becomes a visible suggestion.
How the Score is Calculated
The system-calculated score is a weighted average of five metrics, each converted to a 0–5 scale, minus a flag penalty:
On-Time Completion
Percentage of assigned visits completed and submitted without late flags or human review triggers.
Compliance Score
Average AI compliance score across all submitted call reports (planogram accuracy, correct answers, required fields).
Photo Quality
Average AI photo quality score — checks for clarity, relevance, duplicates, and whether photos show the required before/after state.
Visit Completion Rate
Ratio of completed/submitted reports to total assigned visits. Missed or abandoned visits lower this metric.
On-Site Check-In
Percentage of assignments where the rep checked in on-site (check_in_time recorded). Validating physical presence is critical — not checking in directly damages the overall rating.
Flag Penalty Deduction
Each flagged report (AI duplicates, irrelevant photos, human review required, or needs-correction status) deducts 0.25 stars from the calculated score, capped at a maximum of 1.5 stars.
FORMULA
calculatedScore =
(onTimeScore × 0.25) +
(complianceScore × 0.2) +
(photoQualityScore × 0.15) +
(completionScore × 0.15) − flagDeductionManual Override & Adjustment
Who can override?
- Regional Managers — can rate any rep in their workgroup
- Admins — can rate any rep in the system
- Reviewers — can rate reps during quality review
How to override
- Open the rep's profile page (
/rep-profile/:id) - Find the "Your RM Rating" section in the Performance & Rating card
- Click the desired star (1–5) — the rating saves instantly to the rep's UserProfile
- An AuditLog entry is automatically created recording the old value, new value, who made the change, and when
- The override takes precedence immediately — the system-calculated score is shown as a reference below the override badge
When to override
- Exceptional performance not captured by AI (e.g., short-notice coverage, going above and beyond)
- Correcting an unfairly low AI score due to a known scanning error
- Penalizing a rep for behavior not visible in visit data (e.g., unprofessional conduct, no-shows without formal flags)
- Resetting a rating — to remove an override, contact an admin to clear the
rm_ratingfield
Activity & Adjustment Log
Every rating change — whether a new rating, an adjustment, or a reset — is recorded in the AuditLog entity. Each entry captures:
Date & Time
When the action occurred
Action
e.g., 'Manual Rating Adjustment'
Old → New Value
Previous and new star rating
Details
Human-readable summary of the change
Actor
Who made the change (Admin, RM, or System)
Target User
Which rep the action was about
The log appears at the bottom of each rep's profile page and can be exported as CSV for compliance records.
Where the Data Comes From
status, ai_compliance_score, ai_photo_score, human_review_required, ai_irrelevant_photos, ai_has_duplicates
Core visit metrics — compliance, photo quality, flags
status, scheduled_date, check_in_time, check_out_time
Visit scheduling, on-time tracking, completion status
rm_rating, rm_rating_by, rm_rating_at
Manual override storage — the authoritative rating field
action, old_value, new_value, details, target_user_id
Complete history of every rating adjustment