Imported from ran729/context-rot-skill (.claude/.claude/skills/context-rot/SKILL.md). Install upstream with npx skills add ran729/context-rot-skill --skill context-rot. Copyright stays with the author.

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:

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

Bonuses

Grade Table

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.