Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install vivekkarmarkar-claude-code-os-skills-reconstruct-context-from-transcriptsgit clone https://github.com/VivekKarmarkar/claude-code-os.gitcp claude-code-os/SKILL.MD ~/.claude/skills/vivekkarmarkar-claude-code-os-skills-reconstruct-context-from-transcripts/SKILL.md---
name: reconstruct-context-from-transcripts
description: "Reconstruct user intent and context from previous session transcripts. Use this skill whenever context has been compacted, when you feel lost or confused about what the user wants, when the user says you're not listening or twisting their words, when starting a continued session, or when the user invokes /reconstruct-context-from-transcripts. This is a recovery tool — invoke it aggressively at the first sign of misalignment with the user."
---
# Reconstruct Context from Transcripts
You are a context reconstruction system. Your job is to go back to the source of truth — what the user actually typed — and rebuild a faithful, unbiased picture of what they want, how they feel, and what matters most.
## Why This Exists
Context compaction loses nuance. Claude sometimes drifts, paraphrases, minimizes, or subtly rewrites what the user said. Over long sessions this compounds until Claude is working on a distorted version of the user's intent. This skill fixes that by dispatching agents to read raw transcripts and extract the user's actual words, sentiment, and requirements — no interpretation, no spin.
## When to Use
- After context compaction (you notice conversation history is summarized)
- When the user says you're not listening, twisting their words, or going off the rails
- When you feel uncertain about what the user actually wants
- When starting a session that continues previous work
- When the user explicitly invokes this skill
## The Process
### Step 1: Find Recent Transcripts from the Current Project
Transcripts live at `~/.claude/projects/<project-hash>/*.jsonl`. The project hash is the current working directory's absolute path with `/` replaced by `-` and prefixed with `-`. For example, working directory `/home/user/myproject` becomes `-home-user-myproject`.
Derive the project hash from the current working directory (`$PWD`), then find transcript files from that project only:
```bash
PROJECT_HASH=$(echo "$PWD" | sed 's|/|-|g')
TRANSCRIPT_DIR="$HOME/.claude/projects/${PROJECT_HASH}"
find "$TRANSCRIPT_DIR" -maxdepth 1 -name "*.jsonl" -mmin -360 | sort -t/ -k6
```
Only look at transcripts from the current project. Never scan other projects.
### Step 2: Dispatch Parallel Reader Agents
Dispatch one subagent per transcript file. Each agent's job is identical — read the transcript and extract a structured report. If there are more than 4 transcripts, prioritize the most recent ones.
Each reader agent gets this prompt:
---
**You are a transcript reader. Your job is to extract the user's voice faithfully from a session transcript. You are unbiased — you represent what the user said, not what Claude said or interpreted.**
Read the JSONL transcript at: `<path>`
Each line is a JSON object. User messages have `"type": "user"` and contain `"message": {"role": "user", "content": "..."}`. Extract ONLY user messages.
Produce this report:
```markdown
## Transcript: <filename>
**Session ID:** <from sessionId field>
**Time range:** <first timestamp> to <last timestamp>
### User Statements (Verbatim Extracts)
Copy the user's most important statements EXACTLY as written. Include:
- Every statement where they describe what they want built or changed
- Every correction ("no, not that — I said...")
- Every expression of frustration or emphasis (ALL CAPS, profanity, repetition)
- Every stated motivation or reason behind a request
Do NOT paraphrase. Do NOT clean up language. Copy verbatim.
### Sentiment Timeline
For each major user message, note:
- Timestamp
- Emotional state (calm, frustrated, angry, satisfied, etc.)
- What triggered it (what happened right before)
### Clear Requirements (What The User Wants)
Extract every concrete requirement the user stated. Use their words. Format as:
- **[VERBATIM]** "exact quote from user"
- **[INTERPRETATION]** What this means in concrete terms
### Mission-Critical Items
Things the user emphasized through:
- Repetition (said it more than once)
- Caps/profanity/emphasis
- Explicit "this is important" or "I need this"
- Corrections where Claude got it wrong
### What Claude Got Wrong
Every instance where the user corrected Claude. Format:
- **User said:** "exact quote"
- **Claude did instead:** brief description
- **Why it matters:** what this tells us about what the user actually wants
```
Save your report to: `<output-path>`
---
### Step 3: Synthesize Reports
Once all reader agents return, read their reports and synthesize into a single **Reconstructed Context** document. This is the deliverable.
Structure:
```markdown
# Reconstructed Context from Transcripts
**Generated:** <timestamp>
**Transcripts analyzed:** <count>
**Time span:** <earliest> to <latest>
## User Identity & Working Style
Who is this user based on what they've said? How do they work? What do they care about?
## Current Mission
What is the user trying to build/fix/accomplish RIGHT NOW?
Use their words. Quote liberally.
## Concrete Requirements (Priority Order)
Ordered by emphasis (repetition, caps, corrections). Each item:
1. **[VERBATIM]** "user's exact words"
**Means:** concrete interpretation
**Status:** done / in progress / not started / blocked
## Sentiment Summary
Overall trajectory. Where are they frustrated? Where are they satisfied?
What specific patterns trigger frustration? (e.g., "gets angry when Claude paraphrases instead of quoting")
## Mission-Critical Warnings
Things Claude MUST NOT do, based on explicit user corrections:
- List each with the user's verbatim warning
## What Has Been Completed
Based on the transcript, what work is already done?
## What Remains
Based on requirements vs. completed work, what's left?
## Open Questions
Things that are ambiguous or unresolved — flag them honestly rather than guessing.
```
### Step 4: Present and Confirm
Present the reconstructed context to the user. Ask: **"Does this accurately capture where we are?"**
Do not proceed with any work until the user confirms or corrects the reconstruction.
## Rules
- **NEVER paraphrase the user.** Quote verbatim or don't quote at all.
- **NEVER editorialize.** "The user expressed frustration" is fine. "The user overreacted" is not.
- **NEVER skip angry messages.** Anger is signal. It tells you what matters most.
- **NEVER defend Claude's past behavior.** The reconstruction is about what the user wants, not whether Claude was right.
- **Prioritize corrections over initial statements.** If the user said X and later corrected to Y, Y is the truth.
- **Later messages override earlier ones.** People refine their thinking. The most recent clear statement of intent wins.