# RateRight Ratings System Specification

## Overview
RateRight needs a simple, trustworthy rating system that helps construction workers and contractors make informed decisions about who they work with. This system should be easy to understand, difficult to game, and provide meaningful feedback without being overly complex.

## 1. Rating Dimensions

### For Contractors (rated by workers):
1. **Payment Promptness** (1-5 stars)
   - 5: Paid immediately upon completion
   - 3: Paid within agreed timeframe
   - 1: Delayed payment or non-payment

2. **Communication** (1-5 stars)
   - Clear instructions, responsive to questions
   - Professional tone and timely responses

3. **Job Accuracy** (1-5 stars)
   - Job description matches actual work
   - No unexpected requirements or scope changes

4. **Work Environment** (1-5 stars)
   - Safe working conditions
   - Proper tools/equipment provided
   - Respectful treatment

### For Workers (rated by contractors):
1. **Skill Level** (1-5 stars)
   - Quality of work performed
   - Technical competence
   - Attention to detail

2. **Punctuality** (1-5 stars)
   - Arrives on time
   - Completes work within agreed timeframe

3. **Professionalism** (1-5 stars)
   - Attitude and behavior
   - Communication skills
   - Respect for property and people

4. **Reliability** (1-5 stars)
   - Shows up as agreed
   - Completes commitments
   - Doesn't abandon jobs

## 2. Rating Flow

### When to Prompt:
- **24 hours after job completion** - Send notification to rate
- **Reminder at 72 hours** if not rated
- **Rating window closes after 7 days**
- **Both parties must rate before either rating is visible** (double-blind system)

### Making it Easy:
- One-tap rating from notification
- Optional comment field (280 characters max)
- Quick tags for common issues (e.g., "Late payment", "Excellent quality")
- Pre-filled positive options for 5-star ratings

## 3. Display Strategy

### Overall Rating:
- **5-star system** with half-star increments
- **Weighted average** of last 20 ratings (more recent = higher weight)
- **Minimum 5 ratings** before displaying public score
- Show "New User" badge if fewer than 5 ratings

### Additional Display Elements:
- **Response rate**: Percentage of rating requests answered
- **Completion rate**: Jobs completed vs. accepted
- **Badge system** for milestones:
  - "Reliable Payer" (95%+ payment ratings)
  - "Skilled Worker" (95%+ skill ratings)
  - "Top Communicator" (95%+ communication)
- **Trend indicator**: Arrow showing if rating is improving/declining

### Profile Display:
```
John Smith (Contractor)
★★★★☆ 4.3 (23 reviews)
💬 100% response rate | ✅ 95% completion
🏆 Reliable Payer | 📈 Improving
```

## 4. Anti-Gaming Measures

### Verification Requirements:
- **Phone number verification** required before rating
- **Job completion verification** via check-in/check-out system
- **Payment verification** for contractor ratings

### Pattern Detection:
- **Unusual rating patterns** trigger review (e.g., sudden influx of negative ratings)
- **Retaliatory rating detection** - if both parties rate 1-star within 1 hour
- **Circle trading** - detecting users who rate each other frequently

### Rating Limits:
- **Maximum 3 unrated jobs** before requiring ratings
- **Cannot rate same person** more than once per 30 days
- **Weight first-time ratings higher** than repeat ratings

### Dispute Process:
- **48-hour cooling off** period for ratings under 3 stars
- **Mediation option** for disputed ratings
- **Ratings can be amended** if both parties agree
- **Public response** option to ratings (with character limit)

## 5. Edge Cases

### New Users:
- Show "New to RateRight" badge prominently
- **First job bonus**: Higher visibility for new workers
- **Mentorship program**: Pair new contractors with experienced ones
- **Starter rating**: 4.0 default for first 3 jobs (not displayed)

### Disputes:
- **Neutral ratings** (3 stars) excluded from public average during dispute
- **Dispute resolution** affects rating visibility
- **Arbitration team** for complex cases
- **Strike system** for false disputes

### Job Abandonment:
- **Automatic 1-star** for no-shows (with verification)
- **Appeal process** for legitimate emergencies
- **Strike system**: 3 strikes = account review

### Long-term Inactivity:
- **Ratings expire** after 24 months of inactivity
- **Re-verification** required after 6 months away
- **Fresh start** option after 12 months (keep account, reset ratings)

## 6. Implementation Plan

### Phase 1 (MVP - Week 1-2):
- Basic 5-star rating system
- Simple average calculation
- Email notifications for ratings
- Minimum 3 ratings before display

### Phase 2 (Week 3-4):
- In-app rating notifications
- Comment fields
- Basic badge system
- Rating history view

### Phase 3 (Week 5-6):
- Anti-gaming pattern detection
- Dispute process
- Weighted averages
- Response rate tracking

### Phase 4 (Week 7-8):
- Advanced analytics
- Trend indicators
- Public response feature
- Integration with payment system

### Technical Considerations:
- **Database design**: Separate tables for ratings, comments, disputes
- **API endpoints**: POST /rate, GET /ratings/{userId}, PUT /dispute
- **Real-time updates**: WebSocket for live rating changes
- **Caching**: Redis for frequently accessed ratings
- **Analytics**: Daily aggregation jobs for statistics

### Success Metrics:
- **Rating completion rate** > 70%
- **Dispute rate** < 5%
- **User satisfaction** with rating system > 4.0
- **Reduction in payment disputes** > 30%

## Future Enhancements
- **Video testimonials** for top-rated users
- **Skill certifications** integrated with ratings
- **Insurance discounts** for highly-rated contractors
- **AI-powered matching** based on rating compatibility
- **Blockchain verification** for critical ratings

## Key Principles
1. **Simplicity first** - Easy to understand and use
2. **Trust through transparency** - Clear how ratings work
3. **Fairness for all** - Protect against abuse
4. **Continuous improvement** - Iterate based on feedback
5. **Industry-specific** - Tailored for construction needs