Review learned rules against marketplace rules for overlap. Identifies learned rules that have been superseded by upstream changes and recommends cleanup. Use periodically to reduce context bloat from duplicate rules.
Compare learned rules against marketplace rules to find overlap and recommend cleanup. Learned rules are created by the retrospective system when corrections are detected. Marketplace rules are installed by plugins. Over time, learnings get folded into the marketplace — but the local learned rules stick around, doubling up in context.
Scan both locations based on $ARGUMENTS:
# Global learned rules
ls ~/.claude/rules/learned--*.md 2>/dev/null
# Project learned rules
ls .claude/rules/learned--*.md 2>/dev/null
# Marketplace rules (installed by plugins)
ls .claude/rules/ 2>/dev/null | grep -v '^learned--'
ls ~/.claude/rules/ 2>/dev/null | grep -v '^learned--'
Read every rule file — both learned and marketplace. For each, extract:
description from frontmatterOutput: Table of all rules with source (learned vs marketplace plugin).
For each learned rule, compare it against every marketplace rule. You are looking for:
Full supersession: The marketplace rule covers the same ground as the learned rule. The learned rule adds nothing beyond what the marketplace now enforces.
Example: learned--evaluate-platforms-as-package.md says "evaluate infrastructure decisions together." If the architect plugin's architecture rule now says the same thing, the learned rule is superseded.
Partial overlap: The marketplace rule covers part of the learned rule, but the learned rule has additional specifics not in the marketplace.
Example: learned--no-code-without-spec.md says "never code without a spec." The marketplace has spec-first.md in all implementation agents. If the content is the same, it's superseded. If the learned rule has project-specific detail (like a specific docs/quality/specs/ path), it's partial.
No overlap: The learned rule covers something the marketplace doesn't address at all. Keep it.
Output: Classification table.
## Rule Reconciliation
### Superseded (safe to remove)
| Learned rule | Superseded by | Confidence | Reason |
|---|---|---|---|
| `learned--{topic}.md` | `{plugin}--{rule}.md` | High/Medium | [why they overlap] |
### Partial overlap (review needed)
| Learned rule | Overlaps with | What's extra in learned | Recommendation |
|---|---|---|---|
| `learned--{topic}.md` | `{plugin}--{rule}.md` | [specific additional content] | Keep / Merge / Remove |
### No overlap (keep)
| Learned rule | Covers |
|---|---|
| `learned--{topic}.md` | [what it covers that no marketplace rule addresses] |
### Summary
- Total learned rules: [N]
- Superseded (remove): [N]
- Partial overlap (review): [N]
- Unique (keep): [N]
- Context tokens saved if cleaned up: ~[estimate based on file sizes]
Wait for the user to approve removals before deleting anything.
For each rule the user approves for removal:
rm ~/.claude/rules/learned--{topic}.md
# or
rm .claude/rules/learned--{topic}.md
Report what was removed.
After cleanup, update the reconciliation snapshot so the SessionStart hook won't nudge again until plugins change:
python3 -c "
import json, os, glob
plugins = set()
for d in [os.path.expanduser('~/.claude/rules'), '.claude/rules']:
for f in glob.glob(os.path.join(d, '*.md')):
basename = os.path.basename(f)
if not basename.startswith('learned--'):
parts = basename.split('--', 1)
if len(parts) == 2:
plugins.add(parts[0])
snapshot = {'marketplace_plugins': sorted(plugins), 'reconciled_at': '$(date -u +%Y-%m-%dT%H:%M:%SZ)'}
os.makedirs(os.path.expanduser('~/.claude/learnings'), exist_ok=True)
with open(os.path.expanduser('~/.claude/learnings/reconcile-snapshot.json'), 'w') as f:
json.dump(snapshot, f, indent=2)
"
Do NOT remove rules the user hasn't explicitly approved. Present the list, wait for confirmation, then act.
~/.claude/rules/) and project (.claude/rules/). A global learned rule might be superseded by a project-installed marketplace rule./thinking:retrospective — creates learned rules. This skill cleans them up when the marketplace catches up./thinking:propose-improvement — proposes PRs to upstream learned rules into the marketplace. After merge, run reconcile to clean up.