Back to Details

replay-handoff

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Replay Handoff

重做交接文档（Replay Handoff）

Purpose

目的

Create a redo handoff from the current branch. Do not finish the branch. Preserve the intended change, identify what should be done better, and prepare a fresh agent to rebuild cleanly from 
master
or 
main
.
基于当前分支创建重做交接文档。请勿完成该分支。保留预期变更，明确需要改进的地方，并准备让新的agent从
master
或
main
分支干净地重新构建。

Hard Rules

严格规则

  • Do not edit the repository except for creating the handoff document, unless the user explicitly asks.
  • Treat the current diff as evidence, not as the correct implementation.
  • Use a subagent to check current default-branch code for the changed areas.
  • Make the handoff concise, pragmatic, and easy to verify.
  • Tell the receiving agent to verify the handoff and align with the user before any code edits.
  • 除创建交接文档外，请勿修改仓库，除非用户明确要求。
  • 将当前差异视为证据，而非正确实现。
  • 使用subagent检查默认分支中变更区域的代码。
  • 交接文档需简洁、务实且易于验证。
  • 告知接收方agent在进行任何代码编辑前，需先验证交接内容并与用户对齐。

Workflow

工作流程

  1. Inspect the branch.
  2. Infer intent from the branch and diffs.
  3. Check default-branch reality with a subagent.
  4. Derive lessons for a cleaner redo.
  5. Write the redo handoff.
  6. Return the handoff path and a short summary.
  1. 检查分支。
  2. 从分支和差异中推断意图。
  3. 借助subagent检查默认分支的实际情况。
  4. 总结更干净重做的经验。
  5. 撰写重做交接文档。
  6. 返回交接文档路径和简短总结。

Inspect The Branch

检查分支

Start with:
bash
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline --decorate -n 10
git diff --name-only
Then read staged and unstaged diffs. Prioritize files with strong intent signals:
  • New, deleted, renamed, staged, or heavily edited files
  • TODOs, placeholders, schema changes, migrations, shared contracts, generated files
  • Tests, type definitions, API surfaces, UI state, or cross-service boundaries
Read enough surrounding code to understand local patterns, call sites, constraints, and nearby validation.
从以下命令开始：
bash
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline --decorate -n 10
git diff --name-only
然后查看暂存和未暂存的差异。优先关注带有强烈意图信号的文件：
  • 新增、删除、重命名、暂存或大量编辑的文件
  • TODO注释、占位符、schema变更、迁移脚本、共享契约、生成文件
  • 测试用例、类型定义、API接口、UI状态或跨服务边界
阅读足够的周边代码，以理解本地模式、调用站点、约束条件和附近的验证逻辑。

Infer Intent

推断意图

Ground the inferred goal in concrete evidence:
  • Branch name and recent commits
  • Changed files and public interfaces
  • Test names/assertions
  • TODOs and deleted/replaced behavior
  • Validation failures, if available
If intent is ambiguous, state the ambiguity in the handoff instead of forcing a single story.
基于具体证据推断目标：
  • 分支名称和最近的提交
  • 变更文件和公共接口
  • 测试名称/断言
  • TODO注释和删除/替换的行为
  • （若有）验证失败信息
如果意图不明确，在交接文档中说明歧义，而非强行设定单一结论。

Check Default Branch

检查默认分支

Use a subagent for the default-branch check while the main agent continues analyzing the current branch.
Subagent prompt shape:
text
In this repository, determine the default branch (`origin/main` or `origin/master`) and inspect the latest available default-branch version of these paths: <paths>. Report drift, newer abstractions, renamed APIs, or conflicts that matter for redoing the current branch cleanly. Do not edit files.
Prefer a fresh remote-tracking branch when available:
bash
git remote show origin
git fetch origin
git branch -r --list 'origin/main' 'origin/master'
git show origin/main:<path>
git show origin/master:<path>
If fetch is blocked, use the newest local 
origin/main
or 
origin/master
and mark freshness as unverified. The main agent should also identify the default branch independently and use the subagent result as a cross-check.
主agent继续分析当前分支的同时，使用subagent检查默认分支。
Subagent提示模板：
text
在此仓库中，确定默认分支（`origin/main`或`origin/master`）并检查以下路径的最新默认分支版本：<paths>。报告对干净重做当前分支有影响的差异、新增抽象、重命名API或冲突。请勿修改文件。
优先使用最新的远程跟踪分支（若可用）：
bash
git remote show origin
git fetch origin
git branch -r --list 'origin/main' 'origin/master'
git show origin/main:<path>
git show origin/master:<path>
若无法执行fetch操作，使用本地最新的
origin/main
或
origin/master
，并标记其新鲜度未验证。主agent也应独立确定默认分支，并将subagent的结果作为交叉验证。

Derive Lessons

总结经验

Extract only lessons that change the redo:
  • What to preserve from the current branch
  • What not to port
  • Which names, abstractions, or boundaries should change
  • Which default-branch APIs or patterns should be used
  • Which generated files, migrations, or contracts need care
  • Which validation is necessary
  • Whether the redo should be split across commits or PRs
Avoid generic advice. Tie each lesson to a file, command, behavior, or contract.
仅提取会影响重做的经验：
  • 当前分支中需要保留的内容
  • 无需迁移的内容
  • 需要更改的名称、抽象或边界
  • 应使用的默认分支API或模式
  • 需要注意的生成文件、迁移脚本或契约
  • 必要的验证步骤
  • 是否应将重做工作拆分到多个提交或PR中
避免通用建议。每条经验都需关联到具体文件、命令、行为或契约。

Create The Handoff

创建交接文档

Create and read the handoff file before writing:
bash
d=$(mktemp -d) && touch "$d/replay-handoff.md" && echo "$d/replay-handoff.md"
Use this structure:
md
undefined
在撰写前先创建并读取交接文档：
bash
d=$(mktemp -d) && touch "$d/replay-handoff.md" && echo "$d/replay-handoff.md"
使用以下结构：
md
undefined

Replay Handoff

Replay Handoff

Goal

Goal

Current Branch Evidence

Current Branch Evidence

Inferred Intent

Inferred Intent

What To Preserve

What To Preserve

What To Do Differently

What To Do Differently

Default Branch Reality Check

Default Branch Reality Check

Instructions For The Receiving Agent

Instructions For The Receiving Agent

Clean Redo Plan

Clean Redo Plan

Validation Plan

Validation Plan

Open Questions / Risks

Open Questions / Risks

Suggested Skills

Suggested Skills

undefined
undefined

Handoff Style

交接文档风格

  • Prefer short bullets over paragraphs.
  • Include only facts that change the redo plan, expose risk, or help verify intent.
  • Do not paste long diffs, logs, command output, or full test failures.
  • Cite files, branches, commits, commands, PRs, or URLs instead of copying large artifacts.
  • Avoid repeating the same fact across sections.
  • Keep evidence selective; this is not a full audit trail.
## Goal
should be one short statement of the desired change. It may name the current branch as the original source. Keep evidence, lessons, and implementation detail out.
md
undefined
  • 优先使用短项目符号，而非段落。
  • 仅包含会改变重做计划、暴露风险或有助于验证意图的事实。
  • 请勿粘贴长差异、日志、命令输出或完整的测试失败信息。
  • 引用文件、分支、提交、命令、PR或URL，而非复制大型内容。
  • 避免在不同章节重复相同事实。
  • 选择性保留证据；这并非完整的审计追踪。
## Goal
部分应为一句简短的期望变更陈述。可将当前分支作为原始来源提及。请勿包含证据、经验和实现细节。
md
undefined

Goal

Goal

Redo the assistant attachment commit flow cleanly from 
origin/master
, using 
ofigma/attachment-send-path
as the original source branch.
undefined
Redo the assistant attachment commit flow cleanly from 
origin/master
, using 
ofigma/attachment-send-path
as the original source branch.
undefined

Receiving Agent Instructions

接收方Agent说明

In 
## Instructions For The Receiving Agent
, require the next agent to:
  1. Start from a clean workspace on the verified default branch.
  2. Read the handoff, then independently inspect referenced files, branches, commits, diffs, and tests.
  3. Report drift, missing context, or incorrect assumptions before proposing changes.
  4. Align with the user on design and intent before implementation:
    • Summarize the current system and relevant interfaces.
    • Ask one lettered multiple-choice question at a time when input is needed.
    • Compare 2-3 clean approaches when direction is not obvious.
    • Use before/after diagrams for multi-component changes.
    • Use illustrative code snippets only; do not edit files yet.
  5. Present a concise design or redo spec with interface changes, trade-offs, implementation plan, and validation plan.
  6. Wait for explicit user approval before any file edits.
  7. Ask before adding new tests unless already approved.
在
## Instructions For The Receiving Agent
部分，要求下一个Agent：
  1. 从已验证的默认分支开始，使用干净的工作区。
  2. 阅读交接文档，然后独立检查引用的文件、分支、提交、差异和测试用例。
  3. 在提出变更前，报告差异、缺失的上下文或错误的假设。
  4. 在实现前与用户对齐设计和意图：
    • 总结当前系统和相关接口。
    • 需要输入时，一次提出一个带字母的选择题。
    • 方向不明确时，对比2-3种干净的实现方案。
    • 对于多组件变更，使用前后对比图。
    • 仅使用示例代码片段；请勿修改文件。
  5. 提交包含接口变更、权衡、实现计划和验证计划的简洁设计或重做规范。
  6. 在进行任何文件编辑前，等待用户明确批准。
  7. 除非已获批准，否则添加新测试前需先询问用户。

Clean Redo Plan

干净重做计划

Keep the plan minimal and ordered:
  1. Start from the verified default branch.
  2. Recreate the smallest coherent contract or behavior change.
  3. Port useful code selectively from the current branch.
  4. Prefer current default-branch abstractions over branch-local inventions.
  5. Regenerate generated files only after source changes are stable.
  6. Run targeted validation before widening scope.
  7. Split work when deploy order or review clarity requires it.
Call out what not to port when that is the main lesson.
保持计划简洁有序：
  1. 从已验证的默认分支开始。
  2. 重新创建最小的连贯契约或行为变更。
  3. 有选择性地从当前分支迁移有用代码。
  4. 优先使用当前默认分支的抽象，而非分支本地的自定义实现。
  5. 仅在源码变更稳定后重新生成生成文件。
  6. 在扩大范围前运行针对性验证。
  7. 若部署顺序或评审清晰度要求，拆分工作内容。
当主要经验是无需迁移某些内容时，明确指出这些内容。

Output

输出

Return:
  • Handoff file path
  • Current branch
  • Default branch checked
  • Whether default-branch freshness was verified
  • Short redo summary
返回：
  • 交接文档路径
  • 当前分支
  • 已检查的默认分支
  • 默认分支新鲜度是否已验证
  • 简短的重做总结