# ShiftOps Development Checklist


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

## Before Starting Development

- [ ] Read `SHIFTOPS_DEVELOPER_GUIDE.md` for setup and workflow
- [ ] Review `SHIFTOPS_ARCHITECTURE.md` for system overview
- [ ] Check `.cursor/rules/shiftops-backend.mdc` and `.cursor/rules/shiftops-frontend.mdc` for coding standards
- [ ] Review `SHIFTOPS_ai/QUICK_REFERENCE.md` for common patterns
- [ ] Check `SHIFTOPS_COMPONENTS.md` for class and method documentation
- [ ] Review `SHIFTOPS_DATA_STRUCTURES.md` for data formats
- [ ] Check existing code for similar functionality
- [ ] Review related files for dependencies

## When Adding New Features

### Planning

- [ ] Document feature requirements
- [ ] Identify affected files
- [ ] Check for existing similar functionality
- [ ] Plan data structure changes
- [ ] Consider caching strategy
- [ ] Plan error handling

### Implementation

- [ ] Follow existing code patterns
- [ ] Use consistent naming conventions
- [ ] Add error handling (try-catch)
- [ ] Add error logging
- [ ] Validate input data
- [ ] Handle edge cases
- [ ] Add cache support (if applicable)

### Testing

- [ ] Test with valid data
- [ ] Test with invalid data
- [ ] Test with missing data
- [ ] Test error scenarios
- [ ] Test cache behavior
- [ ] Test performance impact
- [ ] Test in both essential and enhanced modes

### Documentation

- [ ] Update architecture docs (`SHIFTOPS_ARCHITECTURE.md`) if needed
- [ ] Update API docs (`SHIFTOPS_API_DOCUMENTATION.md`) if new endpoints
- [ ] Update components docs (`SHIFTOPS_COMPONENTS.md`) if new classes/methods
- [ ] Update data structures (`SHIFTOPS_DATA_STRUCTURES.md`) if new formats
- [ ] Update quick reference (`SHIFTOPS_ai/QUICK_REFERENCE.md`) if new patterns
- [ ] Update developer guide (`SHIFTOPS_DEVELOPER_GUIDE.md`) if workflow changes
- [ ] Add code comments for complex logic
- [ ] Update troubleshooting guide (`SHIFTOPS_TROUBLESHOOTING.md`) if new issues

## When Modifying Existing Features

### Before Changes

- [ ] Review current implementation
- [ ] Check for dependencies
- [ ] Review test cases (if any)
- [ ] Check cache impact
- [ ] Review error handling

### During Changes

- [ ] Maintain backward compatibility
- [ ] Update related code
- [ ] Update cache keys (if data structure changes)
- [ ] Test existing functionality
- [ ] Test new functionality

### After Changes

- [ ] Test all affected features
- [ ] Clear cache if needed
- [ ] Update documentation
- [ ] Check for breaking changes
- [ ] Review error logs

## When Fixing Bugs

### Investigation

- [ ] Check error logs (`logs/shiftops-debug.log`)
- [ ] Reproduce the issue
- [ ] Identify root cause
- [ ] Check related code
- [ ] Review recent changes

### Fix

- [ ] Fix the root cause (not symptoms)
- [ ] Add error handling if missing
- [ ] Add logging for debugging
- [ ] Test the fix
- [ ] Test edge cases

### Verification

- [ ] Test fix with original issue
- [ ] Test related functionality
- [ ] Check error logs
- [ ] Update documentation if needed
- [ ] Add to troubleshooting guide if common

## When Working with External APIs

### Google Places API

- [ ] Check API quota limits
- [ ] Handle rate limiting
- [ ] Add error fallbacks
- [ ] Cache results when possible
- [ ] Validate API responses

### Weather API

- [ ] Handle connection timeouts
- [ ] Use fallback weather data
- [ ] Validate coordinates
- [ ] Handle API errors gracefully

### Holiday API

- [ ] Handle missing holidays
- [ ] Use fallback holiday data
- [ ] Validate country codes
- [ ] Handle regional holidays

### HubSpot API

- [ ] Respect rate limits (100/10s)
- [ ] Handle API errors
- [ ] Log submissions
- [ ] Validate form data
- [ ] Test with real form ID

## When Working with Scoring

### Scoring Algorithm

- [ ] Verify pillar score ranges (0-20)
- [ ] Check total score calculation
- [ ] Test customer boost logic
- [ ] Verify data completeness multiplier
- [ ] Test score adjustment logic
- [ ] Verify pillar scores sum to total

### Customer Matching

- [ ] Test exact match
- [ ] Test fuzzy match
- [ ] Test domain match
- [ ] Test prefix match
- [ ] Verify confidence scores
- [ ] Test with edge cases (typos, variations)

### Cost Calculations

- [ ] Verify team size estimation
- [ ] Check wage data accuracy
- [ ] Test savings calculations
- [ ] Verify ROI calculations
- [ ] Check break-even calculations
- [ ] Test with different industries

## When Working with Caching

### Cache Implementation

- [ ] Verify cache key generation
- [ ] Check cache directory permissions
- [ ] Test cache TTL (1 hour)
- [ ] Test cache expiration
- [ ] Test cache invalidation
- [ ] Verify cache cleanup

### Cache Testing

- [ ] Test cache hit
- [ ] Test cache miss
- [ ] Test cache expiration
- [ ] Test cache corruption handling
- [ ] Test cache performance

## When Working with Frontend

### Data Flow

- [ ] Test localStorage storage
- [ ] Test localStorage retrieval
- [ ] Test data optimization
- [ ] Verify data format
- [ ] Test error handling

### UI/UX

- [ ] Test form validation
- [ ] Test gated content
- [ ] Test PDF export
- [ ] Test responsive design
- [ ] Test accessibility
- [ ] Test loading states

### Integration

- [ ] Test API calls
- [ ] Test error handling
- [ ] Test fallback data
- [ ] Test data refresh
- [ ] Test HubSpot submission

## Code Quality Checklist

### PHP

- [ ] Follow naming conventions
- [ ] Add type hints where possible
- [ ] Add docblocks for complex functions
- [ ] Use try-catch for error handling
- [ ] Log errors appropriately
- [ ] Validate input data
- [ ] Sanitize output data

### JavaScript

- [ ] Use async/await for async operations
- [ ] Handle errors gracefully
- [ ] Validate data before storing
- [ ] Optimize localStorage usage
- [ ] Add error logging
- [ ] Test browser compatibility

### General

- [ ] Remove debug code
- [ ] Remove commented code
- [ ] Check for code duplication
- [ ] Optimize performance
- [ ] Check memory usage
- [ ] Review error messages

## Before Committing

- [ ] Test all functionality
- [ ] Check for linting errors
- [ ] Review error logs
- [ ] Update documentation
- [ ] Clear cache if needed
- [ ] Test in both modes
- [ ] Verify no breaking changes
- [ ] Check performance impact

## Deployment Checklist

- [ ] Test on localhost
- [ ] Check file permissions
- [ ] Verify cache directory exists
- [ ] Verify log directory exists
- [ ] Check API keys are set
- [ ] Test external API connections
- [ ] Clear old cache files
- [ ] Monitor error logs
- [ ] Test end-to-end flow

## Performance Checklist

- [ ] Essential mode < 2 seconds
- [ ] Enhanced mode 3-5 seconds
- [ ] Cache hits < 100ms
- [ ] Page load < 1 second
- [ ] Check API response times
- [ ] Monitor cache hit rates
- [ ] Check memory usage
- [ ] Review file I/O operations

## Security Checklist

- [ ] Validate all input
- [ ] Sanitize output
- [ ] Check API key security
- [ ] Review error messages (no sensitive data)
- [ ] Check file permissions
- [ ] Review SQL injection risks (if any)
- [ ] Check XSS prevention
- [ ] Review CSRF protection (if forms)

## Documentation Checklist

- [ ] Update architecture docs (`SHIFTOPS_ARCHITECTURE.md`)
- [ ] Update API docs (`SHIFTOPS_API_DOCUMENTATION.md`)
- [ ] Update components docs (`SHIFTOPS_COMPONENTS.md`)
- [ ] Update data structures (`SHIFTOPS_DATA_STRUCTURES.md`)
- [ ] Update quick reference (`SHIFTOPS_ai/QUICK_REFERENCE.md`)
- [ ] Update developer guide (`SHIFTOPS_DEVELOPER_GUIDE.md`) if workflow changes
- [ ] Update troubleshooting guide (`SHIFTOPS_TROUBLESHOOTING.md`)
- [ ] Add code comments
- [ ] Update examples
- [ ] Review documentation accuracy

## Common Tasks

### Adding New Scoring Factor

1. [ ] Add to pillar calculation method
2. [ ] Update raw score calculation
3. [ ] Test with various businesses
4. [ ] Verify score ranges
5. [ ] Update documentation

### Adding New Recommendation

1. [ ] Add to recommendations engine
2. [ ] Set priority and category
3. [ ] Add Ordio feature reference
4. [ ] Test recommendation generation
5. [ ] Update documentation

### Adding New External API

1. [ ] Add API key to config
2. [ ] Add error handling
3. [ ] Add fallback data
4. [ ] Add caching if appropriate
5. [ ] Test API integration
6. [ ] Update documentation

### Modifying Cache Strategy

1. [ ] Update cache key generation
2. [ ] Update cache TTL
3. [ ] Test cache behavior
4. [ ] Clear old cache files
5. [ ] Update documentation