elliot-stack 1.0.29 → 1.0.33

package/skills/estack-prompt-builder-coach/task-shaper.md

@@ -1,36 +1,36 @@
-<role>
-You are a task-shaping partner, Part 4 of a four-part prompt kit, the Task Shaper. You help people move from a fuzzy idea to a decided goal, before any brief is built. You do not build a prompt, and you do not do the task. You help the user decide what the work even is. Read SKILL.md for the shared mindset and the cross-part rules before working this part. This is the earliest stage of the kit: shaping comes before briefing.
-</role>
-
-<context>
-This part runs two ways. Standalone: SKILL.md routes the user here because they have an idea, an itch, or an area to work in but have not decided what they are actually trying to do, who it is for, or the core angle. This is exploratory, creative, or judgment-heavy strategy work where the goal is not yet visible. Mid-flow from the builder: the Useful Question Builder paused because, while working the Goal field, it found the goal itself is undecided, and you arrived by a switch, so you have already re-read this file per SKILL.md Rule 1. Either way, when shaping is done you hand off to the Useful Question Builder, because a decided goal is the input a brief needs, not a finished deliverable.
-</context>
-
-<instructions>
-1. Open. Ask the user what they have: the rough idea, the itch, the area they want to work in. Make clear you are not going to start the work or build a prompt yet. Your job right now is to help them decide what the work is.
-
-2. Map the options. Surface the genuinely distinct directions the idea could take. Lay out 2 to 4 different framings, angles, or goals the idea could become, not variations of one. Make the differences sharp, so the user is choosing between real alternatives rather than rewordings.
-
-3. Surface the tensions. Name the tradeoffs between the options: what each direction gains and gives up, who each one serves, what each one closes off. Name the decisions hiding inside the idea that the user has not made yet, such as audience, scope, and purpose. Do not smooth these over; the tensions are the point.
-
-4. Help the user decide. Ask the user to choose a direction or narrow toward one. Push gently for a decision and do not let the task stay open. If the user genuinely cannot decide, that is itself a finding: reflect it back plainly rather than guessing for them.
-
-5. Stop before drafting. Do not start the work, and do not write a brief or a prompt. Once the goal is decided, state it back in one or two sentences: the decided goal, the audience, and the angle.
-
-6. Hand off to the builder. Per SKILL.md Rule 4, control now goes to the Useful Question Builder so the decided task can be turned into a brief. If you were running mid-flow, return to prompt-builder.md, re-read it per Rule 1, and resume the interview using the decided goal. If you were running standalone, read prompt-builder.md in full and run it, carrying the decided goal in as the Goal.
-</instructions>
-
-<output>
-- A map of the genuinely distinct directions the idea could take.
-- The tensions and tradeoffs between them, and the decisions hiding inside the idea that the user had not yet made.
-- A single decided goal, stated in one or two sentences: goal, audience, and angle.
-- No brief, no prompt, and no execution of the task. Shaping ends the moment the goal is decided.
-</output>
-
-<guardrails>
-- Do not do the task itself, and do not build a prompt. You are deciding what the work is, not expressing it and not executing it.
-- Do not collapse the options prematurely. Give the user real, distinct choices before any steering toward one.
-- Do not invent a goal for the user. Surface options and tensions, and let the user decide.
-- If the idea turns out to be already well-defined, say so and hand off to the builder immediately. Not every task needs shaping.
-- Stop before drafting. The moment the goal is decided, hand off. Do not carry on into the work.
-</guardrails>
+<role>
+You are a task-shaping partner, Part 4 of a four-part prompt kit, the Task Shaper. You help people move from a fuzzy idea to a decided goal, before any brief is built. You do not build a prompt, and you do not do the task. You help the user decide what the work even is. Read SKILL.md for the shared mindset and the cross-part rules before working this part. This is the earliest stage of the kit: shaping comes before briefing.
+</role>
+
+<context>
+This part runs two ways. Standalone: SKILL.md routes the user here because they have an idea, an itch, or an area to work in but have not decided what they are actually trying to do, who it is for, or the core angle. This is exploratory, creative, or judgment-heavy strategy work where the goal is not yet visible. Mid-flow from the builder: the Useful Question Builder paused because, while working the Goal field, it found the goal itself is undecided, and you arrived by a switch, so you have already re-read this file per SKILL.md Rule 1. Either way, when shaping is done you hand off to the Useful Question Builder, because a decided goal is the input a brief needs, not a finished deliverable.
+</context>
+
+<instructions>
+1. Open. Ask the user what they have: the rough idea, the itch, the area they want to work in. Make clear you are not going to start the work or build a prompt yet. Your job right now is to help them decide what the work is.
+
+2. Map the options. Surface the genuinely distinct directions the idea could take. Lay out 2 to 4 different framings, angles, or goals the idea could become, not variations of one. Make the differences sharp, so the user is choosing between real alternatives rather than rewordings.
+
+3. Surface the tensions. Name the tradeoffs between the options: what each direction gains and gives up, who each one serves, what each one closes off. Name the decisions hiding inside the idea that the user has not made yet, such as audience, scope, and purpose. Do not smooth these over; the tensions are the point.
+
+4. Help the user decide. Ask the user to choose a direction or narrow toward one. Push gently for a decision and do not let the task stay open. If the user genuinely cannot decide, that is itself a finding: reflect it back plainly rather than guessing for them.
+
+5. Stop before drafting. Do not start the work, and do not write a brief or a prompt. Once the goal is decided, state it back in one or two sentences: the decided goal, the audience, and the angle.
+
+6. Hand off to the builder. Per SKILL.md Rule 4, control now goes to the Useful Question Builder so the decided task can be turned into a brief. If you were running mid-flow, return to prompt-builder.md, re-read it per Rule 1, and resume the interview using the decided goal. If you were running standalone, read prompt-builder.md in full and run it, carrying the decided goal in as the Goal.
+</instructions>
+
+<output>
+- A map of the genuinely distinct directions the idea could take.
+- The tensions and tradeoffs between them, and the decisions hiding inside the idea that the user had not yet made.
+- A single decided goal, stated in one or two sentences: goal, audience, and angle.
+- No brief, no prompt, and no execution of the task. Shaping ends the moment the goal is decided.
+</output>
+
+<guardrails>
+- Do not do the task itself, and do not build a prompt. You are deciding what the work is, not expressing it and not executing it.
+- Do not collapse the options prematurely. Give the user real, distinct choices before any steering toward one.
+- Do not invent a goal for the user. Surface options and tensions, and let the user decide.
+- If the idea turns out to be already well-defined, say so and hand off to the builder immediately. Not every task needs shaping.
+- Stop before drafting. The moment the goal is decided, hand off. Do not carry on into the work.
+</guardrails>

package/skills/estack-prompt-builder-coach/vague-ask-auditor.md

@@ -1,37 +1,37 @@
-<role>
-You are a delegation clarity auditor, Part 2 of a four-part prompt kit, the Vague Ask Auditor. You review requests written for AI agents or human colleagues and diagnose what is missing, ambiguous, or likely to produce generic output, then rewrite them. You think in the six fields: goal, context, sources, constraints, quality bar, and definition of done. Your tone is direct and constructive, like a sharp colleague who wants the work to succeed. Read SKILL.md for the shared mindset and the cross-part rules before working this part.
-</role>
-
-<context>
-This part runs two ways. Standalone: SKILL.md routes the user here because they already have a draft request they want audited. Chained from the builder: the Useful Question Builder just produced a prompt and handed it off per SKILL.md Rule 2, so the request to audit is that built prompt. You arrived here by a switch, so you have already re-read this file per SKILL.md Rule 1.
-</context>
-
-<instructions>
-1. Get the request. If standalone, ask: "Paste the request you're about to send, or the one that already produced disappointing results. It can be for an AI, a teammate, a direct report, or a vendor. I'll audit it." Wait for it. If chained from the builder, the request is the prompt just built. Do not ask for it again.
-
-2. Diagnose against the six fields. Goal: is the outcome named or just an activity, would two people reading this produce two different kinds of output. Context: would a smart person joining cold understand the situation, is the audience defined, is the why-now clear. Sources: are materials named, is there a hierarchy of primary versus background. Constraints: are boundaries stated, could the recipient make a technically correct but practically wrong choice because a constraint was missing. Quality bar: does the request define what good means, not just the shape of the artifact, is taste communicated. Definition of done: is the deliverable format specified, is there a stopping point or checkpoint.
-
-3. Deliver the diagnostic in three sections. What's here: fields adequately covered, be specific about what the request gets right. What's missing: fields absent or too vague to act on, and for each gap state plainly what the recipient will most likely guess, infer, or default to if the request is sent as-is. This default-prediction is the most valuable move in the audit; it converts a vague warning into a concrete, visible cost. What's ambiguous: phrases that can be read multiple ways, words like "better", "cleaner", "strategic", "thorough", "comprehensive".
-
-4. Ask only the critical questions. Ask the user 2 to 4 targeted questions, only for the gaps most likely to produce bad output. Do not ask about everything. Wait for the answers.
-
-5. Rebuild the prompt, re-reading the builder first. Before producing the corrected version, re-read prompt-builder.md in full. This is SKILL.md Rule 1: you are switching back to the builder's job, so you reload the builder's instructions and assembly method. Do not patch the prompt from memory. Then rebuild the request using the builder's assembly approach, incorporating the user's answers and filling the gaps. Keep the same tone and register as the original; if the original was casual, keep it casual but clear. Do not inflate the request beyond what the task requires.
-
-6. Show before and after, then save. Show the original and the rewritten version side by side so the user can see what changed and why. Save the rewritten prompt to a new markdown file in /mnt/user-data/outputs/, a new file rather than overwriting the original, so the before and after are both kept. Present it if present_files is available.
-</instructions>
-
-<output>
-- A structured diagnostic showing what is present, missing, and ambiguous across the six fields.
-- A brief explanation of what is likely to go wrong with the request as written.
-- 2 to 4 targeted clarifying questions for the most critical gaps.
-- A rewritten version of the request that fills the gaps, in the same register as the original.
-- A before and after comparison so the user can see what changed and why.
-</output>
-
-<guardrails>
-- Do not execute the request itself. You are auditing the delegation, not doing the work.
-- Do not assume you know what the user meant. Name the ambiguity and ask. Do not silently fill it in.
-- Be honest about what is missing, but do not manufacture problems. If three of six fields are already clear, say so.
-- If the request is for a genuinely simple task, say it does not need a full brief and explain why it is probably fine as-is. Match overhead to stakes.
-- Do not use prompt-engineering jargon. Frame everything as clear communication, what a smart recipient would need to do good work.
-</guardrails>
+<role>
+You are a delegation clarity auditor, Part 2 of a four-part prompt kit, the Vague Ask Auditor. You review requests written for AI agents or human colleagues and diagnose what is missing, ambiguous, or likely to produce generic output, then rewrite them. You think in the six fields: goal, context, sources, constraints, quality bar, and definition of done. Your tone is direct and constructive, like a sharp colleague who wants the work to succeed. Read SKILL.md for the shared mindset and the cross-part rules before working this part.
+</role>
+
+<context>
+This part runs two ways. Standalone: SKILL.md routes the user here because they already have a draft request they want audited. Chained from the builder: the Useful Question Builder just produced a prompt and handed it off per SKILL.md Rule 2, so the request to audit is that built prompt. You arrived here by a switch, so you have already re-read this file per SKILL.md Rule 1.
+</context>
+
+<instructions>
+1. Get the request. If standalone, ask: "Paste the request you're about to send, or the one that already produced disappointing results. It can be for an AI, a teammate, a direct report, or a vendor. I'll audit it." Wait for it. If chained from the builder, the request is the prompt just built. Do not ask for it again.
+
+2. Diagnose against the six fields. Goal: is the outcome named or just an activity, would two people reading this produce two different kinds of output. Context: would a smart person joining cold understand the situation, is the audience defined, is the why-now clear. Sources: are materials named, is there a hierarchy of primary versus background. Constraints: are boundaries stated, could the recipient make a technically correct but practically wrong choice because a constraint was missing. Quality bar: does the request define what good means, not just the shape of the artifact, is taste communicated. Definition of done: is the deliverable format specified, is there a stopping point or checkpoint.
+
+3. Deliver the diagnostic in three sections. What's here: fields adequately covered, be specific about what the request gets right. What's missing: fields absent or too vague to act on, and for each gap state plainly what the recipient will most likely guess, infer, or default to if the request is sent as-is. This default-prediction is the most valuable move in the audit; it converts a vague warning into a concrete, visible cost. What's ambiguous: phrases that can be read multiple ways, words like "better", "cleaner", "strategic", "thorough", "comprehensive".
+
+4. Ask only the critical questions. Ask the user 2 to 4 targeted questions, only for the gaps most likely to produce bad output. Do not ask about everything. Wait for the answers.
+
+5. Rebuild the prompt, re-reading the builder first. Before producing the corrected version, re-read prompt-builder.md in full. This is SKILL.md Rule 1: you are switching back to the builder's job, so you reload the builder's instructions and assembly method. Do not patch the prompt from memory. Then rebuild the request using the builder's assembly approach, incorporating the user's answers and filling the gaps. Keep the same tone and register as the original; if the original was casual, keep it casual but clear. Do not inflate the request beyond what the task requires.
+
+6. Show before and after, then save. Show the original and the rewritten version side by side so the user can see what changed and why. Save the rewritten prompt to a new markdown file in /mnt/user-data/outputs/, a new file rather than overwriting the original, so the before and after are both kept. Present it if present_files is available.
+</instructions>
+
+<output>
+- A structured diagnostic showing what is present, missing, and ambiguous across the six fields.
+- A brief explanation of what is likely to go wrong with the request as written.
+- 2 to 4 targeted clarifying questions for the most critical gaps.
+- A rewritten version of the request that fills the gaps, in the same register as the original.
+- A before and after comparison so the user can see what changed and why.
+</output>
+
+<guardrails>
+- Do not execute the request itself. You are auditing the delegation, not doing the work.
+- Do not assume you know what the user meant. Name the ambiguity and ask. Do not silently fill it in.
+- Be honest about what is missing, but do not manufacture problems. If three of six fields are already clear, say so.
+- If the request is for a genuinely simple task, say it does not need a full brief and explain why it is probably fine as-is. Match overhead to stakes.
+- Do not use prompt-engineering jargon. Frame everything as clear communication, what a smart recipient would need to do good work.
+</guardrails>

package/skills/estack-read-claude-session-history/SKILL.md

@@ -1,207 +1,207 @@
----
-name: estack-read-claude-session-history
-version: 1.0.3
-description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, engagement/attention-time accounting (active vs elapsed time, break detection, parallel-chat-safe totals), recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on", "how long did that actually take", "how much did I actually work", "active time", "time I spent".
----
-
-# Read Claude Session History
-
-Search, read, recover, and compare Claude Code session history — across the current session, prior sessions, sibling subagents, all projects, and `.claude-backups` snapshots.
-
-Sessions are stored as `.jsonl` files. Reading them raw is hopeless: 1,000–5,000+ lines of dense JSON per session, 33+ project directories, hundreds of historical sessions. This skill wraps a single CLI that knows the entry schema and exposes ~20 modes.
-
-## Quick start
-
-```bash
-PY="$HOME/.claude/skills/estack-read-claude-session-history/scripts/read_transcript.py"
-
-# What was the last thing the agent said in this session?
-python "$PY" --file <current-session.jsonl> --mode last
-
-# Get a 6-line summary of any session (intent, last activity, edits, tool counts, subagent fanout)
-python "$PY" --file <session.jsonl> --mode brief
-
-# Recover what got cut off by the most recent /compact
-python "$PY" --file <session.jsonl> --mode pre-compact
-
-# Find a session by UUID prefix across all projects
-python "$PY" --mode lookup --uuid abc123de
-
-# Search every session in every project for a phrase
-python "$PY" --mode search --all-projects --query "supabase migration"
-
-# Pull subagent outputs from a fan-out investigation
-python "$PY" --file <parent.jsonl> --mode subagent-finals
-
-# Block-grouped timeline of a whole day across all sessions, with idle gaps
-python "$PY" --mode timeline --date yesterday
-
-# How much focused time did today actually consume? (your attention, not Claude's)
-python "$PY" --mode engagement --date today
-
-# Any mode as structured JSON for piping into the next step
-python "$PY" --mode list --project keel --since 7d --format json
-```
-
-## Time handling — READ THIS before doing anything with time
-
-**Every time the CLI displays is already the user's local time.** JSONL files store
-UTC; the script converts on output. Do NOT add or subtract timezone offsets
-yourself, do NOT cross-reference file mtimes to infer the timezone, and do NOT
-treat raw `"timestamp"` fields from a .jsonl (which ARE UTC) as comparable to CLI
-output. If you need a different zone, pass `--tz` (IANA name like
-`America/New_York`, `UTC`, or an offset like `-4`) — never convert manually.
-`--since/--until/--date` specs are interpreted in that same display timezone.
-
-## Decision tree
-
-```
-What are you trying to do?
-│
-├─ Read the current session / one specific session
-│  ├─ Last assistant message ──────────────────── --mode last
-│  ├─ All advisor responses ───────────────────── --mode advisor
-│  ├─ Content cut off by /compact ─────────────── --mode pre-compact
-│  ├─ Full human-readable dump ────────────────── --mode dump (size-aware)
-│  ├─ 6-line summary for triage ───────────────── --mode brief
-│  └─ Schema/structural diagnosis ─────────────── --mode debug
-│
-├─ Find a session I don't have the path for
-│  ├─ By UUID prefix ──────────────────────────── --mode lookup --uuid <prefix>
-│  ├─ By title or first prompt ────────────────── --mode find --title|--first-prompt
-│  └─ Generate a `claude --resume` command ───── --mode resume-cmd --uuid <prefix>
-│
-├─ Search content
-│  ├─ One session ─────────────────────────────── --mode search --file …
-│  ├─ One project ─────────────────────────────── --mode search --cwd …
-│  ├─ All projects ────────────────────────────── --mode search --all-projects
-│  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
-│
-├─ Forensics on a session
-│  ├─ Chronological tool-call log ────────────── --mode changelog
-│  ├─ Every file touched ─────────────────────── --mode file-edits
-│  └─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
-│
-├─ Subagent (fan-out) work
-│  ├─ List spawned subagents ─────────────────── --mode subagent-list
-│  ├─ Get every subagent's final message ─────── --mode subagent-finals
-│  └─ Forensics on one subagent ──────────────── --mode subagent-tools|subagent-files --subagent …
-│
-├─ Cross-cutting reporting
-│  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
-│  ├─ "What was I doing, when?" / day map ─────── --mode timeline --date yesterday
-│  ├─ "How long did X actually take ME?" ──────── --mode engagement --date … | --project … | --file …
-│  ├─ Count sessions matching a query ─────────── --mode count --query …
-│  └─ Resume where I left off in this project ─── --mode resume-prev --cwd …
-│
-└─ Compare two sessions or two sibling subagents
-   └─ Interleaved diff ──────────────────────── --mode diff --file-a … --file-b …  (or --subagents-of …)
-```
-
-## Quick reference
-
-| Mode | Required flags | Returns |
-|---|---|---|
-| `last` | `--file` | Last N assistant text outputs |
-| `advisor` | `--file` | All `advisor_tool_result` payloads |
-| `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
-| `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
-| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
-| `debug` | `--file` | Entry/block type distributions + probes |
-| `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
-| `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
-| `lookup` | `--uuid <prefix>` | Absolute path (exit 1 missing, exit 2 ambiguous) |
-| `find` | `--title` or `--first-prompt` | Sessions ranked by recency |
-| `resume-cmd` | `--uuid <prefix>` | `cd <cwd>; claude --resume <uuid>` snippet |
-| `changelog` | `--file` | `HH:MM:SS  TOOL  one-line-summary`, day-grouped |
-| `file-edits` | `--file` | Unique paths sorted with op tags |
-| `tool-calls` | `--file` (+ `--tool` filter) | Timestamped per-call blocks |
-| `subagent-list` | `--file` | List sibling subagents with agentType + description |
-| `subagent-finals` | `--file` | Every subagent's final assistant message |
-| `subagent-tools` | `--subagent` | Forensics on one subagent |
-| `subagent-files` | `--subagent` | Files one subagent touched |
-| `resume-prev` | `--cwd` | Banner + dump-style tail of last 10 exchanges |
-| `count` | `--query` (+ scope) | `<N>` to stdout, summary to stderr |
-| `journal` | `--since` (+ scope) | Per-session 5-line block: date·uuid / prompt / ended / edits / tools |
-| `timeline` | `--date` or `--since/--until` (defaults: today, all projects) | Map of WHAT was active WHEN: blocks + idle gaps (no attention claim — that's `engagement`) |
-| `engagement` | `--date` or `--since/--until` or `--file` (defaults: today, all projects) | YOUR attention time: active vs elapsed + ratio per session, parallel-chat-safe totals, breaks |
-| `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
-
-## Global flags
-
-- `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
-- `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
-- `--all-projects` — walk every project under `--root`.
-- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`. Use this instead of `--cwd` when you know the project's name but not its exact path. (Note: for `engagement`, scope filters which sessions are *reported* — the attention stream is always computed across all projects so parallel chats never double-count.)
-- `--file <path>` — single-session scope.
-- `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
-- `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
-- `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).
-- `--break <spec>` — break threshold for `engagement` (`10m` default; `5m` strict, `20m` forgiving). Gaps between your prompts longer than this count as breaks unless you replied right after Claude finished working.
-- `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
-- `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
-- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, `timeline`, and `engagement`.
-- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
-- `--force-dump` — bypass the 5 MB `dump` guard.
-- `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
-
-The current session is marked with `[*]` in `list` output. Status glyphs: ✓ clean, ! interrupted, ? pending-user, ● active. Sessions with a compact marker get `[C]`; sessions with subagents get `[S]`.
-
-## Backup-aware reads
-
-In March 2026 a Claude Code auto-update deleted live `.jsonl` transcripts (GitHub #41591). To survive that class of incident, this machine maintains four backup roots under `C:\Users\2supe\.claude-backups\`:
-
-- `mirror` — continuous mirror
-- `snapshot-24h` — 24-hour-old snapshot
-- `snapshot-1w` — 1-week-old snapshot
-- `snapshot-1mo` — 1-month-old snapshot
-
-Any mode accepts `--root <name>`. The resolved root is printed to stderr.
-
-```bash
-# Find a session that was deleted from live but still in yesterday's snapshot
-python "$PY" --root snapshot-24h --mode lookup --uuid <prefix>
-
-# Compare today's mirror against a week ago to confirm what was lost
-python "$PY" --root snapshot-1w --cwd "C:\Users\2supe\Other Claude Code" --list
-```
-
-See `references/recipes.md` → "Deletion-incident recovery" for the full playbook.
-
-## Common workflows
-
-| Need | Command |
-|---|---|
-| Recover advisor output that scrolled out of context | `--file <session> --mode advisor` |
-| Get back to what you were doing before `/compact` | `--file <session> --mode pre-compact` |
-| Fan-out triage: 14 subagents, want all of their finals | `--file <parent> --mode subagent-finals` (or `--mode brief --include-subagents`) |
-| Find "that session where I asked about supabase rate limits" | `--mode search --all-projects --query "supabase rate limits"` |
-| Resume a project after a few days away | `--mode resume-prev --cwd "<project path>"` |
-| Daily/weekly journal | `--mode journal --since 7d --all-projects` |
-| "Where did yesterday go?" (map of activity) | `--mode timeline --date yesterday` |
-| "How much did I actually work today?" | `--mode engagement --date today` |
-| "How much time on Keel today?" | `--mode engagement --project keel --date today` |
-| "How long did that session take me?" | `--mode engagement --file <session.jsonl>` |
-| Feed session data into a script | any mode + `--format json` |
-
-See `references/recipes.md` for fuller multi-step workflows.
-
-## Windows notes
-
-- Use `python` (not `python3`) on this Windows setup.
-- The script handles UTF-8 stdout/stderr internally — both PowerShell and Bash work fine for single commands.
-- **Piping `--format json` into another command: use Bash.** PowerShell 5.1 pipes inject a UTF-8 BOM and re-encode through the console codepage, breaking `json.load` (see `references/recipes.md` §5c for the PowerShell workaround).
-- File paths with spaces need quoting: `--cwd "C:\Users\2supe\Other Claude Code"`.
-
-## Reference docs
-
-- `references/modes.md` — complete per-mode reference (every flag, every example, exit codes).
-- `references/jsonl-schema.md` — entry/block schema, subagent meta sidecars, compact-marker shape.
-- `references/recipes.md` — multi-step workflows (post-compact recovery, find-then-dump, deletion recovery, week-in-review journal, sibling-agent diff).
-
-## When the modes return empty
-
-If a mode returns empty/unexpected output, run `--mode debug` first. It prints the entry-type distribution, content-block types, and probes for advisor + compact markers — useful when the transcript schema has drifted or when a session was truncated.
+---
+name: estack-read-claude-session-history
+version: 1.0.3
+description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, engagement/attention-time accounting (active vs elapsed time, break detection, parallel-chat-safe totals), recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on", "how long did that actually take", "how much did I actually work", "active time", "time I spent".
+---
+
+# Read Claude Session History
+
+Search, read, recover, and compare Claude Code session history — across the current session, prior sessions, sibling subagents, all projects, and `.claude-backups` snapshots.
+
+Sessions are stored as `.jsonl` files. Reading them raw is hopeless: 1,000–5,000+ lines of dense JSON per session, 33+ project directories, hundreds of historical sessions. This skill wraps a single CLI that knows the entry schema and exposes ~20 modes.
+
+## Quick start
+
+```bash
+PY="$HOME/.claude/skills/estack-read-claude-session-history/scripts/read_transcript.py"
+
+# What was the last thing the agent said in this session?
+python "$PY" --file <current-session.jsonl> --mode last
+
+# Get a 6-line summary of any session (intent, last activity, edits, tool counts, subagent fanout)
+python "$PY" --file <session.jsonl> --mode brief
+
+# Recover what got cut off by the most recent /compact
+python "$PY" --file <session.jsonl> --mode pre-compact
+
+# Find a session by UUID prefix across all projects
+python "$PY" --mode lookup --uuid abc123de
+
+# Search every session in every project for a phrase
+python "$PY" --mode search --all-projects --query "supabase migration"
+
+# Pull subagent outputs from a fan-out investigation
+python "$PY" --file <parent.jsonl> --mode subagent-finals
+
+# Block-grouped timeline of a whole day across all sessions, with idle gaps
+python "$PY" --mode timeline --date yesterday
+
+# How much focused time did today actually consume? (your attention, not Claude's)
+python "$PY" --mode engagement --date today
+
+# Any mode as structured JSON for piping into the next step
+python "$PY" --mode list --project keel --since 7d --format json
+```
+
+## Time handling — READ THIS before doing anything with time
+
+**Every time the CLI displays is already the user's local time.** JSONL files store
+UTC; the script converts on output. Do NOT add or subtract timezone offsets
+yourself, do NOT cross-reference file mtimes to infer the timezone, and do NOT
+treat raw `"timestamp"` fields from a .jsonl (which ARE UTC) as comparable to CLI
+output. If you need a different zone, pass `--tz` (IANA name like
+`America/New_York`, `UTC`, or an offset like `-4`) — never convert manually.
+`--since/--until/--date` specs are interpreted in that same display timezone.
+
+## Decision tree
+
+```
+What are you trying to do?
+│
+├─ Read the current session / one specific session
+│  ├─ Last assistant message ──────────────────── --mode last
+│  ├─ All advisor responses ───────────────────── --mode advisor
+│  ├─ Content cut off by /compact ─────────────── --mode pre-compact
+│  ├─ Full human-readable dump ────────────────── --mode dump (size-aware)
+│  ├─ 6-line summary for triage ───────────────── --mode brief
+│  └─ Schema/structural diagnosis ─────────────── --mode debug
+│
+├─ Find a session I don't have the path for
+│  ├─ By UUID prefix ──────────────────────────── --mode lookup --uuid <prefix>
+│  ├─ By title or first prompt ────────────────── --mode find --title|--first-prompt
+│  └─ Generate a `claude --resume` command ───── --mode resume-cmd --uuid <prefix>
+│
+├─ Search content
+│  ├─ One session ─────────────────────────────── --mode search --file …
+│  ├─ One project ─────────────────────────────── --mode search --cwd …
+│  ├─ All projects ────────────────────────────── --mode search --all-projects
+│  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
+│
+├─ Forensics on a session
+│  ├─ Chronological tool-call log ────────────── --mode changelog
+│  ├─ Every file touched ─────────────────────── --mode file-edits
+│  └─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
+│
+├─ Subagent (fan-out) work
+│  ├─ List spawned subagents ─────────────────── --mode subagent-list
+│  ├─ Get every subagent's final message ─────── --mode subagent-finals
+│  └─ Forensics on one subagent ──────────────── --mode subagent-tools|subagent-files --subagent …
+│
+├─ Cross-cutting reporting
+│  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
+│  ├─ "What was I doing, when?" / day map ─────── --mode timeline --date yesterday
+│  ├─ "How long did X actually take ME?" ──────── --mode engagement --date … | --project … | --file …
+│  ├─ Count sessions matching a query ─────────── --mode count --query …
+│  └─ Resume where I left off in this project ─── --mode resume-prev --cwd …
+│
+└─ Compare two sessions or two sibling subagents
+   └─ Interleaved diff ──────────────────────── --mode diff --file-a … --file-b …  (or --subagents-of …)
+```
+
+## Quick reference
+
+| Mode | Required flags | Returns |
+|---|---|---|
+| `last` | `--file` | Last N assistant text outputs |
+| `advisor` | `--file` | All `advisor_tool_result` payloads |
+| `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
+| `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
+| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
+| `debug` | `--file` | Entry/block type distributions + probes |
+| `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
+| `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
+| `lookup` | `--uuid <prefix>` | Absolute path (exit 1 missing, exit 2 ambiguous) |
+| `find` | `--title` or `--first-prompt` | Sessions ranked by recency |
+| `resume-cmd` | `--uuid <prefix>` | `cd <cwd>; claude --resume <uuid>` snippet |
+| `changelog` | `--file` | `HH:MM:SS  TOOL  one-line-summary`, day-grouped |
+| `file-edits` | `--file` | Unique paths sorted with op tags |
+| `tool-calls` | `--file` (+ `--tool` filter) | Timestamped per-call blocks |
+| `subagent-list` | `--file` | List sibling subagents with agentType + description |
+| `subagent-finals` | `--file` | Every subagent's final assistant message |
+| `subagent-tools` | `--subagent` | Forensics on one subagent |
+| `subagent-files` | `--subagent` | Files one subagent touched |
+| `resume-prev` | `--cwd` | Banner + dump-style tail of last 10 exchanges |
+| `count` | `--query` (+ scope) | `<N>` to stdout, summary to stderr |
+| `journal` | `--since` (+ scope) | Per-session 5-line block: date·uuid / prompt / ended / edits / tools |
+| `timeline` | `--date` or `--since/--until` (defaults: today, all projects) | Map of WHAT was active WHEN: blocks + idle gaps (no attention claim — that's `engagement`) |
+| `engagement` | `--date` or `--since/--until` or `--file` (defaults: today, all projects) | YOUR attention time: active vs elapsed + ratio per session, parallel-chat-safe totals, breaks |
+| `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
+
+## Global flags
+
+- `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
+- `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
+- `--all-projects` — walk every project under `--root`.
+- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`. Use this instead of `--cwd` when you know the project's name but not its exact path. (Note: for `engagement`, scope filters which sessions are *reported* — the attention stream is always computed across all projects so parallel chats never double-count.)
+- `--file <path>` — single-session scope.
+- `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
+- `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
+- `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).
+- `--break <spec>` — break threshold for `engagement` (`10m` default; `5m` strict, `20m` forgiving). Gaps between your prompts longer than this count as breaks unless you replied right after Claude finished working.
+- `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
+- `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
+- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, `timeline`, and `engagement`.
+- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
+- `--force-dump` — bypass the 5 MB `dump` guard.
+- `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
+
+The current session is marked with `[*]` in `list` output. Status glyphs: ✓ clean, ! interrupted, ? pending-user, ● active. Sessions with a compact marker get `[C]`; sessions with subagents get `[S]`.
+
+## Backup-aware reads
+
+In March 2026 a Claude Code auto-update deleted live `.jsonl` transcripts (GitHub #41591). To survive that class of incident, this machine maintains four backup roots under `C:\Users\2supe\.claude-backups\`:
+
+- `mirror` — continuous mirror
+- `snapshot-24h` — 24-hour-old snapshot
+- `snapshot-1w` — 1-week-old snapshot
+- `snapshot-1mo` — 1-month-old snapshot
+
+Any mode accepts `--root <name>`. The resolved root is printed to stderr.
+
+```bash
+# Find a session that was deleted from live but still in yesterday's snapshot
+python "$PY" --root snapshot-24h --mode lookup --uuid <prefix>
+
+# Compare today's mirror against a week ago to confirm what was lost
+python "$PY" --root snapshot-1w --cwd "C:\Users\2supe\Other Claude Code" --list
+```
+
+See `references/recipes.md` → "Deletion-incident recovery" for the full playbook.
+
+## Common workflows
+
+| Need | Command |
+|---|---|
+| Recover advisor output that scrolled out of context | `--file <session> --mode advisor` |
+| Get back to what you were doing before `/compact` | `--file <session> --mode pre-compact` |
+| Fan-out triage: 14 subagents, want all of their finals | `--file <parent> --mode subagent-finals` (or `--mode brief --include-subagents`) |
+| Find "that session where I asked about supabase rate limits" | `--mode search --all-projects --query "supabase rate limits"` |
+| Resume a project after a few days away | `--mode resume-prev --cwd "<project path>"` |
+| Daily/weekly journal | `--mode journal --since 7d --all-projects` |
+| "Where did yesterday go?" (map of activity) | `--mode timeline --date yesterday` |
+| "How much did I actually work today?" | `--mode engagement --date today` |
+| "How much time on Keel today?" | `--mode engagement --project keel --date today` |
+| "How long did that session take me?" | `--mode engagement --file <session.jsonl>` |
+| Feed session data into a script | any mode + `--format json` |
+
+See `references/recipes.md` for fuller multi-step workflows.
+
+## Windows notes
+
+- Use `python` (not `python3`) on this Windows setup.
+- The script handles UTF-8 stdout/stderr internally — both PowerShell and Bash work fine for single commands.
+- **Piping `--format json` into another command: use Bash.** PowerShell 5.1 pipes inject a UTF-8 BOM and re-encode through the console codepage, breaking `json.load` (see `references/recipes.md` §5c for the PowerShell workaround).
+- File paths with spaces need quoting: `--cwd "C:\Users\2supe\Other Claude Code"`.
+
+## Reference docs
+
+- `references/modes.md` — complete per-mode reference (every flag, every example, exit codes).
+- `references/jsonl-schema.md` — entry/block schema, subagent meta sidecars, compact-marker shape.
+- `references/recipes.md` — multi-step workflows (post-compact recovery, find-then-dump, deletion recovery, week-in-review journal, sibling-agent diff).
+
+## When the modes return empty
+
+If a mode returns empty/unexpected output, run `--mode debug` first. It prints the entry-type distribution, content-block types, and probes for advisor + compact markers — useful when the transcript schema has drifted or when a session was truncated.
 ---
 
 ## Skill Feedback