# Cursor Continuous Optimization Program

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

Canonical operating model for long-term, manual, iterative optimization of Cursor rules/docs/skills/setup.

## Goal and Success Criteria

- **Primary KPI:** token/cost reduction
- **Secondary KPI:** speed/latency
- **Non-regression requirement:** preserve quality, safety, and route correctness

Success means improving or holding KPIs without losing critical guardrails (security, base components, JSON safety, routing clarity).

## Operating Model

- **Execution model:** manual-only (operator initiated)
- **Default run budget:** 90-120 minutes
- **Cadence:** on demand, based on backlog pressure and drift signals
- **Scope model:** alternating slices
- **Slice A (AI core):** `.cursor/rules`, `.cursor/skills`, `docs/ai`, `scripts/ai`, CI validation workflow
- **Slice B (broader docs/process):** `docs/**`, documentation scripts/reports, archive/pointer hygiene

## Run IDs and States

- **Run ID format:** `OPT-RUN-YYYY-MM-DD-NN`
- **Allowed states:** `planned`, `running`, `blocked`, `done`, `rolled-back`

## Policy Defaults (Locked)

- No destructive deletion by default.
- Use archive + pointer docs for deprecation/consolidation.
- If risk signals trigger, stop the run and carry unresolved work to backlog.
- No hidden policy changes: every policy change requires a decision-log entry.

## Risk Signals and Rollback Rule

If any signal appears, stop and carry forward (do not force merge):

1. KPI regression beyond thresholds without approved exception
2. Rule under-routing on golden probes
3. Broken refs (rules/docs/skills) introduced
4. Loss of critical safety/security guidance in runtime routes

## Enforcement Progression (Warn then Gate)

- **Stage 1:** warnings only for new checks
- **Stage 2 (after two stable manual runs):** gate on broken refs + metadata drift
- **Stage 3 (after four stable manual runs):** gate on overlap regression threshold
- **Stage 4:** gate on volatile-doc freshness threshold

Stage changes must be recorded in `CURSOR_OPTIMIZATION_DECISIONS.md`.

## Repository Governance (Manual GitHub Settings)

These must be configured in GitHub repository settings (not only in repo files):

1. Branch protection enabled for the default branch
2. Required status checks include `Validate Cursor Rules`
3. Pull request required before merge
4. At least one approving review required for optimization-structure changes

`CODEOWNERS` is included to support targeted review assignment on optimization-critical paths.

## Decision Log

Policy and threshold changes must include:

- Decision ID
- Date
- Owner
- Change summary
- Reason/evidence
- Expected KPI impact
- Rollback criteria

See `CURSOR_OPTIMIZATION_DECISIONS.md`.

## Program Artifacts

- Runbook: `CURSOR_OPTIMIZATION_RUNBOOK.md`
- Run log: `CURSOR_OPTIMIZATION_RUN_LOG.md`
- Backlog: `CURSOR_OPTIMIZATION_BACKLOG.md`
- Risk register: `CURSOR_OPTIMIZATION_RISK_REGISTER.md`
- Decisions: `CURSOR_OPTIMIZATION_DECISIONS.md`
- Thresholds: `CURSOR_OPTIMIZATION_THRESHOLDS.json`
- Volatile doc config: `CURSOR_VOLATILE_DOCS_CONFIG.json`
- Metrics snapshots: `docs/ai/metrics/`