forensics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Forensics Skill

Purpose

用途

Investigate failed or stuck workflows through post-mortem analysis of git history, plan files, and session artifacts. The forensics skill answers "what went wrong and why" -- it detects workflow-level failures that individual tool errors don't reveal.

Key distinction: A tool error is "ruff found 3 lint errors." A workflow failure is "the agent entered a fix/retry loop editing the same file 5 times and never progressed." The error-learner handles tool-level errors. Forensics handles workflow-level patterns.

通过对git历史记录、计划文件和会话工件的事后分析，调查失败或停滞的工作流。Forensics Skill旨在解答“出了什么问题以及为什么会出问题”——它能检测单个工具错误无法揭示的工作流层面故障。

核心区别：工具错误是指“ruff检测到3个lint错误”这类问题，而工作流故障是指“Agent进入修复/重试循环，反复编辑同一文件5次却从未取得进展”这类情况。Error Learner负责处理工具层面的错误，Forensics则负责处理工作流层面的模式问题。

Operator Context

操作环境

This skill operates as a read-only diagnostic instrument. It examines git history, plan files, and worktree state to detect anomaly patterns, then produces a structured report. It never modifies files, creates commits, or attempts repairs.

该Skill作为只读诊断工具运行。它会检查git历史记录、计划文件和工作区状态以检测异常模式，然后生成结构化报告。它绝不会修改文件、创建提交或尝试修复问题。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

READ-ONLY: Never modify files, create commits, or attempt repairs. WHY: A diagnostic tool that modifies state destroys the evidence it needs to analyze. Forensics examines -- it does not fix. The tool restriction to Read/Grep/Glob enforces this at the platform level.
CLAUDE.md Compliance: Read and follow repository CLAUDE.md before analysis. Repository conventions inform what "normal" looks like (e.g., expected branch patterns, required artifacts).
Credential Scrubbing: Before including any file content or path in the report, scan for and redact patterns matching secrets (API keys, tokens, passwords, connection strings). WHY: Diagnostic reports may be shared or logged. Leaking credentials through a forensics report is worse than the original workflow failure.
Path Redaction: Redact absolute home directory paths in report output. Replace paths like
```
/home/alice/
```
or
```
/Users/alice/
```
with
```
~/
```
. WHY: Reports shared across teams should not expose filesystem layout or usernames.
Confidence-Based Reporting: Every anomaly includes a confidence level (High/Medium/Low) based on signal strength. WHY: False positives erode trust. A "High" confidence stuck loop (5 identical commits) is qualitatively different from a "Low" confidence one (3 commits to the same file with different messages). Consumers filter on confidence.
No Remediation Execution: Recommended remediation is advisory text only. Forensics never executes fixes, even if the user asks. WHY: Remediation requires understanding intent, not just detecting anomalies. The wrong fix applied automatically can destroy work. Recommend, don't execute.

只读模式：绝不修改文件、创建提交或尝试修复。原因：修改状态的诊断工具会破坏其需要分析的证据。Forensics仅负责检查，不负责修复。平台层面通过限制工具仅能执行Read/Grep/Glob操作来强制实现这一点。
遵循CLAUDE.md：分析前先读取并遵循仓库中的CLAUDE.md。仓库约定定义了“正常”的标准（例如，预期的分支模式、必需的工件）。
凭据清理：在报告中包含任何文件内容或路径之前，扫描并编辑匹配密钥的模式（API密钥、令牌、密码、连接字符串）。原因：诊断报告可能会被共享或记录。通过取证报告泄露凭据比原始工作流故障的后果更严重。
路径编辑：编辑报告输出中的绝对主目录路径。将
```
/home/alice/
```
或
```
/Users/alice/
```
这类路径替换为
```
~/
```
。原因：跨团队共享的报告不应暴露文件系统布局或用户名。
基于置信度的报告：每个异常都会包含基于信号强度的置信度等级（高/中/低）。原因：误报会降低信任度。“高”置信度的停滞循环（5次相同提交）与“低”置信度的停滞循环（3次针对同一文件但提交信息不同）在性质上完全不同。用户会根据置信度筛选结果。
不执行修复：建议的修复方案仅为指导性文本。即使用户要求，Forensics也绝不会执行修复操作。原因：修复需要理解意图，而不仅仅是检测异常。自动应用错误的修复可能会破坏工作。仅提供建议，不执行操作。

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则开启）

Communication Style: Report findings factually with evidence. Show git hashes, timestamps, and file paths rather than making assertions. No self-congratulation.
Full Scan: Run all 5 anomaly detectors on every invocation. Skipping detectors creates blind spots -- a stuck loop that also drifted scope is a different situation than a stuck loop alone.
Severity-Ordered Output: Report anomalies ordered by confidence (High first). The reader needs the strongest signals first.
Evidence Inclusion: Include relevant git log excerpts, file snippets, and timestamps as evidence for each anomaly. Claims without evidence are not diagnostics.

沟通风格：基于证据如实报告发现结果。展示git哈希、时间戳和文件路径，而非做出断言。不自我夸耀。
全面扫描：每次调用时运行所有5个异常检测器。跳过检测器会产生盲点——同时存在停滞循环和范围偏离的情况与单纯的停滞循环完全不同。
按严重程度排序输出：按置信度（高优先级在前）排序报告异常。读者需要首先看到最强烈的信号。
包含证据：为每个异常包含相关的git日志片段、文件代码段和时间戳作为证据。没有证据的断言不是诊断结果。

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则关闭）

Cross-session comparison: Compare current branch against other recent branches for pattern similarity (OFF by default -- requires broader git history scan).
Timeline visualization: Produce ASCII timeline of commits with anomaly markers (OFF by default -- adds report length).

跨会话比较：将当前分支与其他近期分支进行模式相似性比较（默认关闭——需要更广泛的git历史扫描）。
时间线可视化：生成带有异常标记的ASCII提交时间线（默认关闭——会增加报告长度）。

What This Skill CAN Do

该Skill能做什么

Detect stuck fix/retry loops through git commit pattern analysis
Identify missing pipeline artifacts by checking expected phase outputs
Find abandoned work through timestamp gap analysis
Measure scope drift by comparing modified files against plan expectations
Detect crash/interruption through uncommitted changes and orphaned worktrees
Produce structured diagnostic reports with confidence levels
Scrub credentials and redact paths in report output

通过git提交模式分析检测停滞的修复/重试循环
通过检查预期阶段输出来识别缺失的流水线工件
通过时间戳间隔分析发现未完成的工作
通过比较修改文件与计划预期来衡量范围偏离
通过未提交的更改和孤立的工作区检测崩溃/中断
生成带有置信度等级的结构化诊断报告
在报告输出中清理凭据并编辑路径

What This Skill CANNOT Do

该Skill不能做什么

Fix any of the issues it finds (read-only -- recommend only)
Debug code-level bugs (use systematic-debugging)
Review code quality (use systematic-code-review)
Access external services or APIs (filesystem and git only)
Analyze workflows that left no git history or plan files (no evidence = no diagnosis)
Run shell commands (allowed-tools restricts to Read/Grep/Glob)

修复它发现的任何问题（只读模式——仅提供建议）
调试代码层面的bug（请使用systematic-debugging）
评审代码质量（请使用systematic-code-review）
访问外部服务或API（仅能访问文件系统和git）
分析未留下git历史或计划文件的工作流（没有证据就无法诊断）
运行shell命令（允许使用的工具仅限于Read/Grep/Glob）

Instructions

操作步骤

Phase 1: GATHER

阶段1：证据收集

Goal: Collect the raw evidence needed for anomaly detection. Determine what branch, plan, and time range to analyze.

Step 1: Identify the investigation target

Accept the target from one of these sources (in priority order):

Explicit branch: User specifies a branch name to investigate
Current branch: Use the current git branch if no branch specified
Explicit plan: User points to a specific
```
task_plan.md
```

Step 2: Locate the plan file

Search for the plan that governed the workflow:

Check
```
task_plan.md
```
in the repository root
Check
```
.feature/state/plan/
```
for feature plans
Check
```
plan/active/
```
for workflow-orchestrator plans

Record whether a plan exists. If no plan is found, note this -- it limits scope drift and abandoned work detection but does not block the investigation.

Step 3: Collect git history

Read the git log for the target branch. Extract:

Commit hashes, messages, timestamps, and files changed
The branch's divergence point from main/master

Use Grep to search git log output for patterns. Focus on:

Commits on this branch since divergence from the base branch
File change frequency across commits
Commit message patterns (similarity, repetition)

Step 4: Check working tree state

Examine the current state:

Are there uncommitted changes? (look for modified/untracked indicators)
Are there orphaned
```
.claude/worktrees/
```
directories?
Is there an active
```
task_plan.md
```
with incomplete phases?

GATE: Evidence collected. At minimum: git history available, branch identified. Proceed to DETECT only when evidence gathering is complete.

目标：收集异常检测所需的原始证据。确定要分析的分支、计划和时间范围。

步骤1：确定调查目标

从以下来源（按优先级排序）接受目标：

明确指定的分支：用户指定要调查的分支名称
当前分支：如果未指定分支，则使用当前git分支
明确指定的计划：用户指向特定的
```
task_plan.md
```

步骤2：定位计划文件

搜索管理工作流的计划：

检查仓库根目录下的
```
task_plan.md
```
检查
```
.feature/state/plan/
```
目录下的功能计划
检查
```
plan/active/
```
目录下的工作流编排器计划

记录是否存在计划文件。如果未找到计划文件，请注明这一点——这会限制范围偏离和未完成工作的检测，但不会阻止调查。

步骤3：收集git历史记录

读取目标分支的git日志。提取：

提交哈希、提交信息、时间戳和修改的文件
分支与main/master分支的分歧点

使用Grep搜索git日志输出中的模式。重点关注：

分支从基础分支分歧以来的提交
跨提交的文件更改频率
提交信息模式（相似性、重复性）

步骤4：检查工作区状态

检查当前状态：

是否存在未提交的更改？（查看已修改/未跟踪的标记）
是否存在孤立的
```
.claude/worktrees/
```
目录？
是否存在带有未完成阶段的活跃
```
task_plan.md
```
？

** gate（检查点）**：证据收集完成。至少需要：git历史可用、分支已确定。仅在证据收集完成后进入检测阶段。

Phase 2: DETECT

阶段2：异常检测

Goal: Run all 5 anomaly detectors against the collected evidence. Each detector produces zero or more findings with confidence levels.

目标：对收集到的证据运行所有5个异常检测器。每个检测器会生成零个或多个带有置信度等级的发现结果。

Detector 1: Stuck Loop

检测器1：停滞循环

Signal: Same file appearing in 3+ consecutive commits.

Analyze the git history for files that appear in consecutive commits:

List files changed in each commit (ordered chronologically)
Identify files that appear in 3 or more consecutive commits
For each candidate, analyze commit message similarity

Confidence scoring:

Pattern	Confidence	Rationale
Same file in 5+ consecutive commits, near-identical messages	High	Strong loop signal -- agent retrying the same fix
Same file in 4+ consecutive commits, varied messages	Medium	Possible loop, but varied messages suggest different approaches
Same file in 3 consecutive commits, different messages	Low	Could be legitimate iterative development
Same file in 3+ commits with messages containing "fix", "retry", "attempt"	High	Explicit retry language strengthens the signal regardless of count

False positive awareness: Legitimate multi-pass refactoring (e.g., "extract method", "add tests", "clean up") touches the same file repeatedly with genuinely different messages. Check whether the file's changes are cumulative (refactoring) or oscillating (loop). Oscillating changes -- where content reverts and re-applies -- are the strongest stuck loop signal.

信号：同一文件出现在3次或更多连续提交中。

分析git历史中连续提交中出现的文件：

列出每次提交中修改的文件（按时间顺序排列）
识别出现在3次或更多连续提交中的文件
针对每个候选文件，分析提交信息的相似性

置信度评分：

模式	置信度	理由
同一文件出现在5次或更多连续提交中，提交信息几乎相同	高	强烈的循环信号——Agent在重试相同的修复操作
同一文件出现在4次或更多连续提交中，提交信息不同	中	可能存在循环，但提交信息不同表明使用了不同的方法
同一文件出现在3次连续提交中，提交信息不同	低	可能是合理的迭代开发
同一文件出现在3次或更多提交中，提交信息包含“fix”“retry”“attempt”	高	明确的重试语言增强了信号强度，与提交次数无关

误报注意事项：合理的多轮重构（例如，“提取方法”“添加测试”“清理”）会反复修改同一文件，但提交信息确实不同。检查文件的更改是累积性的（重构）还是振荡性的（循环）。内容反复撤销和重新应用的振荡性更改是最强的停滞循环信号。

Detector 2: Missing Artifacts

检测器2：缺失工件

Signal: Pipeline phase ran but produced no expected output.

If a plan file exists, check each phase for expected artifacts:

Phase Type	Expected Artifacts
PLAN / UNDERSTAND	`task_plan.md` , design documents
IMPLEMENT / EXECUTE	New or modified source files matching plan scope
TEST / VERIFY	Test files, test results, verification output
REVIEW	Review comments, approval artifacts

For each phase marked complete (or partially complete) in the plan:

Check whether the expected artifacts exist
If missing, check git history for whether they were created then deleted

Confidence scoring:

Pattern	Confidence
Phase marked complete, zero artifacts found, no git evidence of creation	High
Phase marked complete, partial artifacts found	Medium
Phase marked in-progress, artifacts missing	Low (may still be generating)

If no plan file exists, skip this detector and note: "No plan file found -- missing artifact detection requires a plan to define expected outputs."

信号：流水线阶段已运行但未生成预期输出。

如果存在计划文件，检查每个阶段的预期工件：

阶段类型	预期工件
PLAN / UNDERSTAND	`task_plan.md` 、设计文档
IMPLEMENT / EXECUTE	符合计划范围的新增或修改的源文件
TEST / VERIFY	测试文件、测试结果、验证输出
REVIEW	评审意见、批准工件

针对计划中标记为已完成（或部分完成）的每个阶段：

检查预期工件是否存在
如果缺失，检查git历史记录以确定它们是否被创建后又删除

置信度评分：

模式	置信度
阶段标记为已完成，未找到任何工件，也没有git证据表明曾创建过	高
阶段标记为已完成，仅找到部分工件	中
阶段标记为进行中，工件缺失	低（可能仍在生成中）

如果未找到计划文件，则跳过此检测器并注明：“未找到计划文件——缺失工件检测需要计划来定义预期输出。”

Detector 3: Abandoned Work

检测器3：未完成工作

Signal: Active plan with incomplete phases and a significant timestamp gap.

Requirements: plan file must exist with timestamp-trackable phases.

Read the plan file for phase completion status
Extract the last commit timestamp on the branch
Calculate the gap between last commit and current time
Calculate the branch's average commit interval (total time span / number of commits)

Confidence scoring:

Pattern	Confidence
Plan shows "Currently in Phase X", last commit >24h ago, phases incomplete	High
Last commit gap exceeds 3x the branch's average commit interval	Medium
Plan has incomplete phases but last commit is recent (less than 1h ago)	Low (session may be active)

If no plan file exists, fall back to git-only analysis: a branch with incomplete work (no merge, no PR) and a large timestamp gap from last commit is a weaker abandoned work signal.

信号：活跃计划包含未完成阶段且存在明显的时间戳间隔。

要求：计划文件必须存在且包含可跟踪时间戳的阶段。

读取计划文件中的阶段完成状态
提取分支上的最后一次提交时间戳
计算最后一次提交与当前时间的间隔
计算分支的平均提交间隔（总时间跨度 / 提交次数）

置信度评分：

模式	置信度
计划显示“当前处于阶段X”，最后一次提交已超过24小时，阶段未完成	高
最后一次提交间隔超过分支平均提交间隔的3倍	中
计划包含未完成阶段，但最后一次提交是近期的（不到1小时前）	低（会话可能仍在进行中）

如果未找到计划文件，则退回到仅基于git的分析：包含未完成工作（未合并、未创建PR）且最后一次提交存在较长时间间隔的分支是较弱的未完成工作信号。

Detector 4: Scope Drift

检测器4：范围偏离

Signal: Files modified outside the plan's expected domain.

Requirements: plan file must exist with identifiable scope (file paths, package names, or domain descriptions).

Extract the plan's expected scope (file paths, directories, packages mentioned)
List all files actually modified on the branch (from git history)
Compare: which modified files fall outside the expected scope?

Drift severity:

Drift Type	Severity	Example
Adjacent package	Minor	Plan targets `pkg/auth/` , also modified `pkg/auth/testutil/`
Different domain	Moderate	Plan targets `pkg/auth/` , also modified `pkg/billing/`
Infrastructure/config not in plan	Major	Plan targets feature code, also modified `.github/workflows/` , `Makefile` , or config files
Unrelated files	Major	Plan targets Go code, also modified `docs/README.md` or JavaScript files

Confidence scoring:

Pattern	Confidence
Multiple major-severity drifts	High
Single major or multiple moderate drifts	Medium
Minor drifts only	Low

If no plan file exists, skip this detector and note: "No plan file found -- scope drift detection requires a plan to define expected scope."

信号：修改了计划预期范围之外的文件。

要求：计划文件必须存在且包含可识别的范围（文件路径、包名称或领域描述）。

提取计划的预期范围（提到的文件路径、目录、包）
列出分支上实际修改的所有文件（来自git历史记录）
比较：哪些修改的文件超出了预期范围？

偏离严重程度：

偏离类型	严重程度	示例
相邻包	轻微	计划目标为 `pkg/auth/` ，同时修改了 `pkg/auth/testutil/`
不同领域	中等	计划目标为 `pkg/auth/` ，同时修改了 `pkg/billing/`
计划中未包含的基础设施/配置	严重	计划目标为功能代码，同时修改了 `.github/workflows/` 、 `Makefile` 或配置文件
无关文件	严重	计划目标为Go代码，同时修改了 `docs/README.md` 或JavaScript文件

置信度评分：

模式	置信度
多次严重偏离	高
单次严重偏离或多次中等偏离	中
仅存在轻微偏离	低

如果未找到计划文件，则跳过此检测器并注明：“未找到计划文件——范围偏离检测需要计划来定义预期范围。”

Detector 5: Crash/Interruption

检测器5：崩溃/中断

Signal: Evidence of abnormal session termination.

Check for the combination of these indicators:

Indicator	How to Check
Uncommitted changes	Look for modified/untracked files in working tree
Active plan with incomplete phases	Read `task_plan.md` for "Currently in Phase" with unchecked items
Orphaned worktrees	Check `.claude/worktrees/` for directories that reference non-existent branches or stale sessions
Debug session file	Check for `.debug-session.md` with a "Next Action" that was never executed

Confidence scoring:

Indicators Present	Confidence
3+ indicators simultaneously	High
2 indicators	Medium
1 indicator alone	Low (may be normal state)

GATE: All 5 detectors have run. Each produced zero or more findings with confidence levels. Proceed to REPORT.

信号：会话异常终止的证据。

检查以下指标的组合：

指标	检查方式
未提交的更改	查看工作区中的已修改/未跟踪文件
包含未完成阶段的活跃计划	读取 `task_plan.md` 中的“当前处于阶段”以及未勾选的项
孤立的工作区	检查 `.claude/worktrees/` 目录中是否存在引用不存在分支或过期会话的目录
调试会话文件	检查是否存在包含“下一步操作”但从未执行的 `.debug-session.md`

置信度评分：

存在的指标数量	置信度
同时存在3个或更多指标	高
存在2个指标	中
仅存在1个指标	低（可能是正常状态）

gate（检查点）：所有5个检测器已运行。每个检测器生成了零个或多个带有置信度等级的发现结果。进入报告阶段。

Phase 3: REPORT

阶段3：生成报告

Goal: Compile findings into a structured diagnostic report with root cause hypothesis and remediation recommendations.

Step 1: Scrub sensitive content

Before assembling the report, scan all evidence strings for:

API keys, tokens, passwords (patterns:
```
sk-
```
,
```
ghp_
```
,
```
token=
```
,
```
password=
```
,
```
secret=
```
,
```
key=
```
, bearer tokens, base64-encoded credentials)
Absolute home directory paths

Replace sensitive values with

[REDACTED]

and home paths with

~/

Step 2: Compile anomaly table

Order findings by confidence (High first), then by detector number:

undefined

目标：将发现结果编译成包含根本原因假设和修复建议的结构化诊断报告。

步骤1：清理敏感内容

在组装报告之前，扫描所有证据字符串以查找：

API密钥、令牌、密码（模式：
```
sk-
```
、
```
ghp_
```
、
```
token=
```
、
```
password=
```
、
```
secret=
```
、
```
key=
```
、Bearer令牌、base64编码的凭据）
绝对主目录路径

将敏感值替换为

[REDACTED]

，将主目录路径替换为

~/

。

步骤2：编译异常表格

按置信度（高优先级在前）排序发现结果，然后按检测器编号排序：

undefined

Forensics Report: [branch name or session identifier]

取证报告：[分支名称或会话标识符]

Anomalies Detected

检测到的异常

#	Type	Confidence	Description
1	[type]	[High/Medium/Low]	[description with evidence]
2	[type]	[High/Medium/Low]	[description with evidence]


If no anomalies detected:

#	类型	置信度	描述
1	[类型]	[高/中/低]	[带有证据的描述]
2	[类型]	[高/中/低]	[带有证据的描述]


如果未检测到异常：

Anomalies Detected

检测到的异常

No anomalies detected. The workflow appears to have executed normally.


**Step 3: Synthesize root cause hypothesis**

Connect the anomalies into a coherent narrative. Look for causal chains:
- Stuck loop + scope drift = agent tried to fix a problem, drifted into unrelated files looking for the root cause
- Missing artifacts + abandoned work = session crashed before producing outputs
- Crash/interruption + stuck loop = agent exhausted retries and was terminated

The hypothesis should be specific and testable, not generic:
- BAD: "Something went wrong during execution"
- GOOD: "Agent entered a lint fix loop on server.go (4 consecutive commits with 'fix lint' messages), which consumed the session's context budget before Phase 3 VERIFY could execute, leaving test artifacts missing"

**Step 4: Recommend remediation**

Provide specific, actionable recommendations. Each recommendation should reference the anomaly it addresses:

| Anomaly Type | Typical Remediation |
|--------------|-------------------|
| Stuck loop | Identify the root cause of the loop (often a lint/type error the agent can't resolve). Fix manually, then resume from the last successful phase. |
| Missing artifacts | Re-run the phase that failed to produce artifacts. Check if the phase definition is clear enough for the executor. |
| Abandoned work | Resume from the last completed phase. Check `.debug-session.md` or plan status for where to pick up. |
| Scope drift | Review out-of-scope changes for necessity. Revert unrelated changes. Re-scope the plan if the drift was needed. |
| Crash/interruption | Check for uncommitted changes worth preserving. Clean up orphaned worktrees. Resume from last committed state. |

**Step 5: Format final report**

================================================================ FORENSICS REPORT: [branch/session identifier]

Scan completed: [timestamp] Branch: [branch name] Commits analyzed: [count] Plan file: [path or "not found"]

================================================================ ANOMALIES

#	Type	Confidence	Description
...	...	...	...

================================================================ ROOT CAUSE HYPOTHESIS

[Narrative connecting anomalies into causal explanation]

================================================================ RECOMMENDED REMEDIATION

[Specific action referencing anomaly #N]
[Specific action referencing anomaly #N]

================================================================ EVIDENCE

[Relevant git log excerpts, file snippets, timestamps] [All paths redacted, credentials scrubbed]

================================================================


**GATE**: Report is complete, scrubbed, and formatted. Deliver to user.

---

未检测到异常。工作流执行正常。


**步骤3：合成根本原因假设**

将异常关联成连贯的叙述。寻找因果链：
- 停滞循环 + 范围偏离 = Agent尝试修复问题，偏离到无关文件中寻找根本原因
- 缺失工件 + 未完成工作 = 会话在生成输出之前崩溃
- 崩溃/中断 + 停滞循环 = Agent耗尽重试次数后被终止

假设应具体且可测试，而非泛泛而谈：
- 错误示例：“执行过程中出现了问题”
- 正确示例：“Agent在server.go文件上进入了lint修复循环（4次连续提交，提交信息包含'修复lint'），这消耗了会话的上下文预算，导致第3阶段VERIFY无法执行，从而使测试工件缺失”

**步骤4：建议修复方案**

提供具体、可操作的建议。每个建议都应引用它所针对的异常：

| 异常类型 | 典型修复方案 |
|--------------|-------------------|
| 停滞循环 | 确定循环的根本原因（通常是Agent无法解决的lint/类型错误）。手动修复，然后从最后一个成功的阶段恢复。 |
| 缺失工件 | 重新运行未能生成工件的阶段。检查阶段定义是否足够清晰，以便执行者理解。 |
| 未完成工作 | 从最后一个完成的阶段恢复。查看`.debug-session.md`或计划状态以确定从何处继续。 |
| 范围偏离 | 评审超出范围的更改是否必要。撤销无关更改。如果偏离是必要的，则重新定义计划范围。 |
| 崩溃/中断 | 检查是否有值得保留的未提交更改。清理孤立的工作区。从最后一次提交的状态恢复。 |

**步骤5：格式化最终报告**

================================================================ 取证报告：[分支/会话标识符]

扫描完成时间：[时间戳] 分支：[分支名称] 分析的提交数量：[数量] 计划文件：[路径或“未找到”]

================================================================ 异常

#	类型	置信度	描述
...	...	...	...

================================================================ 根本原因假设

[将异常关联成因果解释的叙述]

================================================================ 建议的修复方案

[引用异常#N的具体操作]
[引用异常#N的具体操作]

================================================================ 证据

[相关的git日志片段、文件代码段、时间戳] [所有路径已编辑，凭据已清理]

================================================================


**gate（检查点）**：报告已完成、清理并格式化。交付给用户。

---

Error Handling

错误处理

Error	Cause	Solution
No git history on branch	Branch has zero commits or just forked	Report "insufficient evidence" -- forensics needs commit history to analyze
No plan file found	Workflow ran without a plan	Note limitation in report. Detectors 2 (missing artifacts), 3 (abandoned work), and 4 (scope drift) operate in degraded mode or skip. Detectors 1 (stuck loop) and 5 (crash) still function.
Worktree access fails	Orphaned worktree with broken symlinks	Report the orphaned worktree as crash/interruption evidence. Do not attempt cleanup.
Git log too large	Long-lived branch with hundreds of commits	Focus analysis on the most recent 50 commits. Note truncation in report.
Ambiguous branch target	User request doesn't clearly identify which branch	Ask: "Which branch should I investigate? Current branch is [X]."

错误	原因	解决方案
分支上没有git历史记录	分支没有提交或刚创建	报告“证据不足”——取证分析需要提交历史才能进行分析
未找到计划文件	工作流未按计划运行	在报告中注明限制。检测器2（缺失工件）、3（未完成工作）和4（范围偏离）将以降级模式运行或跳过。检测器1（停滞循环）和5（崩溃）仍可正常运行。
无法访问工作区	孤立的工作区存在损坏的符号链接	将孤立的工作区作为崩溃/中断的证据报告。不要尝试清理。
git日志过大	长期存在的分支包含数百次提交	重点分析最近的50次提交。在报告中注明截断。
分支目标不明确	用户请求未明确指定要调查的分支	询问：“我应该调查哪个分支？当前分支是[X]。”

Anti-Patterns

反模式

Anti-Pattern	Why Wrong	Do Instead
Attempting to fix detected issues	Forensics that modifies state destroys evidence and violates read-only constraint. A fix applied without understanding intent can make things worse.	Report findings and recommend remediation. Let the user decide what to fix.
Reporting anomalies without evidence	"There might be a stuck loop" without commit hashes or file names is not a diagnostic. Unsubstantiated claims waste the reader's time.	Include specific git hashes, file paths, timestamps, and commit messages for every anomaly.
Treating all anomalies as equal severity	A High confidence stuck loop and a Low confidence scope drift require different urgency. Flat reporting obscures priority.	Order by confidence. Lead with the strongest signals.
Running only some detectors	"The user asked about stuck loops so I'll skip the other detectors." Anomalies are often correlated -- a stuck loop causes missing artifacts causes abandoned work. Partial analysis misses the causal chain.	Run all 5 detectors. The user asked about one symptom, but the diagnosis may involve several.
Including raw credentials in report	Diagnostic reports may be shared, logged, or pasted into issues. A credential in a forensics report is a security incident.	Scrub before reporting. Always.
Guessing at root cause without evidence	"The agent probably ran out of context" without timestamp or commit evidence is speculation, not diagnosis.	Every claim in the root cause hypothesis must trace to a specific anomaly finding with evidence.

反模式	错误原因	正确做法
尝试修复检测到的问题	修改状态的取证分析会破坏证据并违反只读约束。在不理解意图的情况下应用修复可能会使问题恶化。	报告发现结果并建议修复方案。让用户决定要修复的内容。
报告异常但不提供证据	“可能存在停滞循环”但不提供提交哈希或文件名不是诊断结果。无根据的断言会浪费读者的时间。	为每个异常包含具体的git哈希、文件路径、时间戳和提交信息。
将所有异常视为同等严重	高置信度的停滞循环和低置信度的范围偏离需要不同的处理优先级。平铺直叙的报告会掩盖优先级。	按置信度排序。首先展示最强烈的信号。
仅运行部分检测器	“用户询问了停滞循环，所以我会跳过其他检测器。”异常通常是相关的——停滞循环会导致缺失工件，进而导致未完成工作。部分分析会遗漏因果链。	运行所有5个检测器。用户询问的是一个症状，但诊断可能涉及多个问题。
在报告中包含原始凭据	诊断报告可能会被共享、记录或粘贴到问题中。取证报告中的凭据是安全事件。	报告前清理凭据。始终如此。
在没有证据的情况下猜测根本原因	“Agent可能耗尽了上下文”但没有时间戳或提交证据是猜测，不是诊断。	根本原因假设中的每个断言都必须追溯到带有证据的特定异常发现结果。

Anti-Rationalization

反合理化

Rationalization Attempt	Why It's Wrong	Required Action
"I can see the problem, let me just fix it"	Forensics is read-only. Fixing destroys evidence. Even if the fix is obvious, the user needs the diagnostic to understand what happened.	Complete the report. Recommend the fix. Do not execute it.
"No plan file, so forensics can't help"	3 of 5 detectors work without a plan (stuck loop, crash/interruption, and degraded abandoned work). Missing the plan limits analysis, it doesn't prevent it.	Run all detectors. Note limitations for plan-dependent detectors. Report what you can.
"This is just normal iterative development, not a loop"	That's what confidence levels are for. Report it as Low confidence if the evidence is ambiguous. Don't suppress findings based on your interpretation of intent.	Report the finding with appropriate confidence. Let the consumer decide.
"The report is long enough, I'll skip the evidence section"	A forensics report without evidence is an opinion piece. Evidence is what makes it a diagnostic.	Include evidence. Every anomaly must have supporting data in the evidence section.
"Credentials in this file aren't real secrets"	You cannot determine whether a credential is real from its format. Treat all credential-shaped strings as real.	Scrub all credential patterns. No exceptions.
"Path redaction isn't needed for internal reports"	You don't control where the report ends up. Internal today, shared tomorrow.	Redact paths in every report. It costs nothing and prevents future exposure.

合理化尝试	错误原因	必需操作
“我能看到问题，让我直接修复它”	取证分析是只读的。修复会破坏证据。即使修复方案很明显，用户也需要诊断来了解发生了什么。	完成报告。建议修复方案。不要执行修复。
“没有计划文件，所以取证分析无法提供帮助”	5个检测器中有3个无需计划即可运行（停滞循环、崩溃/中断，以及降级模式的未完成工作）。缺少计划会限制分析，但不会阻止分析。	运行所有检测器。注明依赖计划的检测器的限制。报告你能发现的内容。
“这只是正常的迭代开发，不是循环”	这就是置信度等级的用途。如果证据不明确，则将其报告为低置信度。不要根据你对意图的解释压制发现结果。	以适当的置信度报告发现结果。让用户决定。
“报告已经够长了，我会跳过证据部分”	没有证据的取证报告只是观点。证据是使其成为诊断的关键。	包含证据。每个异常在证据部分都必须有支持数据。
“此文件中的凭据不是真正的密钥”	你无法从格式判断凭据是否真实。将所有类似凭据的字符串视为真实凭据。	清理所有凭据模式。无一例外。
“内部报告不需要编辑路径”	你无法控制报告的最终去向。今天是内部报告，明天可能会被共享。	在每份报告中编辑路径。这没有成本，还能防止未来的信息泄露。

References

参考资料

ADR-073: Forensics Meta-Workflow Diagnostics
Systematic Debugging -- for code-level bugs (not workflow-level)
Workflow Orchestrator -- produces the plans forensics analyzes
Plan Checker -- validates plans pre-execution (forensics analyzes post-execution)
Error Learner Hook -- handles tool-level errors (forensics handles workflow-level patterns)
Gate Enforcement
Anti-Rationalization

ADR-073: Forensics Meta-Workflow Diagnostics
Systematic Debugging —— 用于代码层面的bug（而非工作流层面）
Workflow Orchestrator —— 生成取证分析要分析的计划
Plan Checker —— 在执行前验证计划（取证分析在执行后分析）
Error Learner Hook —— 处理工具层面的错误（取证分析处理工作流层面的模式）
Gate Enforcement
Anti-Rationalization