When to Roll Back AI Rules
Roll back when: AI-generated code is consistently wrong after a rule change (the new rule causes incorrect patterns), developer productivity drops noticeably (the new rule is too restrictive or confusing), CI is failing across multiple repos (the rule conflicts with existing code or lint configurations), or developers are overriding the new rule more than 30% of the time (the rule does not fit real-world usage). Roll back immediately: do not wait for the quarterly review. A bad rule: actively degrades every developer's AI output until it is reverted.
Do NOT roll back when: one developer finds the rule inconvenient (investigate — they may need guidance, not a rollback), the AI occasionally gets the rule wrong (refine the rule's wording instead), or the rule is correct but requires learning (give developers time to adapt — 1-2 weeks). The distinction: a rule that is wrong for the codebase (rollback) vs a rule that is new and unfamiliar (support and training).
The urgency spectrum: critical (CI failing across repos, developers blocked — rollback within 1 hour), high (AI consistently generates wrong patterns — rollback within 1 day), medium (rule is too restrictive for some use cases — rollback within 1 week, or refine the rule instead), and low (cosmetic issue — address in the next quarterly review). AI rule: 'Match rollback urgency to the impact. CI-breaking: immediate. Inconvenient: investigate before rolling back.'
Step 1: The Rollback Process (5 Minutes)
For a single repo: git revert the commit that changed the CLAUDE.md. This creates a new commit that undoes the rule change, preserving the full history. The CLAUDE.md: returns to the previous version. The AI: immediately reads the reverted rules on the next prompt. Push the revert commit. Done. Total time: 2 minutes.
For multi-repo sync: if the rule was distributed via the sync workflow (GitHub Actions, GitLab CI), revert the change in the central rules repo. The next sync run: opens PRs in target repos with the reverted rules. For faster rollback: run the sync workflow manually (workflow_dispatch trigger) instead of waiting for the scheduled run. For immediate rollback in critical situations: revert directly in each affected target repo (2 minutes per repo).
Version pin rollback: if the rule file uses version headers (v2.4.0), the rollback: pin back to the previous version (v2.3.0). In the sync system: update the manifest to reference v2.3.0. All target repos: receive the previous version on the next sync. AI rule: 'Rollback is always a revert — never a manual edit to remove the problematic rule. Revert preserves history. Manual edits: can introduce new errors and lose the audit trail.'
The instinct: open CLAUDE.md, find the problematic rule, delete it manually. The problem: you might delete too much, not enough, or introduce a formatting error. Git revert: reverses the exact change that was made. Nothing more, nothing less. The history: preserved (the problematic change AND the revert are both in git log). The result: deterministic, auditable, and error-free. Always git revert. Never manual edit for rollbacks.
Step 2: Communication and Investigation
Communication template: post in the #ai-standards Slack channel (or equivalent): 'RULE ROLLBACK: The [rule name/description] added in v2.4.0 has been rolled back to v2.3.0. Reason: [brief description — e.g., the error handling rule conflicted with Express middleware patterns, causing CI failures in 5 repos]. Action: if you merged the v2.4.0 sync PR, your rules will be updated on the next sync run. If you are experiencing issues now: run git revert [commit hash] on the CLAUDE.md change in your repo. Investigation: in progress. Updated rule will be re-deployed in v2.4.1.'
Root cause investigation: after the rollback stabilizes the situation, investigate. Questions: why did the rule cause problems? (Was it too broad? Too specific? Conflicting with another rule?) Was the rule tested before deployment? (If not: add a testing step to the rule deployment process.) Was the impact anticipated? (If not: improve the impact assessment process.) The investigation: produces a fix for the root cause, not just a revert. AI rule: 'Rollback stops the bleeding. Investigation prevents recurrence. Both are required. Rollback without investigation: the same mistake will be made again.'
The fix: based on the investigation, revise the problematic rule. Address the root cause (narrow the scope, resolve the conflict, improve the wording). Test the revised rule (use the test prompt technique from the debugging tutorial). Deploy as a new version (v2.4.1, not v2.4.0 — the old version is tainted). The revised rule: deployed through the normal sync process with a changelog explaining what changed and why.
The rule is rolled back. CI is green. Everyone moves on. 3 months later: a similar rule is proposed. Same conflict. Same CI failures. Same rollback. Without investigation: the team does not understand why the rule failed. With investigation: the root cause is identified (the rule conflicted with Express middleware patterns). The fix: scope the rule to exclude Express middleware. The re-deploy: succeeds because the root cause was addressed.
Step 3: Preventing the Need for Rollbacks
Test before deploy: before deploying a rule change to all repos, test it. Technique: apply the changed rules to one repo. Generate code with 5 representative prompts. Verify the output follows the intended pattern without breaking existing patterns. If the output is correct: deploy to all repos. If not: revise before deploying. This 15-minute test: prevents most rollbacks. AI rule: 'Every rule change: tested with 5 prompts before deployment. 15 minutes of testing: prevents hours of rollback and investigation.'
Canary deployment for rules: deploy the rule change to 2-3 volunteer repos first. Monitor for 1-2 days. If no issues: deploy to all repos. If issues: fix before the wider deployment. Only 2-3 repos are affected instead of all repos. The canary: catches problems at small scale before they become organization-wide incidents. AI rule: 'Canary deployment for rules: the same principle as canary deployment for code. Test with a few repos. Expand only when the canary is healthy.'
Rollback capability as a feature: the ability to rollback quickly is a feature of the rules platform, not an emergency procedure. Design for it: version all rule changes, maintain a changelog, use git revert (not manual edits), and have the sync workflow support emergency re-runs. When rollback is easy: teams are more willing to try new rules (the risk of experimentation is low). AI rule: 'Easy rollback encourages experimentation. Hard rollback discourages improvement. Invest in making rollback a 2-minute operation.'
Team afraid to try new rules: 'What if it breaks something?' If rollback takes 2 minutes and is well-practiced: 'Let us try it. If it breaks something: revert in 2 minutes.' Low rollback cost: enables the team to experiment with rules, learn what works, and improve faster. High rollback cost (manual process, no versioning, unclear communication): makes the team conservative. They never improve the rules because the risk of change is too high.
Rollback Summary
Complete AI rules rollback playbook.
- When: CI failing, AI consistently wrong, >30% override rate. NOT when: one person is inconvenienced
- Process: git revert the CLAUDE.md change. Push. 2 minutes for single repo
- Multi-repo: revert in central repo. Run sync manually. Or revert directly in affected repos
- Communication: Slack template with rule name, reason, action, and investigation status
- Investigation: why did it fail? Was it tested? Was impact assessed? Produce a root cause fix
- Re-deploy: revised rule as new version (v2.4.1). Changelog explains what changed and why
- Prevention: test with 5 prompts before deploying. Canary to 2-3 repos first. Expand when healthy
- Design for rollback: versioning, changelog, git revert, emergency sync re-runs. 2-minute operation