# Cursor Optimization TODO (Phased, Token/Cost First)

**Last Updated:** 2026-04-03

Use this checklist as the operational tracker for the optimization program.

## Wave 1 — Dead Refs + Validator Reliability

- [x] Add benchmark script (`scripts/ai/cursor-optimization-benchmark.py`)
- [x] Add skill-reference validator (`scripts/validate-skill-links.py`)
- [x] Add `.cursorignore` drift audit (`scripts/ai/audit-cursorignore.py`)
- [x] Make validators print-only by default (no noisy writes unless `--write-report`)
- [x] Add graceful PyYAML dependency error hints in YAML-based validators
- [x] Update `scripts/maintain-rules.sh` to include skill validation
- [x] Add `make cursor-integrity`
- [x] Add `make cursor-benchmark`
- [x] Add `make cursorignore-audit`
- [x] Update CI workflow to validate skills
- [x] Update CI workflow to check `docs/ai/METADATA_INDEX.json` path
- [x] Fix stale/non-existent rule refs in skills
- [x] Run full integrity checks and confirm passing

## Wave 2 — Rule Overlap + Pointerization

- [x] Enumerate top overlap hotspots from `rule-footprint.py`
- [x] Prioritize overlap reduction candidates by token impact
- [x] Convert long empty-glob rules to thin pointer rules where appropriate
- [x] Merge overlapping comparison rule guidance where safe
- [x] Merge overlapping API guidance where safe
- [x] Rationalize broad `v2/pages/**/*.php` style overlap where safe
- [x] Ensure no loss of critical warnings in base/API routes
- [x] Re-run integrity + benchmark and record deltas

## Wave 3 — SSOT Docs + Archive Cleanup

- [x] Refresh model config doc to capability-based guidance
- [x] Add optimization scorecard doc
- [x] Add golden-task regression doc
- [x] Add rule deprecation policy doc
- [x] Add `.cursorignore` process doc
- [x] Update AI README to include optimization docs
- [x] Consolidate legacy “status/next steps” docs into per-domain changelog pointers
- [x] Add archive index for AI rules/doc history
- [x] Reduce stale examples and duplicate long snippets in maintenance/playbook docs
- [x] Add explicit “hot path reading order” section in routing docs

## Wave 4 — Indexing Scope + Final Report

- [x] Add comments in `.cursorignore` for temporary unignore process
- [x] Run indexing footprint comparison before/after exclusions
- [x] Verify excluded paths do not break core `@` workflows
- [x] Tune additional heavy generated path exclusions (if needed)
- [x] Produce final benchmark snapshot
- [x] Publish final wave summary and KPI deltas

## Regression Checks (Run Every Wave)

- [x] Rule metadata validation
- [x] Rule glob validation
- [x] Rule link validation
- [x] Skill reference validation
- [x] Golden-task review: product page
- [x] Golden-task review: comparison page
- [x] Golden-task review: tools page
- [x] Golden-task review: blog workflow
- [x] Golden-task review: MCP research
- [x] Golden-task review: base component change

## Additional Next-Step Pass (Post-Wave Cleanup)

- [x] Reduce advisory blog JSON overlap where safety allows
- [x] Consolidate dashboard/admin overlap to single runtime router
- [x] Preserve moved guidance in archive docs
- [x] Re-run integrity + benchmark and record deltas

## Continuous Program Setup (Manual Iterative)

- [x] Add canonical continuous program doc
- [x] Add runbook with standardized task/evidence/defer fields
- [x] Add append-only run log
- [x] Add carry-forward backlog
- [x] Add risk register
- [x] Add decisions log
- [x] Add threshold config + volatile-doc freshness config
- [x] Extend benchmark with additional KPIs and delta support
- [x] Add timestamped benchmark snapshot support (`docs/ai/metrics/`)
- [x] Add overlap regression checker script
- [x] Add volatile-doc freshness checker script
- [x] Add optional run report generator + Make target
- [x] Add staged warn-then-gate CI progression logic
- [x] Add CODEOWNERS coverage for optimization-critical paths

## Wave 7 — Rule/Skill Quality Hardening (Safety-First)

- [x] Add rule/skill census inventory script + outputs
- [x] Add warning-first rule-size/no-glob quality checker
- [x] Add warning-first skill-trigger quality checker
- [x] Wire new checks into Makefile and CI staged progression
- [x] Normalize all active skills with scope boundaries + fallback sections
- [x] Pointerize long no-glob rules (`otterly-ai-monitoring`, `partner-pages`, `performance-monitoring`) with archive backlinks
- [x] Fix `find-rules-for-file.py` glob matching for `**` patterns to keep golden-probe routing accurate
- [x] Re-run benchmark and confirm no overlap regression

## Next Steps (Pending)

- [x] Promote CI from stage 1 to stage 2 only after two additional stable manual runs
- [x] Triage and reduce the remaining rule-size/no-glob warnings (currently warning-only by design)
- [ ] Execute first controlled deletion batch only for proven-unused pointerized artifacts with zero required references

## Current Blockers / Carry-Forward

- [ ] Controlled deletion batch is blocked until a verified zero-reference candidate set exists (current archive/rule candidates are still referenced or operational).