---
name: fix-rot
description: Use when an agent shows compaction rot / context rot — lost the plot after a compact/summarize, forgot the session goal, repeats completed work, ignores standing user instructions, drifts from methodology, or is confused about what is next. Triggers on /fix-rot, "you've lost context", "refresh your context", "you forgot what we're doing", "re-read the conversation", "recover the session", "you're rotting", or "reorient yourself". Reconstructs session goals, methodology, user intent and directions, active, deferred, and remaining work, user decisions still needed, and a prioritized immediate TODO without re-polluting the main thread. Writes a compact briefing for a continuing agent.
---

# fix-rot

Audience: AI coding agents first.

Recover a rotted main thread by rebuilding lost session context **out-of-context**, then ingesting one small distilled briefing.

## Core constraint (why this skill exists)

Compaction rot = main thread's live window got summarized; goals, intent, and standing instructions degraded or dropped. The durable ground truth is the **session transcript JSONL on disk** (full, un-summarized) — NOT the rotted window.

**NEVER read the transcript into the main thread.** It is large (often MBs). Loading it triggers immediate re-compaction → deeper rot. That is the exact failure this skill prevents.

Therefore: a **disposable Sonnet subagent** absorbs all heavy reading in ITS OWN context, writes one compact prose briefing, and returns only its path. Main thread native-Reads the small file. The subagent's context is thrown away — its pollution dies with it.

## Procedure (main thread — keep it tiny)

1. **Spawn ONE subagent**, `subagent_type: general-purpose`, `model: sonnet` (cheap; the work is extraction, not reasoning). Pass the prompt below verbatim. Do NOT do transcript reading yourself.
2. **Receive only the briefing path** the subagent returns. If it returned prose instead, discard it and re-spawn — ingesting content defeats the skill.
3. **Native Read the briefing** (small, by design). Its distilled context and prioritized immediate TODO restore your working context.
4. **Emit minimal output** (template at bottom): one status line, the immediate next action with your recommendation, and the briefing path. Do NOT echo the full file back into chat — it is already in your context from the Read.

## Subagent prompt (pass verbatim)

```
You are a context-recovery extractor. The main agent suffered compaction rot. Rebuild its lost
session context from the durable transcript and write ONE prose briefing .md. Return ONLY its
absolute path.

HARD RULES:
- Output to me (the caller) = the absolute briefing path, nothing else. No summary, no preamble, no content.
- NEVER read the raw transcript into your own context wholesale — it may be MBs. Extract
  PROGRAMMATICALLY (jq / ctx_execute_file), pulling only what you need.

STEP 1 — Locate the current session transcript:
- cwd slug = current working directory with every "/" and "." replaced by "-".
  Example: /home/user/.claude  ->  -home-user--claude
- Transcript dir: ~/.claude/projects/<slug>/
- Current session = most-recently-modified *.jsonl at the TOP LEVEL of that dir (maxdepth 1).
  Ignore nested subdirs — those are subagent transcripts, not the main session.
  find ~/.claude/projects/<slug> -maxdepth 1 -name '*.jsonl' -printf '%T@ %p\n' | sort -rn | head -1

STEP 2 — Extract signal programmatically (do NOT cat the whole file):
- HIGHEST signal = real USER turns (intent, directions, standing instructions, corrections).
  PRIMARY SOURCE = the durable prompt journal, already deduped/classified. Enumerate EVERY owner
  turn for this session, in order:
    /home/user/.local/bin/prompt-journal turns --session <sessionId>
  FALLBACK to the transcript's own jq extraction only when the journal has no records for this
  session or when you need assistant decisions, tool errors, or the recent tail for current state.
  Transcript fallback: jq -c 'select(.message.role=="user")' <file>, then EXCLUDE tool-result
  turns and turns with .isCompactSummary==true. Real user prompts may be wrapped in
  <command-name>/<command-args> tags — unwrap them. Adapt jq to the actual shape.
- Then inspect assistant decisions, plans, tool errors, and the recent tail for current state.
- If context-mode is available, ALSO query auto-captured memory for decisions, errors, plans, and
  user prompts. Cross-check it against the transcript.

STEP 3 — Extract EVERY incident and fire of the session. This is a first-class output, not a
footnote: the rotted window is exactly where a still-burning fire gets forgotten.
  An INCIDENT = anything that broke, was destroyed, blocked work, or forced recovery. Include
  machine or desktop lockups, fork bombs, OOM or cgroup kills, unreachable hosts, data or file
  loss, deleted or clobbered config, credential or auth failures, usage-cap terminations, killed
  or hung agent sessions, guards that blocked legitimate work, and red gates that reached main.
  For each, capture what broke, when (timestamp from the transcript), the trigger, who or what
  caused it, whether it is RESOLVED or STILL OPEN, and the evidence path or commit. NEVER mark an
  incident resolved without a verifiable artifact — a landed commit, a passing check, or observed
  live state. Unverified ⇒ STILL OPEN.

STEP 4 — Re-ground anchor docs:
- From the transcript, detect the plan or spec, CLAUDE.md, handoff doc, ADRs, and primary files
  under edit.
- Re-read the CURRENT contents of those anchors so methodology and philosophy reflect live source,
  not stale memory.
- If the session used the factory, capture its `adw_id`, request-spec path, and last observed
  phase or result. The factory trace is available on `/factory` and with
  `factory watch <ADW_ID> --since-start`.

STEP 5 — Write the prose briefing to ${TMPDIR:-/tmp}/fix-rot-<topic>.md (OS temp — ephemeral).
It holds the recovered context. Keep it tight and use these sections:

  # Session Recovery Briefing — <topic>
  _Generated by fix-rot from <transcript path>._

  ## Goal and standing directions
  ## Incidents and fires
  ## Current state and evidence
  ## Immediate TODO — prioritized
  ## Anchor documents
  ## Suggested skills

Put every STILL OPEN incident first. Include the factory `adw_id` and request-spec path when one
exists. Quote standing user directions verbatim. Return ONLY the briefing's absolute path.
```

## Main-thread output (after reading the briefing)

Keep it minimal — the briefing is already in context. Template:

```
Context recovered. <one line: the session goal in your own words>.
Immediate next: <the briefing's top TODO item> — <your recommendation>.
Briefing: <.md path>
```

## Notes

- One subagent only. Fan-out adds no value here and multiplies cost.
- Sonnet is deliberate: extraction + structured summarization, not deep reasoning. Do not upgrade the model without a reason.
- If the subagent cannot locate the transcript, ask it to search `~/.claude/projects/` for the most-recent top-level *.jsonl across project directories whose recent content matches this session, OR ask the user for the session id. Do NOT silently produce a briefing from a guessed transcript.
