create-handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Handoff

生成交接文档

Generate a structured handoff document summarizing implementation work for the review pipeline.

为评审流程生成一份结构化的交接文档，总结开发工作内容。

Step 1: Determine the session name

步骤1：确定会话名称

Derive a session name from context:

If the user provided
```
$ARGUMENTS
```
, sanitize it to a safe kebab-case string (lowercase, strip any characters that aren't alphanumeric or hyphens, collapse multiple hyphens) and use that as the item name
Otherwise, infer from the current branch name (e.g.
```
feature/issue-24-authentication
```
→
```
issue-24-authentication
```
)
If on
```
main
```
/
```
master
```
, ask the user what to name the session

从上下文推导会话名称：

如果用户提供了
```
$ARGUMENTS
```
，将其清理为安全的kebab-case格式字符串（小写，去除非字母数字或连字符的字符，合并多个连字符）并将其用作项目名称

否则，从当前分支名称推断（例如

feature/issue-24-authentication

→

issue-24-authentication

）

如果在
```
main
```
/
```
master
```
分支上，询问用户会话名称

Step 2: Create the review session

步骤2：创建评审会话

Create the session directory and handoff file:

SESSION_DIR=".chalk/reviews/${session_name}"
HANDOFF_PATH="$SESSION_DIR/handoff.md"
mkdir -p "$SESSION_DIR"

If the handoff file already exists with content beyond the template, ask the user whether to overwrite or create a new timestamped session.

创建会话目录和交接文件：

SESSION_DIR=".chalk/reviews/${session_name}"
HANDOFF_PATH="$SESSION_DIR/handoff.md"
mkdir -p "$SESSION_DIR"

如果交接文件已存在且内容超出模板范围，询问用户是覆盖还是创建带时间戳的新会话。

Step 3: Determine the base branch

步骤3：确定基准分支

Figure out what the current branch was based on:

Check for a merge base with
```
main
```
:
```
git merge-base main HEAD
```
If that fails, try
```
origin/main
```
If that fails, try
```
master
```
/
```
origin/master
```

Store this as

{base}

for later steps.

确定当前分支基于哪个分支：

检查与
```
main
```
分支的合并基准：
```
git merge-base main HEAD
```
如果失败，尝试
```
origin/main
```
如果仍失败，尝试
```
master
```
/
```
origin/master
```

将结果保存为

{base}

，供后续步骤使用。

Step 4: Gather context

步骤4：收集上下文信息

Run these to understand the scope of changes:

git log --oneline {base}..HEAD
git diff --stat {base}..HEAD
git diff {base}..HEAD

运行以下命令了解变更范围：

git log --oneline {base}..HEAD
git diff --stat {base}..HEAD
git diff {base}..HEAD

Step 5: Detect and run project checks

步骤5：检测并运行项目检查

Auto-detect the project's build/check tooling and run what's available. Check for these in order:

Node.js — if

package.json

exists:

Detect package manager:
```
yarn.lock
```
→ yarn,
```
pnpm-lock.yaml
```
→ pnpm, else npm
Run build:
```
{pm} run build 2>&1 | tail -5
```

Run typecheck:

{pm} run typecheck 2>&1 | tail -5

npx tsc --noEmit 2>&1 | tail -5

Run lint:
```
{pm} run lint 2>&1 | tail -5
```
Run test:
```
{pm} run test 2>&1 | tail -5
```

Rust — if

Cargo.toml

exists:

```
cargo check 2>&1 | tail -5
```
```
cargo test --no-run 2>&1 | tail -5
```
```
cargo clippy 2>&1 | tail -5
```

Go — if

go.mod

exists:

```
go build ./... 2>&1 | tail -5
```
```
go vet ./... 2>&1 | tail -5
```
```
go test ./... -short 2>&1 | tail -5
```

Python — if

pyproject.toml

requirements.txt

exists:

```
python -m py_compile
```
on changed
```
.py
```
files
```
python -m pytest --co -q 2>&1 | tail -5
```
(collect only, don't run)

Make — if

Makefile

exists with

build

check

test

targets:

```
make build 2>&1 | tail -5
```
```
make check 2>&1 | tail -5
```
```
make test 2>&1 | tail -5
```

If no build system is detected, note "No build system detected — skipped automated checks".

Important: If any check fails, note the failure — do NOT try to fix it. The handoff should report the current state honestly.

自动检测项目的构建/检查工具，并运行可用的检查项，按以下顺序检测：

Node.js — 若存在

package.json

：

检测包管理器：存在
```
yarn.lock
```
则使用yarn，存在
```
pnpm-lock.yaml
```
则使用pnpm，否则使用npm
运行构建：
```
{pm} run build 2>&1 | tail -5
```

运行类型检查：

{pm} run typecheck 2>&1 | tail -5

或

npx tsc --noEmit 2>&1 | tail -5

运行代码检查：
```
{pm} run lint 2>&1 | tail -5
```
运行测试：
```
{pm} run test 2>&1 | tail -5
```

Rust — 若存在

Cargo.toml

：

```
cargo check 2>&1 | tail -5
```
```
cargo test --no-run 2>&1 | tail -5
```
```
cargo clippy 2>&1 | tail -5
```

Go — 若存在

go.mod

：

```
go build ./... 2>&1 | tail -5
```
```
go vet ./... 2>&1 | tail -5
```
```
go test ./... -short 2>&1 | tail -5
```

Python — 若存在

pyproject.toml

或

requirements.txt

：

对修改后的
```
.py
```
文件执行
```
python -m py_compile
```
```
python -m pytest --co -q 2>&1 | tail -5
```
（仅收集测试用例，不执行）

Make — 若存在包含

build

check

test

目标的

Makefile

：

```
make build 2>&1 | tail -5
```
```
make check 2>&1 | tail -5
```
```
make test 2>&1 | tail -5
```

若未检测到构建系统，记录“未检测到构建系统——跳过自动化检查”。

重要提示：若任何检查失败，需如实记录失败情况——请勿尝试修复问题。交接文档应真实反映当前状态。

Step 6: Write the handoff

步骤6：撰写交接文档

Write to

HANDOFF_PATH

. Use this format:

markdown

undefined

将内容写入

HANDOFF_PATH

，使用以下格式：

markdown

undefined

Handoff

交接文档

Scope

范围

Item: {item reference — e.g. "#24 — Add authentication" or "Refactor IPC layer"}
Goal: {1-sentence summary of what was accomplished}

项目：{项目参考 — 例如“#24 — 添加认证功能”或“重构IPC层”}
目标：{一句话总结完成的工作内容}

What Changed

变更内容

{bullet list of logical changes — describe WHAT each change does, not just file names}

{按逻辑分类的变更点列表——描述每个变更的作用，而非仅列出文件名}

Files Changed

修改的文件

{bullet list of every file modified/created, from git diff --stat}

{所有被修改/创建的文件列表，来自git diff --stat}

Risk Areas

风险区域

{bullet list of things that could break, have edge cases, or need careful review}

{可能出现问题、存在边缘情况或需要重点评审的内容列表}

Commands Run

执行的命令

{bullet list of every command run and its pass/fail status}

{所有执行的命令及其通过/失败状态列表}

Known Gaps

已知缺口

{bullet list of things NOT done — e.g. "no tests written", "error handling incomplete", "hardcoded values"}

{未完成的工作列表——例如“未编写测试用例”、“错误处理不完整”、“存在硬编码值”}

Suggested Focus For Reviewers

评审重点建议

{bullet list of what reviewers should look at most carefully — prioritize by risk}

undefined

{评审人员应重点关注的内容列表——按风险优先级排序}

undefined

Step 7: Report to the user

步骤7：向用户反馈

Show:

The handoff file path
A brief summary of what was captured
Suggest next step: run
```
/create-review
```
to generate a review prompt for any AI reviewer

展示以下信息：

交接文档的路径
已捕获内容的简要总结
下一步建议：运行
```
/create-review
```
为AI评审生成评审提示词

Rules

规则

Do NOT modify any source code — this skill is read-only except for the handoff file
Be honest about failures — if build/typecheck fail, report that clearly
Keep descriptions concrete and actionable — avoid vague statements like "various improvements"
List ALL files from
```
git diff --stat
```
, don't summarize or skip any
If there are no commits ahead of base, warn the user that there's nothing to hand off

请勿修改任何源代码——该工具仅可读写交接文档，其余操作均为只读
如实记录失败情况——若构建/类型检查失败，需清晰报告
描述需具体且可执行——避免“多项优化”这类模糊表述
列出
```
git diff --stat
```
中的所有文件，请勿省略或总结
若当前分支相对于基准分支无提交，需提醒用户没有可交接的内容