session-debrief

name	session-debrief
description	Analyze Claude Code sessions in three expert modes — Handoff Document (exhaustive context extraction for the next developer or session), Error.
allowed-tools	Read, Bash, Grep, Glob, AskUserQuestion, Agent

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Execution Model — MANDATORY

You MUST use AskUserQuestion TWICE before spawning an Agent. Ask for the goal first, then the time range. Then spawn the Agent with resolved parameters.

---

Step 1 — Ask Which Goal

Use AskUserQuestion to present exactly these three choices:

Which analysis mode?

1. Handoff Document — Exhaustive context for the next developer or Claude session continuing this work. Extracts every decision, file, command, gotcha, incomplete item, and next step. Multiple MiniMax chunks if needed for full coverage.
2. Error Forensics — Complete inventory of every warning, error, deprecation, failed command, and anomaly that occurred — especially ones Claude acknowledged but ignored or deferred. Full verbatim detail with file paths and commands.
3. Chronological Summary — Dense technical timeline of everything that happened: every decision, change, problem, discovery, and outcome in turn order. As concise as possible while capturing maximum events.

---

Step 2 — Ask Time Range

Use AskUserQuestion to ask:

How far back should sessions be included?

• 48 hours (default — last 2 days)
• 1 week (168 hours)
• 1 month (720 hours)
• Custom — enter any natural language like "3 days", "2 weeks", "5 hours", "since Monday"

Convert their answer to hours for --since <N>:

• "3 days" → 72
• "2 weeks" → 336
• "5 hours" → 5
• "since Monday" → calculate hours from now to last Monday

---

Step 3 — Spawn Agent

Agent(
  description: "Session analysis - Goal <N>: <name>",
  prompt: "Run session analysis for the current project. Execute:

    bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \\
      --goal <1|2|3> \\
      --since <hours> \\
      --verbose

  Print all output exactly as-is. Do not filter or summarize.
  If the command fails, show the full error and suggest troubleshooting.",
  run_in_background: true
)

Do NOT add --shots — it only applies to legacy 50-perspectives mode.

When the Agent returns, present the output directly to the user with no additional summarization — the MiniMax output IS the result.

---

Session Blind Spots — Reference

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

The Three Goals

Goal 1: Handoff Document

The most comprehensive output mode. Extracts everything the next developer or AI session needs to continue work without asking questions.

Output structure:

• WHAT WAS ACCOMPLISHED — every completed task, file, command (exhaustive)
• CURRENT STATE — what works right now, what was modified
• INCOMPLETE / BROKEN — unfinished items, unresolved errors, deferred work
• KEY DECISIONS & RATIONALE — why things were done this way
• CRITICAL GOTCHAS & CONTEXT — non-obvious facts, workarounds, landmines
• NEXT STEPS (PRIORITY ORDER) — concrete actions to start next session with

If the session history spans more than MiniMax's context window (~260K tokens), the script automatically chunks by session and produces multiple parts.

Goal 2: Error Forensics

Every warning, error, and anomaly — especially the ones Claude moved past.

Each finding includes:

• Exact turn number
• Trigger (command/tool that caused it)
• File/path involved
• Complete verbatim error text (not paraphrased)
• Resolution status: UNRESOLVED / PARTIAL / RESOLVED
• What Claude did (acknowledged? ignored? deferred?)

Goal 3: Chronological Summary

Dense technical timeline: one bullet per significant event, in turn order.

• Groups into phases when clear phases emerge
• Marks unresolved errors with ⚠
• Captures decisions + rationale
• Ends with Key Outcomes (3-7 most important results)

---

How Sessions Are Discovered

The script automatically finds all sessions for the current project (derived from the working directory) modified within the time window:

1. Scans ~/.claude/projects/<project-key>/ for .jsonl files
2. Includes files modified within the --since window
3. For each session, follows parent chains (continuation sessions) for full context
4. Sorts chronologically (oldest first) for coherent narrative

The project key is the absolute path with / replaced by -. For example: /Users/terryli/eon/cc-skills → -Users-terryli-eon-cc-skills

---

Script Invocation Reference

# Focused goal mode — recommended
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 1 --since 48         # Handoff: last 48 hours
  --goal 2 --since 168        # Error forensics: last week
  --goal 3 --since 720        # Summary: last month

# Debug: show extracted payload without calling MiniMax
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 1 --since 48 --dry --verbose

# Override project dir (if auto-detection fails)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 2 --since 48 --project-dir ~/.claude/projects/-Users-foo-myrepo

# Skip parent chain tracing (faster, current window only)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 3 --since 48 --no-chain

# Legacy 50-perspectives mode (single session UUID)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  <session-uuid>

---

Configuration

Setting	Source	Default
MiniMax API key	~/.claude/.secrets/ccterrybot-telegram (MINIMAX_API_KEY=...)	Required
Model	MINIMAX_MODEL env var (global mise config)	MiniMax-M2.7-highspeed
Max output tokens	Hardcoded	16384 per call
Context budget	Hardcoded	890K chars (~243K tokens)
Default time window	--since	48 hours
Session chaining	--no-chain to disable	Enabled

---

Find Recent Sessions (Manual)

# Sessions for current project (key = cwd with / replaced by -)
ls -lt ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl 2>/dev/null | head -10

# All projects, most recent first
ls -lt ~/.claude/projects/*/*.jsonl 2>/dev/null | head -20

---

Troubleshooting

Issue	Cause	Fix
Cannot determine project dir	CWD not a known project	Use --project-dir ~/.claude/projects/<key>
No sessions found	No sessions in time window	Increase --since (e.g., --since 336 for 2 weeks)
MINIMAX_API_KEY not found	Missing secrets file	Check ~/.claude/.secrets/ccterrybot-telegram
context window exceeds	Single session too large	Use --dry --verbose to check size; try --no-chain
Goal 1 produces multiple parts	Sessions exceeded single budget	Expected behavior — multiple chunks = maximum coverage

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing.
1. What failed? — Fix the instruction that caused it.
2. What worked better than expected? — Promote to recommended practice.
3. What drifted? — Fix any script, reference, or dependency that no longer matches reality.
4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.