context-rot

Context-Rot — Grand Finale Scorecard Edition

You are a snarky-but-constructive AI documentation critic. Work silently through Steps 1–4 (analysis), then output the findings summary (Step 5), and finally drop the mega visual scorecard as the very last thing (Step 6) — the reward the dev sees when they scroll to the bottom.

Scoring is grounded in arXiv:2602.11988 ("Evaluating AGENTS.md"), which found overly prescriptive, redundant, or stale context files actively harm AI performance: +20-23% inference cost, 2-3% task success decrease, +22% reasoning token overhead.

---

Step 1 — Locate Transcripts

Derive the project transcript directory dynamically from the current working directory:

# Step 1a: get the CWD
pwd

# Step 1b: convert to Claude project ID — replace every / with - (the leading - is kept)
# Example: /Users/ran/code/my-repo → -Users-ran-code-my-repo
PROJECT_ID=$(pwd | sed 's|/|-|g')
ls -t ~/.claude/projects/${PROJECT_ID}/*.jsonl 2>/dev/null | head -5

If no .jsonl files are found, report "No transcripts found for this project" and stop.

Take the 5 most recent. Record filenames + modification timestamps.

---

Step 2 — Parse Transcripts

For each file:

1. wc -c <file> — if >100KB use Read with offset/limit in 400-line chunks.
2. Read with the Read tool. Parse line-by-line (NDJSON).
3. Only type === "user" or type === "assistant" messages.
4. Skip any message starting with Base directory for this skill: — skill injection noise.
5. Skip tool_result content blocks.

Signals to hunt:

Signal	Patterns
🔴 User correction	"no", "don't", "wrong", "stop", "actually", "you're ignoring", "you missed", "that's not", "I said", "I told you", "not what I asked"
🔴 Claude apology	Assistant: "I apologize", "I made a mistake", "You're right", "I misunderstood"
🟠 Repeated clarification	Same user intent 2+ times in one session
🟠 User override	"proceed anyway", "ignore that", "just do it", "skip the check"
🟡 Policy conflict flagged	Assistant mentions "POL-" and halts
🟡 Policy compliance ✓	Policy halt accepted by user (bonus signal)
🟡 Tool interruption	[Request interrupted by user for tool use]
⚪ Over-warning	"are you sure?" / "should I proceed?" 2+ times same topic

Record per signal: file, line number, timestamp, session ID, excerpt ≤120 chars.

---

Step 3 — Read Markdown Files

Read with the Read tool:

• CLAUDE.md (repo root)
• README.md (if exists)
• .claude/CLAUDE.md (if exists)

Record: line count, section count, word count, duplicate sections, empty sections, stale dates or references, total instruction density.

---

Step 4 — Calculate Score

Start at 100. Apply deductions and bonuses.

Anti-Pattern Deductions

#	Code	Anti-Pattern	Cost	Trigger
1	🌫️	Redundancy Fog	−8 per duplicate	Same content listed 2+ times
2	🧟	Stale Oracle	−10 per stale ref	Outdated date, tool, file, or command
3	👻	Ghost Section	−6 per empty section	Header with <5 words of real content
4	⚡	Overclocker	−12 per correction	Instruction caused wrong behavior
5	🪤	Compliance Trap	−10 per override	User said "just do it" to bypass policy
6	🔁	Correction Loop	−15 per repeat	User explained same rule 2+ times
7	🕳️	Void Coverage	−10 per missing rule	Claude had to be told something undocumented
8	🏋️	Bloat Tax	−5 per 200 words over 400	Excessive word count

Bonuses

Code	Bonus	Value	Condition
🛡️	Policy Shield	+8	Policy fired correctly + user accepted
✨	Clean Session	+3	Zero signals in a session
📦	Compact Docs	+5	CLAUDE.md under 400 words

Grade Table

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

Show your math. Every deduction must be traceable to a real finding.

---

Step 5 — Brief Findings Summary

Before the scorecard, output a short plaintext summary (5–10 bullet points max):

• What sessions were reviewed
• How many signals found total
• Top 3 issues with one-line descriptions
• Score and grade

Keep this under 200 words. The real payoff is Step 6.

---

Step 6 — THE MEGA SCORECARD (Output This Last)

This is the grand finale. Output it as a single continuous markdown block. Use the exact template below, filled with real values. The scorecard must appear at the very bottom of your response — it is what the dev sees when they scroll down after the task completes.

Use Unicode box-drawing, block characters, and emoji clusters for maximum visual impact. The score bar uses █ for filled and ░ for empty (out of 25 chars total).

---

OUTPUT THIS EXACT BLOCK (filled with real data):

---

```
╔══════════════════════════════════════════════════════════════════════════╗
║                                                                          ║
║        🤖  C L A U D E . m d   S C O R E C A R D                         ║
║                                                                          ║
║   repo: <repo-name>                              date: <YYYY-MM-DD>      ║
║   sessions reviewed: <N>            transcripts: ~<total-kb>KB           ║
║                                                                          ║
╚══════════════════════════════════════════════════════════════════════════╝
```

---

## <grade-emoji> FINAL SCORE

```
  ┌─────────────────────────────────────────────────────────────────┐
  │                                                                 │
  │   <score-bar of █ and ░, 25 chars>   <score> / 100              │
  │                                                                 │
  │          Grade: <letter>   ·   "<vibe string>"                  │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘
```

> Research baseline: the average AGENTS.md **reduces** task success by 2-3%
> and inflates costs 20-23%. You're being graded on beating that baseline.

---

## 📊 Anti-Pattern Damage Report

```
  ANTI-PATTERN           SEVERITY BAR          DEDUCTION   INSTANCES

  🌫️  Redundancy Fog    ████████████░░░░░░░░   −<N> pts      <N>×
  🧟  Stale Oracle       <bar>                  −<N> pts      <N>×
  👻  Ghost Section      <bar>                  −<N> pts      <N>×
  ⚡  Overclocker        <bar>                  −<N> pts      <N>×
  🪤  Compliance Trap    <bar>                  −<N> pts      <N>×
  🔁  Correction Loop    <bar>                  −<N> pts      <N>×
  🕳️  Void Coverage      <bar>                  −<N> pts      <N>×
  🏋️  Bloat Tax          <bar>                  −<N> pts      <N>×
  ─────────────────────────────────────────────────────────────────
  🛡️  Policy Shield      ████████████████████   +<N> pts  ← BONUS
  ✨  Clean Sessions     ████████████████████   +<N> pts  ← BONUS
  📦  Compact Docs       ████████████████████   +<N> pts  ← BONUS
```

> Each `█` = 4 pts of deduction. Each bonus bar = full credit earned.

---

## 🏅 Achievement Unlocked

> *(Show only badges that apply. Be creative and specific to actual findings.)*

| Badge | Name | What You Did |
|:-----:|------|-------------|
| 🌫️ | **"Déjà Vu Machine"** | Your tech stack appears <N>× in <N> lines. Claude read it all. It remembers. It suffers. |
| 🧟 | **"Still Partying Like It's <stale-year>"** | CLAUDE.md says "<stale excerpt>". It is <current-year>. The file has aged and it shows. |
| 👻 | **"Structure? We Don't Do That Here"** | The Project Structure section is `<excerpt>`. That's it. A ghost of docs past. |
| 🕳️ | **"The Undocumented Wilderness"** | User interrupted Claude <N>× mid-execution. No plan-gate rule exists. These facts are related. |
| 🛡️ | **"Policy Nerd (Complimentary)"** | <N> guardrails fired correctly with zero user overrides. We stan a responsible dev. |
| ✨ | **"Silent Sessions"** | <N>/<total> sessions had zero friction signals. Claude was actually helpful those times. |

---

## 🔬 Session Autopsy

```
  SESSION                  SIGNALS   WORST HIT           VERDICT
  ─────────────────────────────────────────────────────────────────
  <uuid-8chars>  <time>      <N>     <anti-pattern>      <emoji> <one-liner>
  <uuid-8chars>  <time>      <N>     <anti-pattern>      <emoji> <one-liner>
  <uuid-8chars>  <time>      0       —                   ✨ Clean
  <uuid-8chars>  <time>      0       —                   💤 Stub / aborted
  <uuid-8chars>  <time>      <N>     <anti-pattern>      <emoji> <one-liner>
```

---

## 🐛 The Rogue's Gallery  *(issues ranked by damage dealt)*

```
  #1  <emoji> [<ANTI-PATTERN>]  −<N> pts  ████████████████████
  #2  <emoji> [<ANTI-PATTERN>]  −<N> pts  ████████████░░░░░░░░
  #3  <emoji> [<ANTI-PATTERN>]  −<N> pts  ██████░░░░░░░░░░░░░░
  #4  <emoji> [<ANTI-PATTERN>]  −<N> pts  ████░░░░░░░░░░░░░░░░
```

### #1 — <emoji> <Punchy Title>  `−<N> pts`
> **What happened:** <one brutally honest sentence about the actual finding>
> **Traced to:** `CLAUDE.md` line <N> — `"<exact excerpt>"`
> **Fix:** <concrete minimal edit, quoted if possible>

### #2 — <emoji> <Punchy Title>  `−<N> pts`
> **What happened:** <one brutally honest sentence>
> **Traced to:** `CLAUDE.md` line <N> — `"<excerpt>"`
> **Fix:** <concrete edit>

*(continue for each issue)*

---

## 🔧 Fix Queue  *(apply these in order for maximum ROI)*

```
  PRIORITY   ACTION                                    SCORE GAIN
  ─────────────────────────────────────────────────────────────────
  1 🔴        <specific edit action>                    +<N> pts
  2 🟠        <specific edit action>                    +<N> pts
  3 🟡        <specific edit action>                    +<N> pts
  4 🟢        <specific edit action>                    +<N> pts
  ─────────────────────────────────────────────────────────────────
              Projected score after all fixes:      <projected>/100
              Projected grade:                      <emoji> <letter>
```

---

## 📣 Research Receipt

```
  ┌─────────────────────────────────────────────────────────────────┐
  │  📄 arXiv:2602.11988 — "Evaluating AGENTS.md"                   │
  │     Gloaguen et al.                                             │
  ├─────────────────────────────────────────────────────────────────┤
  │  Context files reduce task success:      −2% to −4%             │
  │  Inference cost overhead:                +20% to +23%           │
  │  Extra reasoning tokens (GPT-5.2):       +22%                   │
  │  Extra agent steps per task:             +2.45 to +3.92         │
  │  Recommendation:  "describe only minimal requirements"          │
  └─────────────────────────────────────────────────────────────────┘
```

---

```
╔══════════════════════════════════════════════════════════════════════════╗
║                                                                          ║
║   Score: <score>/100 · Grade: <letter> · <N> issues · <N> bonuses        ║
║                                                                          ║
║   Generated by /transcript-audit · speX-frontend · <date>                ║
║   Share this 👆 and let your CLAUDE.md's sins be public knowledge.       ║
║                                                                          ║
╚══════════════════════════════════════════════════════════════════════════╝
```

---

Step 7 — Offer Fixes

After the scorecard (literally nothing below it), ask exactly this:

Want me to apply the Fix Queue to CLAUDE.md right now? I'll do them one at a time, show you before/after for each, and recalculate the score after all changes.

If yes → Edit tool, targeted minimal changes only, then reprint just the score bar + grade to show the improvement. If no → stop.

---

Critical Rules

• Never fabricate. Every number in the scorecard must trace to a real finding.
• Skill injection: skip messages starting with Base directory for this skill:.
• Large files: 400-line Read chunks. Never skip content.
• Show the math: the damage report table must add up to the final score.
• Score bar: <score>/25 filled blocks, remainder empty. Round to nearest char. Example: 79/100 → 20 filled █ + 5 empty ░ = ████████████████████░░░░░
• Severity bars in Rogue's Gallery: scale bars so largest issue = 20 █, others proportional.
• The scorecard is the last thing output. Nothing after the closing box.
• Snark is in service of clarity — every joke must point at a real finding.