session-analyzer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Analyzer Skill

会话分析Skill

Post-hoc analysis tool for validating Claude Code session behavior against SKILL.md specifications.

一款用于对照SKILL.md规范验证Claude Code会话行为的事后分析工具。

Purpose

用途

Analyze completed sessions to verify:

Expected vs Actual Behavior - Did the skill follow SKILL.md workflow?
Component Invocations - Were SubAgents, Hooks, and Tools called correctly?
Artifacts - Were expected files created/deleted?
Bug Detection - Any unexpected errors or deviations?

分析已完成的会话，以验证：

预期行为 vs 实际行为 - 技能是否遵循SKILL.md工作流？
组件调用 - SubAgents、Hooks和Tools是否被正确调用？
工件 - 是否创建/删除了预期的文件？
Bug检测 - 是否存在意外错误或偏差？

Input Requirements

输入要求

Parameter	Required	Description
`sessionId`	YES	UUID of the session to analyze
`targetSkill`	YES	Path to SKILL.md to validate against
`additionalRequirements`	NO	Extra validation criteria

参数	是否必填	描述
`sessionId`	是	待分析会话的UUID
`targetSkill`	是	用于验证的SKILL.md路径
`additionalRequirements`	否	额外的验证标准

Phase 1: Locate Session Files

阶段1：定位会话文件

Step 1.1: Find Session Files

步骤1.1：查找会话文件

Session files are located in

~/.claude/

bash

undefined

会话文件存储在

~/.claude/

目录下：

bash

undefined

Main session log

主会话日志

~/.claude/projects/-{encoded-cwd}/{sessionId}.jsonl

Debug log (detailed)

调试日志（详细）

~/.claude/debug/{sessionId}.txt

Agent transcripts (if subagents were used)

Agent对话记录（若使用了子代理）

~/.claude/projects/-{encoded-cwd}/agent-{agentId}.jsonl


Use script to locate files:
```bash
${baseDir}/scripts/find-session-files.sh {sessionId}

~/.claude/projects/-{encoded-cwd}/agent-{agentId}.jsonl


使用脚本定位文件：
```bash
${baseDir}/scripts/find-session-files.sh {sessionId}

Step 1.2: Verify Files Exist

步骤1.2：验证文件是否存在

Check all required files exist before proceeding. If debug log is missing, analysis will be limited.

在继续分析前，检查所有必要文件是否存在。若缺少调试日志，分析范围将受限。

Phase 2: Parse Target SKILL.md

阶段2：解析目标SKILL.md

Step 2.1: Extract Expected Components

步骤2.1：提取预期组件

Read the target SKILL.md and identify:

From YAML Frontmatter:

```
hooks.PreToolUse
```
- Expected PreToolUse hooks and matchers
```
hooks.PostToolUse
```
- Expected PostToolUse hooks
```
hooks.Stop
```
- Expected Stop hooks
```
hooks.SubagentStop
```
- Expected SubagentStop hooks
```
allowed-tools
```
- Tools the skill is allowed to use

From Markdown Body:

SubAgents mentioned (
```
Task(subagent_type="...")
```
)
Skills called (
```
Skill("...")
```
)
Artifacts created (
```
.dev-flow/drafts/
```
,
```
.dev-flow/plans/
```
, etc.)
Workflow steps and conditions

读取目标SKILL.md并识别：

从YAML前置元数据中：

```
hooks.PreToolUse
```
- 预期的PreToolUse钩子及匹配器
```
hooks.PostToolUse
```
- 预期的PostToolUse钩子
```
hooks.Stop
```
- 预期的Stop钩子
```
hooks.SubagentStop
```
- 预期的SubagentStop钩子
```
allowed-tools
```
- 技能允许使用的工具

从Markdown正文中：

提及的SubAgents（
```
Task(subagent_type="...")
```
）
调用的Skills（
```
Skill("...")
```
）
创建的工件（
```
.dev-flow/drafts/
```
,
```
.dev-flow/plans/
```
等）
工作流步骤及条件

Step 2.2: Build Expected Behavior Checklist

步骤2.2：构建预期行为检查清单

Create checklist from SKILL.md analysis:

markdown

undefined

通过分析SKILL.md创建检查清单：

markdown

undefined

Expected Behavior

预期行为

SubAgents

Explore agent called (parallel, run_in_background)
gap-analyzer called before plan generation
reviewer called after plan creation

调用了Explore agent（并行，后台运行）
在生成计划前调用了gap-analyzer
在创建计划后调用了reviewer

Hooks

PreToolUse[Edit|Write] triggers plan-guard.sh
Stop hook validates reviewer approval

PreToolUse[Edit|Write]触发了plan-guard.sh
Stop钩子验证了reviewer的批准

Artifacts

工件

Draft file created at .dev-flow/drafts/{name}.md
Plan file created at .dev-flow/plans/{name}.md
Draft file deleted after OKAY

在.dev-flow/drafts/{name}.md路径创建了草稿文件
在.dev-flow/plans/{name}.md路径创建了计划文件
获得OKAY后删除了草稿文件

Workflow

工作流

Interview Mode before Plan Generation
User explicit request triggers plan generation
Reviewer REJECT causes revision loop

---

在生成计划前进入访谈模式
用户明确请求触发计划生成
Reviewer的REJECT指令触发修订循环

---

Phase 3: Analyze Debug Log

阶段3：分析调试日志

The debug log (

~/.claude/debug/{sessionId}.txt

) contains detailed execution traces.

调试日志（

~/.claude/debug/{sessionId}.txt

）包含详细的执行轨迹。

Step 3.1: Extract SubAgent Calls

步骤3.1：提取SubAgent调用记录

Search patterns:

SubagentStart with query: {agent-name}
SubagentStop with query: {agent-id}

Use script:

bash

${baseDir}/scripts/extract-subagent-calls.sh {debug-log-path}

搜索模式：

SubagentStart with query: {agent-name}
SubagentStop with query: {agent-id}

使用脚本：

bash

${baseDir}/scripts/extract-subagent-calls.sh {debug-log-path}

Step 3.2: Extract Hook Events

步骤3.2：提取Hook事件

Search patterns:

Getting matching hook commands for {HookEvent} with query: {tool-name}
Matched {N} unique hooks for query "{query}"
Hooks: Processing prompt hook with prompt: {prompt}
Hooks: Prompt hook condition was met/not met
permissionDecision: allow/deny

Use script:

bash

${baseDir}/scripts/extract-hook-events.sh {debug-log-path}

搜索模式：

Getting matching hook commands for {HookEvent} with query: {tool-name}
Matched {N} unique hooks for query "{query}"
Hooks: Processing prompt hook with prompt: {prompt}
Hooks: Prompt hook condition was met/not met
permissionDecision: allow/deny

使用脚本：

bash

${baseDir}/scripts/extract-hook-events.sh {debug-log-path}

Step 3.3: Extract Tool Calls

步骤3.3：提取工具调用记录

Search patterns:

executePreToolHooks called for tool: {tool-name}
File {path} written atomically

搜索模式：

executePreToolHooks called for tool: {tool-name}
File {path} written atomically

Step 3.4: Extract Hook Results

步骤3.4：提取Hook执行结果

For prompt-based hooks, find the model response:

Hooks: Model response: {
  "ok": true/false,
  "reason": "..."
}

对于基于提示的钩子，查找模型响应：

Hooks: Model response: {
  "ok": true/false,
  "reason": "..."
}

Phase 4: Verify Artifacts

阶段4：验证工件

Step 4.1: Check File Creation

步骤4.1：检查文件创建情况

For each expected artifact:

Search debug log for

FileHistory: Tracked file modification for {path}

Search for
```
File {path} written atomically
```
Verify current filesystem state

针对每个预期工件：

在调试日志中搜索

FileHistory: Tracked file modification for {path}

搜索
```
File {path} written atomically
```
验证当前文件系统状态

Step 4.2: Check File Deletion

步骤4.2：检查文件删除情况

For files that should be deleted:

Search for
```
rm
```
commands in Bash calls
Verify file no longer exists on filesystem

针对应被删除的文件：

在Bash调用中搜索
```
rm
```
命令
验证文件已不存在于文件系统中

Phase 5: Compare Expected vs Actual

阶段5：对比预期与实际情况

Step 5.1: Build Comparison Table

步骤5.1：构建对比表格

markdown

| Component | Expected | Actual | Status |
|-----------|----------|--------|--------|
| Explore agent | 2 parallel calls | 2 calls at 09:39:26 | ✅ |
| gap-analyzer | Called before plan | Called at 09:43:08 | ✅ |
| reviewer | Called after plan | 2 calls (REJECT→OKAY) | ✅ |
| PreToolUse hook | Edit\|Write matcher | Triggered for Write | ✅ |
| Stop hook | Validates approval | Returned ok:true | ✅ |
| Draft file | Created then deleted | Created→Deleted | ✅ |
| Plan file | Created | Exists (10KB) | ✅ |

markdown

| 组件 | 预期 | 实际 | 状态 |
|-----------|----------|--------|--------|
| Explore agent | 2次并行调用 | 于09:39:26执行2次调用 | ✅ |
| gap-analyzer | 在生成计划前调用 | 于09:43:08调用 | ✅ |
| reviewer | 在生成计划后调用 | 2次调用（REJECT→OKAY） | ✅ |
| PreToolUse hook | Edit\|Write匹配器 | 针对Write触发 | ✅ |
| Stop hook | 验证批准状态 | 返回ok:true | ✅ |
| 草稿文件 | 创建后删除 | 创建→删除 | ✅ |
| 计划文件 | 创建 | 已存在（10KB） | ✅ |

Step 5.2: Identify Deviations

步骤5.2：识别偏差

Flag any mismatches:

Missing component calls
Wrong order of operations
Hook failures
Missing artifacts
Unexpected errors

标记所有不匹配项：

缺失的组件调用
错误的操作顺序
Hook执行失败
缺失的工件
意外错误

Phase 6: Generate Report

阶段6：生成报告

Report Template

报告模板

markdown

undefined

markdown

undefined

Session Analysis Report

会话分析报告

Session Info

会话信息

Session ID: {sessionId}
Target Skill: {skillPath}
Analysis Date: {date}

Session ID: {sessionId}
目标Skill: {skillPath}
分析日期: {date}

1. Expected Behavior (from SKILL.md)

1. 预期行为（来自SKILL.md）

[Summary of expected workflow]

[预期工作流摘要]

2. Skill/SubAgent/Hook Verification

2. Skill/SubAgent/Hook验证

SubAgents

SubAgent	Expected	Actual	Time	Result
...	...	...	...	✅/❌

SubAgent	预期	实际	时间	结果
...	...	...	...	✅/❌

Hooks

Hook	Matcher	Triggered	Result
...	...	...	✅/❌

Hook	匹配器	是否触发	结果
...	...	...	✅/❌

3. Artifacts Verification

3. 工件验证

Artifact	Path	Expected State	Actual State
...	...	...	✅/❌

工件	路径	预期状态	实际状态
...	...	...	✅/❌

4. Issues/Bugs

4. 问题/Bug

Severity	Description	Location
...	...	...

严重程度	描述	位置
...	...	...

5. Overall Result

5. 整体结果

Verdict: ✅ PASS / ❌ FAIL

Summary: [1-2 sentence summary]

---

结论: ✅ 通过 / ❌ 失败

摘要: [1-2句话总结]

---

Scripts Reference

脚本参考

Script	Purpose
`find-session-files.sh`	Locate all files for a session ID
`extract-subagent-calls.sh`	Parse subagent invocations from debug log
`extract-hook-events.sh`	Parse hook events from debug log

脚本	用途
`find-session-files.sh`	定位某会话ID对应的所有文件
`extract-subagent-calls.sh`	从调试日志中解析子代理调用记录
`extract-hook-events.sh`	从调试日志中解析Hook事件

Usage Example

使用示例

User: "Analyze session 3cc71c9f-d27a-4233-9dbc-c4f07ea6ec5b against .claude/skills/specify/SKILL.md"

1. Find session files
2. Parse SKILL.md → Expected: Explore, gap-analyzer, reviewer, hooks
3. Analyze debug log → Extract actual calls
4. Verify artifacts → Check .dev-flow/
5. Compare → Build verification table
6. Generate report → PASS/FAIL with details

用户: "分析会话3cc71c9f-d27a-4233-9dbc-c4f07ea6ec5b，对照.claude/skills/specify/SKILL.md"

1. 查找会话文件
2. 解析SKILL.md → 预期：Explore、gap-analyzer、reviewer、hooks
3. 分析调试日志 → 提取实际调用记录
4. 验证工件 → 检查.dev-flow/目录
5. 对比 → 构建验证表格
6. 生成报告 → 给出通过/失败的详细结果