terrylica/cc-skills

session-debrief

Analyze a Claude Code session in three modes: handoff document, error forensics (warnings Claude ignored or deferred), and chronological summary.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/terrylica/cc-skills --skill session-debrief

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

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. Chunked and merged 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 debrief LLM's 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 extracted history is larger than the script's hard-coded budget (890K chars, about 243K tokens; see Configuration), the script splits it at turn boundaries, analyses each chunk with the debrief LLM, then merges the partial analyses in one synthesis call. It prints the parts separately only when the partials are themselves too large to merge. All three goals chunk the same way.

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/<you>/eon/cc-skills → -Users-<you>-eon-cc-skills


Script Invocation Reference

bash
# 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 the LLM
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

SettingSourceDefault
LLM API keyDEBRIEF_LLM_API_KEY (or SUB2API_KEY) env var; otherwise the operator's self-custody vault: vault get cc-skills-tools-sub2api api_keyRequired
LLM endpointDEBRIEF_LLM_API_URL env var, or a DEBRIEF_LLM_API_URL= line in ${XDG_CONFIG_HOME:-~/.config}/cc-skills/debrief.envRequired, no default
ModelDEBRIEF_LLM_MODEL env var (nothing sets it; effectively hardcoded)claude-sonnet-5[1m]
Max output tokensHardcoded16384 per call
Context budgetHardcoded890K chars (~243K tokens)
Default time window--since48 hours
Session chaining--no-chain to disableEnabled

Find Recent Sessions (Manual)

bash
# 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

IssueCauseFix
Cannot determine project dirCWD not a known projectUse --project-dir ~/.claude/projects/<key>
No sessions foundNo sessions in time windowIncrease --since (e.g., --since 336 for 2 weeks)
could not resolve the debrief LLM keyNo key in the environment and the vault lookup failedExport DEBRIEF_LLM_API_KEY, or store it once with vault set cc-skills-tools-sub2api api_key
no LLM endpoint configured (exit 78)DEBRIEF_LLM_API_URL unsetExport it, or add it to ~/.config/cc-skills/debrief.env
context window exceedsSingle session too largeUse --dry --verbose to check size; try --no-chain
Output arrives as several PART sectionsThe partial analyses were too large to mergeExpected behavior — each part covers a range of turns

Post-Execution Reflection

After this skill completes, reflect before closing the task:

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

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

同じリポジトリから

関連する Skills

すべての Skills
terrylica
コミュニティ

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1時間の導入数
1
GitHub Stars
2
更新日
11月5日
terrylica
コミュニティ

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1時間の導入数
1
GitHub Stars
2
更新日
11月5日
terrylica
コミュニティ

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1時間の導入数
1
GitHub Stars
2
更新日
11月5日
terrylica
コミュニティ

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1時間の導入数
1
GitHub Stars
2
更新日
11月5日