# Cursor Optimization Runbook

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

Use this runbook for each manual optimization run.

## Run Header (fill first)

- Run ID: `OPT-RUN-YYYY-MM-DD-NN`
- Slice: `A` or `B`
- State: `planned` -> `running` -> `done|blocked|rolled-back`
- Owner:
- Start time (UTC):

## Standardized Task Checklist Template

- [ ] Task ID:
- [ ] Description:
- [ ] Evidence required:
- [ ] Status: `done` / `deferred`
- [ ] If deferred: not done / why deferred

## Pre-Run Commands (all runs)

1. `make cursor-integrity`
2. `make cursor-benchmark`
3. `make cursorignore-audit`
4. `python3 scripts/ai/rule-footprint.py --top 40`

## Slice A Checklist (AI core)

1. Run representative probes with `scripts/find-rules-for-file.py` (product/compare/tools/blog/base/API).
2. Confirm exactly one `alwaysApply:true` rule (`global.mdc`).
3. Identify overlap hotspots and rank by token impact x risk.
4. Flag long rules above soft cap for pointerization review.
5. Flag empty-glob long rules for pointer conversion review.
6. Validate skill refs and cross-links to archive docs.
7. Propose reductions only for advisory/non-critical routes first.
8. Preserve security/base guardrails as non-negotiable.
9. If ambiguity remains, defer to backlog ticket instead of risky merge.

## Slice B Checklist (broader docs/process)

1. `make docs-inventory` and docs redundancy check.
2. Review docs totals/category drift and top redundancy patterns.
3. Consolidate duplicate status/next-steps/final-status docs via SSOT + pointers.
4. Move stale historical docs to archive index (no destructive deletion).
5. Update archive backlinks and pointer docs.
6. Refresh hot-path reading order in high-traffic docs where needed.
7. Replace stale version statements with capability-based guidance.
8. Add/update explicit freshness notes in volatile docs.
9. Keep generated heavy artifacts excluded unless explicitly needed.
10. Validate core `@` workflows still function with current `.cursorignore`.

## Stop Conditions (mandatory)

Stop immediately and mark run `blocked` or `rolled-back` if:

1. Overlap KPI exceeds threshold without approved exception
2. Golden probe routing degrades
3. Broken references appear
4. Safety/security route guidance is weakened

## Carry-Forward Protocol

For each blocked/deferred item, create backlog record with:

- Backlog ID
- Run ID source
- Root-cause hypothesis
- Required preconditions
- Risk level
- Next review date
- Proposed owner

## End-of-Run Requirements

1. Update `CURSOR_OPTIMIZATION_RUN_LOG.md`
2. Update `CURSOR_OPTIMIZATION_SCORECARD.md`
3. Update `CURSOR_OPTIMIZATION_BACKLOG.md`
4. Add decision entry if thresholds/policies changed
5. (Optional) Generate report:
   - `make cursor-opt-run-report RUN_ID=OPT-RUN-YYYY-MM-DD-NN SLICE=A`
6. Add a one-paragraph **What changed this run** summary in the run log entry.