generate-handoff-document

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generating Handoff Documents

生成交接文档

Create a resumable handoff package for an in-progress analytical session. This orchestrator does three things: think (identify missing inputs and failed gates), decide (choose the next specialist or targeted rerun), and dispatch (send extraction, validation, and assembly work to co-located subagents). The working data lives on disk as structured artifacts; the orchestrator keeps only verdicts, paths, counts, and unresolved questions in context.

为进行中的分析会话创建可恢复的交接包。这个编排器会完成三项工作：思考（识别缺失的输入和未通过的校验关口）、决策（选择下一步要调用的专家Agent或定向重跑任务）、调度（将提取、验证和组装工作发送给同署的子Agent）。工作数据以结构化产物的形式存储在磁盘上；编排器仅在上下文中保留结论、路径、计数和未解决的问题。

Inputs

输入

Input	Required	Example
`TARGET_FILE`	Yes	`docs/auth-review-handoff.md`
`SUBJECT`	No	`Authentication review`
`TRACKING_FILES`	No	`docs/auth-review-notes.md,docs/plan.md`
`CONTEXT_SOURCE`	No	`current conversation` or `docs/transcript.md`

If the user omits optional values, infer them from the session when that is safe. Read

./references/data-contracts.md

when deriving sibling artifact paths or checking the structured artifact schemas.

输入	是否必填	示例
`TARGET_FILE`	是	`docs/auth-review-handoff.md`
`SUBJECT`	否	`Authentication review`
`TRACKING_FILES`	否	`docs/auth-review-notes.md,docs/plan.md`
`CONTEXT_SOURCE`	否	`current conversation` 或 `docs/transcript.md`

如果用户省略了可选值，安全的前提下可从当前会话推断。推导关联产物路径或检查结构化产物 schema 时，请读取

./references/data-contracts.md

。

Workflow Overview

工作流概述

```
context-extractor
```
writes the instruction/Q&A artifact.
```
insight-documenter
```
writes the insights artifact.
```
claim-validator
```
optionally writes the claims artifact when tracking files exist.
```
document-assembler
```
reads those artifacts and writes the final handoff document.
The orchestrator validates the final document and reruns only the failing stage(s).

```
context-extractor
```
编写指令/问答产物。
```
insight-documenter
```
编写洞察产物。
存在跟踪文件时，
```
claim-validator
```
可选择编写声明产物。
```
document-assembler
```
读取这些产物并生成最终的交接文档。
编排器验证最终文档，仅重跑失败的阶段。

Subagent Registry

子Agent注册表

Read a subagent definition only when you are about to dispatch it.

Subagent	Path	Purpose
`context-extractor`	`./subagents/context-extractor.md`	Capture the original mandate, instruction amendments, and chronological Q&A history
`insight-documenter`	`./subagents/insight-documenter.md`	Extract evidence-backed findings, risks, and recommendations from the session
`claim-validator`	`./subagents/claim-validator.md`	Verify factual claims from external tracking files against primary sources when available
`document-assembler`	`./subagents/document-assembler.md`	Assemble the final handoff document from the structured artifacts

仅在即将调度子Agent时读取其定义。

子Agent	路径	用途
`context-extractor`	`./subagents/context-extractor.md`	捕获原始任务要求、指令修订内容，以及按时间排序的问答历史
`insight-documenter`	`./subagents/insight-documenter.md`	从会话中提取有证据支撑的发现、风险和建议
`claim-validator`	`./subagents/claim-validator.md`	存在原始来源时，对照其验证外部跟踪文件中的事实声明
`document-assembler`	`./subagents/document-assembler.md`	基于结构化产物组装最终的交接文档

How This Skill Works

技能工作原理

Read
```
./references/data-contracts.md
```
when you need the sibling artifact naming rules, JSON schemas, or final-section requirements.
Pass only explicit handoffs between stages: source path, target artifact path, subject, and optional tracking files.
Keep only verdicts, file paths, counts, and actionable warnings from each subagent. The detailed payload stays in the artifact files.
Treat claims from tracking files as provisional even after validation. The final handoff must preserve that caution for the next agent.
Use targeted fix cycles. If source extraction is incomplete, rerun the relevant upstream subagent and the downstream stages that consume it. If the problem is only document coherence or formatting, rerun
```
document-assembler
```
only.
Stop and surface the blocker if dispatch is unavailable or if three fix cycles fail to produce a coherent handoff.

需要关联产物命名规则、JSON schema 或最终章节要求时，请读取
```
./references/data-contracts.md
```
。
阶段之间仅传递明确的交接信息：源路径、目标产物路径、主题，以及可选的跟踪文件。
仅保留每个子Agent返回的结论、文件路径、计数和可操作警告，详细 payload 保留在产物文件中。
即使经过验证，跟踪文件中的声明也视为临时性的，最终交接文档必须为后续Agent保留该提醒。
使用定向修复流程：如果源提取不完整，重跑相关的上游子Agent以及依赖其输出的下游阶段。如果仅存在文档连贯性或格式问题，仅重跑
```
document-assembler
```
即可。
如果无法调度子Agent，或是三次修复循环仍无法生成连贯的交接文档，则停止任务并上报阻塞问题。

Output Contract

输出契约

All files written by this skill are resumability artifacts. They preserve workflow state for later continuation; they are not product-code changes.

Artifact	Produced by	Purpose
`TARGET_FILE`	`document-assembler`	Final cold-start handoff document
`<stem>.context.json`	`context-extractor`	Original instructions, amendments, and Q&A log
`<stem>.insights.json`	`insight-documenter`	Findings with evidence, category, priority, and verification state
`<stem>.claims.json`	`claim-validator`	Optional claim-validation checklist and summary

On success,

TARGET_FILE

contains five sections:

```
Original Instructions & Scope
```
```
Q&A Log
```
```
Observations & Insights
```

Unverified Claims & Validation Checklist

```
Open Questions & Recommended Next Steps
```

If no tracking files were provided, Section 4 must explicitly say so and tell the next agent to verify any factual claims independently.

本技能生成的所有文件都是可恢复性产物，用于保存工作流状态以便后续继续执行，不属于产品代码变更。

产物	生成方	用途
`TARGET_FILE`	`document-assembler`	最终的冷启动可用交接文档
`<stem>.context.json`	`context-extractor`	原始指令、修订内容和问答日志
`<stem>.insights.json`	`insight-documenter`	带证据、分类、优先级和验证状态的发现内容
`<stem>.claims.json`	`claim-validator`	可选的声明验证检查清单和摘要

成功生成时，

TARGET_FILE

包含五个章节：

```
原始指令与范围
```
```
问答日志
```
```
观察结果与洞察
```
```
未验证声明与验证检查清单
```
```
待解决问题与推荐后续步骤
```

如果未提供跟踪文件，第4章必须明确说明该情况，并告知后续Agent需独立验证所有事实声明。

Phase Guide

阶段指南

Situation	Reference file	Purpose
Contract or artifact-path questions	`./references/data-contracts.md`	Derive sibling artifact names and confirm the schemas/required sections

场景	参考文件	用途
契约或产物路径相关问题	`./references/data-contracts.md`	推导关联产物名称，确认schema/必填章节要求

Execution Steps

执行步骤

Confirm
```
TARGET_FILE
```
and derive the sibling artifact paths described in
```
./references/data-contracts.md
```
.

Dispatch

context-extractor

with

CONTEXT_SOURCE

and

CONTEXT_FILE

Dispatch

insight-documenter

with

CONTEXT_SOURCE

and

INSIGHTS_FILE

If
```
TRACKING_FILES
```
exist, dispatch
```
claim-validator
```
with
```
TRACKING_FILES
```
,
```
INSIGHTS_FILE
```
, and
```
CLAIMS_FILE
```
. Otherwise record the claims step as skipped.

Dispatch

document-assembler

with

TARGET_FILE

SUBJECT

CONTEXT_FILE

INSIGHTS_FILE

, and optional

CLAIMS_FILE

Validate the written handoff against this checklist:
- every required section exists
- each insight has rationale plus evidence
- the claims section includes either the validation directive or the explicit "no tracking files" note
- open questions are listed or explicitly marked resolved
- a fresh agent could continue without consulting prior chat history
If a check fails, rerun only the failing stage(s); cap the fix loop at three passes.
Return the final handoff path plus a concise summary of counts, warnings, and open questions.

确认
```
TARGET_FILE
```
，并按照
```
./references/data-contracts.md
```
中的说明推导关联产物路径。

传入

CONTEXT_SOURCE

和

CONTEXT_FILE

调度

context-extractor

。

传入

CONTEXT_SOURCE

和

INSIGHTS_FILE

调度

insight-documenter

。

如果存在
```
TRACKING_FILES
```
，传入
```
TRACKING_FILES
```
、
```
INSIGHTS_FILE
```
和
```
CLAIMS_FILE
```
调度
```
claim-validator
```
，否则记录声明验证步骤已跳过。

传入

TARGET_FILE

、

SUBJECT

、

CONTEXT_FILE

、

INSIGHTS_FILE

以及可选的

CLAIMS_FILE

调度

document-assembler

。

对照以下检查清单验证生成的交接文档：
- 所有必填章节都存在
- 每个洞察都有逻辑依据和证据支撑
- 声明章节要么包含验证说明，要么明确标注「无跟踪文件」
- 待解决问题已列出，或明确标记为全部解决
- 新的Agent无需查阅之前的聊天历史即可继续工作
如果某项检查未通过，仅重跑失败的阶段；修复循环最多执行三次。
返回最终交接文件路径，以及计数、警告和待解决问题的简要摘要。

Example

示例

<example> Input: - `TARGET_FILE=docs/auth-review-handoff.md` - `SUBJECT=Authentication review` - `TRACKING_FILES=docs/auth-review-notes.md`

Derived working artifacts:

```
docs/auth-review-handoff.context.json
```
```
docs/auth-review-handoff.insights.json
```
```
docs/auth-review-handoff.claims.json
```

Dispatch
```
context-extractor
```

Subagent returns:

CONTEXT: PASS

File: docs/auth-review-handoff.context.json

Q&A exchanges: 4

Dispatch
```
insight-documenter
```

Subagent returns:

INSIGHTS: PASS

File: docs/auth-review-handoff.insights.json

Insights: 6

Dispatch
```
claim-validator
```

Subagent returns:

CLAIMS: WARN

File: docs/auth-review-handoff.claims.json

Claims checked: 9

Unverified: 2

Dispatch
```
document-assembler
```

Subagent returns:

HANDOFF: PASS

File: docs/auth-review-handoff.md

Open questions: 2

Report: "Handoff document written to
```
docs/auth-review-handoff.md
```
. The session is resumable from disk; two open questions remain."

The orchestrator keeps only those summaries and file paths. </example>

<example> 输入： - `TARGET_FILE=docs/auth-review-handoff.md` - `SUBJECT=Authentication review` - `TRACKING_FILES=docs/auth-review-notes.md`

推导得到的工作产物：

```
docs/auth-review-handoff.context.json
```
```
docs/auth-review-handoff.insights.json
```
```
docs/auth-review-handoff.claims.json
```

调度
```
context-extractor
```

子Agent返回：

CONTEXT: PASS

File: docs/auth-review-handoff.context.json

Q&A exchanges: 4

调度
```
insight-documenter
```

子Agent返回：

INSIGHTS: PASS

File: docs/auth-review-handoff.insights.json

Insights: 6

调度
```
claim-validator
```

子Agent返回：

CLAIMS: WARN

File: docs/auth-review-handoff.claims.json

Claims checked: 9

Unverified: 2

调度
```
document-assembler
```

子Agent返回：

HANDOFF: PASS

File: docs/auth-review-handoff.md

Open questions: 2

报告： "交接文档已写入
```
docs/auth-review-handoff.md
```
。会话可从磁盘恢复，剩余2个待解决问题。"

编排器仅保留这些摘要信息和文件路径。 </example>