session-analyzer

Session Analyzer Skill

用于事后分析的工具，可根据 SKILL.md 规范验证 Claude Code 会话行为。

用途

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

1. 预期行为与实际行为 - Skill 是否遵循了 SKILL.md 工作流？
2. 组件调用 - SubAgents、Hooks 和工具是否正确调用？
3. 产物 - 是否创建/删除了预期文件？
4. Bug 检测 - 是否存在意外错误或偏差？

---

输入要求

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

---

阶段 1：定位会话文件

步骤 1.1：查找会话文件

会话文件位于 ~/.claude/：

# Main session log
~/.claude/projects/-{encoded-cwd}/{sessionId}.jsonl

# Debug log (detailed)
~/.claude/debug/{sessionId}.txt

# Agent transcripts (if subagents were used)
~/.claude/projects/-{encoded-cwd}/agent-{agentId}.jsonl

使用脚本定位文件：

${baseDir}/scripts/find-session-files.sh {sessionId}

步骤 1.2：确认文件存在

继续操作前，检查所有必需文件是否存在。如果缺少调试日志，分析将受到限制。

---

阶段 2：解析目标 SKILL.md

步骤 2.1：提取预期组件

读取目标 SKILL.md 并识别：

从 YAML Frontmatter 中：

• hooks.PreToolUse - 预期的 PreToolUse hooks 和匹配器
• hooks.PostToolUse - 预期的 PostToolUse hooks
• hooks.Stop - 预期的 Stop hooks
• hooks.SubagentStop - 预期的 SubagentStop hooks
• allowed-tools - 该 skill 允许使用的工具

从 Markdown 正文中：

• 提到的 SubAgents（Task(subagent_type="...")）
• 调用的 Skills（Skill("...")）
• 创建的产物（.dev-flow/drafts/、.dev-flow/plans/ 等）
• 工作流步骤和条件

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

根据 SKILL.md 分析创建检查清单：

## Expected Behavior

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

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

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

### Workflow
- [ ] Interview Mode before Plan Generation
- [ ] User explicit request triggers plan generation
- [ ] Reviewer REJECT causes revision loop

---

阶段 3：分析调试日志

调试日志（~/.claude/debug/{sessionId}.txt）包含详细的执行跟踪信息。

步骤 3.1：提取 SubAgent 调用

搜索模式：

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

使用脚本：

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

步骤 3.2：提取 Hook 事件

搜索模式：

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

使用脚本：

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

步骤 3.3：提取工具调用

搜索模式：

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

步骤 3.4：提取 Hook 结果

对于基于提示词的 hooks，查找模型响应：

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

---

阶段 4：验证产物

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

对于每个预期产物：

1. 在调试日志中搜索 FileHistory: Tracked file modification for {path}
2. 搜索 File {path} written atomically
3. 验证当前文件系统状态

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

对于应删除的文件：

1. 在 Bash 调用中搜索 rm 命令
2. 验证文件在文件系统中已不存在

---

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

步骤 5.1：构建对比表

| 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) | ✅ |

步骤 5.2：识别偏差

标记所有不匹配项：

• 缺少组件调用
• 操作顺序错误
• Hook 失败
• 缺少产物
• 意外错误

---

阶段 6：生成报告

报告模板

# Session Analysis Report

## Session Info
- **Session ID**: {sessionId}
- **Target Skill**: {skillPath}
- **Analysis Date**: {date}

---

## 1. Expected Behavior (from SKILL.md)

[Summary of expected workflow]

---

## 2. Skill/SubAgent/Hook Verification

### SubAgents
| SubAgent | Expected | Actual | Time | Result |
|----------|----------|--------|------|--------|
| ... | ... | ... | ... | ✅/❌ |

### Hooks
| Hook | Matcher | Triggered | Result |
|------|---------|-----------|--------|
| ... | ... | ... | ✅/❌ |

---

## 3. Artifacts Verification

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

---

## 4. Issues/Bugs

| Severity | Description | Location |
|----------|-------------|----------|
| ... | ... | ... |

---

## 5. Overall Result

**Verdict**: ✅ PASS / ❌ FAIL

**Summary**: [1-2 sentence summary]

---

脚本参考

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

---

使用示例

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

---

其他资源

参考文件

• references/analysis-patterns.md - 用于日志分析的详细 grep 模式
• references/common-issues.md - 已知问题和故障排除

脚本

• scripts/find-session-files.sh - 会话文件定位器
• scripts/extract-subagent-calls.sh - SubAgent 调用提取器
• scripts/extract-hook-events.sh - Hook 事件提取器