context-rot

# context-rot

A Claude Code plugin that audits your `CLAUDE.md` and recent conversation transcripts for **context rot** — stale, redundant, or missing instructions that quietly degrade AI performance.

Invoke it with `/context-rot:context-rot` and get back a scored health report with concrete fixes.

---

## Why This Exists

A 2026 study — [*Evaluating AGENTS.md Files as a Form of Specification in Agentic AI* (arXiv:2602.11988)](https://arxiv.org/abs/2602.11988) — measured what happens when AI agents are given context files like `CLAUDE.md`:

| Finding | Impact |
|---|---|
| Task success rate | **−2% to −4%** |
| Inference cost overhead | **+20% to +23%** |
| Extra reasoning tokens | **+22%** |
| Additional agent steps per task | **+2.45 to +3.92** |

The research conclusion: context files that are overly prescriptive, redundant, or stale **actively harm** AI performance rather than help it. Most teams don't notice because the degradation is gradual — it's rot.

This plugin makes the rot visible.

---

## What It Does

1. Finds the 5 most recent conversation transcripts for the current project
2. Scans for friction signals: user corrections, repeated clarifications, policy overrides, apologies
3. Reads your `CLAUDE.md` and flags redundancy, ghost sections, bloat, and stale references
4. Scores everything 0–100 against a research-grounded anti-pattern taxonomy
5. Outputs a full visual scorecard with a prioritized fix queue

---

## Installation

```
/plugin marketplace add ran729/context-rot-skill
/plugin install context-rot@ran729
```

### During development

```bash
git clone https://github.com/ran729/context-rot-skill
claude --plugin-dir ./context-rot-skill
```

---

## Usage

In any Claude Code session, invoke the skill:

```
/context-rot:context-rot
```

Claude will work silently through transcript analysis and CLAUDE.md review, then output a scored health report ending with a full visual scorecard.

---

## Score Grades

| Score | Grade | Verdict |
|---|---|---|
| 90–100 | S | "Your AI is basically psychic" |
| 75–89 | A | "Smooth operator" |
| 60–74 | B | "Good bones, some ghosts" |
| 45–59 | C | "Claude is confused but trying" |
| 30–44 | D | "Gaslit by your own docs" |
| 0–29 | F | "CLAUDE.md is a war crime" |

---

## License

MIT