# Performance Monitoring (Archived Full Guidance)

This archive preserves the previously embedded long-form guidance from `.cursor/rules/performance-monitoring.mdc`.

# Performance Monitoring (Pointer Rule)

Use this rule when working on performance dashboards, PSI ingestion, or optimization triage workflows.

## Fast Guardrails

1. Preserve Core Web Vitals focus (`LCP`, `INP/FID`, `CLS`) and avoid regressions on edited pages.
2. Prefer incremental analysis for routine checks; use full sweeps for scheduled/major audits.
3. Keep optimization recommendations actionable and traceable to affected URLs/components.

## Canonical References

- `docs/performance/README.md`
- `docs/ai/CURSOR_INDEXING_FOOTPRINT_REPORT.md` (indexing/cost context)
- `docs/ai/RULE_TO_DOC_MAPPING.md`

Do not duplicate long procedural content in this rule; update the referenced docs instead.
[
    'id' => 'task_abc123',
    'task_id' => 'task_abc123',
    'title' => 'Eliminate render-blocking resources',
    'description' => '...',
    'status' => 'pending',
    'priority' => 85,
    'category' => 'assets',
    'assigned_to' => 'dev@ordio.com',
    'due_date' => '2025-12-15',
    'created_at' => '2025-11-19T10:00:00+00:00',
    'pages_affected' => ['https://www.ordio.com/', ...],
    'affected_page_count' => 15,
    'metadata' => [
        'source' => 'recommendation',
        'recommendation_id' => 'render-blocking-resources',
        'original_topIssue' => [...]
    ]
]
```

### Implementation Patterns

**Mapping Function** (`mapTopIssueToRecommendation`):

- Validates input data
- Generates ID from title if missing
- Maps impact to effort estimate
- Builds comprehensive description with metrics
- Determines category from title/ID keywords
- Provides defaults for missing fields

**Task Creation Function** (`createBulkTasksFromIssue`):

- Validates `topIssue` data
- Maps to recommendation format
- Handles `per_url` vs `aggregated` modes
- Creates tasks via `createTaskFromRecommendation()`
- Returns results with success/error tracking

**Duplicate Detection** (`findDuplicateTask`):

- Checks for existing tasks with same title and status (pending/in_progress)
- Prevents duplicate task creation
- Logs duplicate attempts

**API Endpoints**:

- `POST /create-from-recommendation`: Single task creation
- `POST /create-bulk`: Bulk task creation (max 20 issues)
- Both validate input, check for duplicates, return detailed results

### UI/UX Patterns

**Modal Forms:**

- Clear labels and help text
- Required field indicators
- Validation feedback
- Loading states during API calls
- Success/error notifications via toast system

**Accessibility:**

- ARIA labels on all interactive elements
- Keyboard navigation (Tab, Enter, Escape)
- Focus management
- Screen reader friendly

**Error Handling:**

- User-friendly error messages
- Partial success handling for bulk operations
- Retry logic for transient failures
- Clear indication of what succeeded/failed

## Best Practices

1. **Monitor Regularly**: Check dashboard weekly
2. **Track Trends**: Watch for regressions over time
3. **Prioritize High-Traffic Pages**: Focus optimization efforts
4. **Test Before/After**: Always verify improvements
5. **Document Changes**: Note what optimizations were made
6. **Create Tasks Systematically**: Use aggregated mode for systematic fixes, per_url for page-specific work
7. **Prevent Duplicates**: Always check for existing tasks before creating new ones
8. **Validate Input**: Ensure all required fields are present and valid before task creation

## Files and Locations

- **Config**: `v2/config/pagespeed-insights.php`
- **API Client**: `v2/api/pagespeed-analyze.php`
- **Sitemap Parser**: `v2/helpers/sitemap-parser.php`
- **Recommendations**: `v2/helpers/performance-recommendations.php`
- **Dashboard**: `v2/pages/performance-dashboard.php`
- **Cron Job**: `v2/cron/performance-analysis.php`
- **Batch Script**: `v2/scripts/analyze-all-pages.php`
- **Data**: `v2/data/performance/`

## API Usage

- **Free tier**: 25,000 requests/day
- **Full analysis**: ~234 requests (117 URLs × 2 strategies)
- **Can run**: ~100 full analyses per day
- **Rate limit tracking**: Automatic in `rate-limit.json`

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.

**Key Documentation:**

- [docs/performance/](../../docs/performance/) - `docs/performance/` - Performance monitoring docs (if exists)