Compact From Transcript — Signal-First Session Compaction

"compaction is about extracting the signal not the summary" — the author, describing why this skill mines the raw transcript instead of summarizing it "Have agents mine the JSONL in chunks if you have to, but they must consume the raw source, not a sanitized rewrite" — the author's /jonathan-check2-style oracle (if you have not set up an oracle, this is just a discipline to hold yourself to)

Creates a FULL-QUALITY session compaction from a raw Claude Code transcript — for a session that ended without ever being compacted, so its intent, decisions and open threads would otherwise be lost. The pipeline:

1. Signal extraction — programmatically strip noise (tool calls, system prompts, metadata) preserving the person's verbatim words + agent responses + structured outputs
2. Read the signal file — the agent consumes the person's actual words, not a digest
3. INVOKE /reflect — extract what matters from the session
4. INVOKE /align (if you have it) or just do the same reasoning inline — derive nested intent layers
5. Write the record — to whatever compaction store you have (see below)

This whole pipeline needs nothing beyond what Claude Code already writes on its own: every session's raw transcript. There is no separate history-collection step to complete first.

Step 0: Extract signal from transcript

If your project ships a signal-extraction script (some do, to strip transcript noise before an agent reads it), run it before dispatching the agent:

node <path-to-your-extraction-script> SESSION_UUID --out /tmp/signal-SESSION_SHORT.txt

If you don't have one, skip this step and have the agent read the raw transcript directly — ~/.claude/projects/<project-slug>/<session-id>.jsonl — filtering by hand for human messages and structured outputs. It's slower per-session but works with nothing extra installed.

This produces a signal file containing:

• Every human message (verbatim, never truncated)
• Agent response before and after each human message (truncated to 500 chars)
• Any structured agent outputs: /reflect results, /align intent maps, audit findings, compaction drafts, hallucination diagnostics
• Session metadata: message count, human turn count

The signal file IS the raw source — it's the person's actual words with JSONL metadata stripped. It's not a summary, not a digest, not an interpretation.

Step 1: Read the signal file

The agent reads the signal file (typically 3-75KB vs 50KB-5MB raw JSONL). This preserves the person's verbatim words while fitting within the subagent's token budget.

Step 2: INVOKE /reflect

Invoke the /reflect skill on the session content. Produce:

• Target: What was the person trying to accomplish?
• Location: Where did the session end up?
• Gap: What remains between intent and reality?
• Initiative: What overarching goal does this serve?
• Leverage: What hasn't been considered?

Step 3: INVOKE /align

Invoke the /align skill (if you have it; otherwise just reason through the same questions by hand) to derive nested intent layers with certainty scores.

Step 4: Write the record

If you have your own compaction store (a database, an API, whatever your project already uses to keep session records — this is optional, most people won't have one at first), write the record there in whatever shape that store expects, and include the same fields listed below.

Otherwise, write it locally. Run alignment-harness records compactions to get the folder path, then write one file there, e.g. <that folder>/SESSION_SHORT.json:

{
  "sessionId": "SESSION_UUID",
  "title": "TITLE",
  "subtitle": "SUBTITLE",
  "compactedSession": "SIGNAL EXTRACTION (2000-5000 chars, the person's actual words, not a paraphrase)",
  "overarchingIntentTitle": "FROM /ALIGN",
  "overarchingIntentDescription": "FROM /ALIGN",
  "targetUxIntentTitle": "FROM /ALIGN",
  "targetUxIntentDescription": "FROM /ALIGN",
  "leverageScore": "N",
  "reflectionOnScope": "FULL /REFLECT + /ALIGN MARKDOWN",
  "agentReasoning": "from /reflect",
  "scopeDeclaration": "from /align",
  "tags": ["tag1", "tag2"],
  "creatorSessionId": "SESSION_UUID",
  "enrichmentHistory": [{
    "enrichedBy": "compact-from-transcript",
    "enrichedAt": "ISO timestamp, now",
    "enrichedFields": ["all"],
    "confidenceLevel": "high",
    "modelUsed": "whatever model is actually running this — read it at write time, never hardcode a model name here"
  }]
}

Print the path you wrote to, so the person can find it. If you do have a store, verify the write by reading the record back; if local, verify the file exists and parses.

Batch Mode

An orchestrating agent can pre-extract signal for multiple sessions at once:

# Extract signal for many sessions at once (skip if you have no extraction script — see Step 0)
for uuid in SESSION1 SESSION2 ...; do
  node <path-to-your-extraction-script> $uuid --out /tmp/signal-${uuid:0:8}.txt
done

Then dispatches agents with the signal file content pre-loaded in the prompt. Each agent gets:

• The signal file content (3-75KB of the person's verbatim words)
• Instructions to invoke /reflect + /align + write the record
• The record shape from Step 4

Because this reads someone's full raw transcript, tell the person what you're about to read (which sessions, roughly how much) before you read it — don't run a silent batch sweep over private history without saying so first.

Quality Requirements

• compactedSession must be SIGNAL EXTRACTION not summary — what the person was trying to accomplish, what got done, what's still open, what the UX impact is
• Every human message referenced must be the person's actual words
• UX-first writing: every object leads with who is affected, what they experience, what changes
• reflectionOnScope must contain the full /reflect + /align markdown analysis
• If nothing turns up worth compacting (a trivial or aborted session), say so rather than manufacturing a record