multi-shot-review

多轮审查

1. 根据用户的授权选择模式：

• Barrier（默认）：每次审查都从此模式开始。
• Report：仅当用户明确要求在目标保持不变的情况下进行仅报告审查时切换。

2. 使用实时 Git 目标和用户的原始请求全文初始化审查：

SKILL_DIR="/path/to/this-skill"
REVIEW_DIR="$(python3 "$SKILL_DIR/scripts/init_state.py" \
  --uncommitted \
  --task-file - <<'EOF'
<original user request>
EOF
)"

适当时使用 --base <branch> 或 --commit <sha>。状态只保存该目标描述符；分类器和审查者会直接检查 Git。确保 $REVIEW_DIR/task.md 包含完整的任务上下文后再结束。仅当用户明确要求配置变体时才添加 --variant <tag>。

3. 运行干净分类器：

python3 "$SKILL_DIR/scripts/classify_slices.py" \
  --review-dir "$REVIEW_DIR"

等待其完成（参见等待长时间运行）。仅在需要覆盖已配置的分类器配置时使用 --harness、--model 或 --reasoning。

如有需要，使用 --user-directives-file <path> 传入用户指示原文，并使用 --executor-context-file <path> 传入供参考的父级上下文。分类器会读取目标、任务、规则、代码、当前切片、墓碑、运行记录和历史记录。它会根据上下文调用 add_slice.py 和 remove_slice.py；不会生成分类计划文件。 切片选择行为定义于 references/slice-selection.md，分类器会加载该文件。 启动器会自动将全局审查指示和变更路径审查指示链解析为限定范围的上下文。分类器会编写每条完整的审查者提示词，并保留适用审查策略的措辞和范围。没有审查策略时，仅在上下文需要时按内容拆分广泛审查。审查者可以阅读辅助上下文，但只能报告分配给自己的变更。

如果退出代码为 2 且没有切片，请先阅读 $REVIEW_DIR/_logs/classifier-<id>.stdout.log，再重试；子进程会说明受阻原因。 如果分类器在创建切片后失败，请使用 --resume-incomplete 完成分类，然后再开始任何审查。此选项要求分类失败、此前没有成功的分类，且没有审查运行。它会保留部分切片集，并使用当前分类器完成分类。它不允许在审查之后重新分类。

每个会话只运行一次分类。会话中存在活动切片时，classify_slices.py 会失败。用户指示移除所有切片后，分类器可以再次运行。只能通过 明确的用户切片变更来修改切片集。其他情况下，应重新运行未完成的切片。

4. 运行一轮审查，然后等待其完成。取得该轮的最终 JSON 后即可完成：

python3 "$SKILL_DIR/scripts/run_reviews.py" --review-dir "$REVIEW_DIR" \
  --child-timeout-seconds 3600

所有符合条件的切片都会在同一轮中运行。最多同时运行 max_parallel 个子进程；其余子进程会在队列中等待。shots > 1 的切片会在该轮中对同一提示词运行指定数量的独立审查者轮次；如果某轮审查者报告了其他轮次已报告的问题，运行器会自动将其标记为重复。审查者会输出 references/review-result.schema.json 中规定的严格 JSON 结构；运行器会验证结果、分配会话范围内的 f_ ID，并用生成的 Markdown 替换原始结果。无效结果会导致可重试的切片失败。只使用 out 中的最终 JSON、问题 ID 和 Markdown 路径，以及 err 中的诊断信息。每条 out 记录会在 sh 中注明轮次，并包含 final。将每个问题视为假设，并根据代码和任务进行验证。

5. 完成所选模式：

Report

返回已验证并整合的问题，附上文件和行号引用。将切片失败计入审查覆盖缺失。将 ok 视为执行成功，将 rem 视为后续处理资格。无论 rem 的值如何，消费完该轮结果后即可完成 Report 模式。

如果用户要求后续处理，则再运行一轮。复用该会话运行符合条件的切片；如果所需覆盖范围有变化，则应用明确的用户切片变更。若要独立重复审查每个切片，或目标已变更，则初始化新会话。

隔离区

修复已验证的问题，并在能显著降低风险时添加有针对性的回归测试。按 ID 忽略一个已驳回的问题，并提供不可更改的理由：

python3 "$SKILL_DIR/scripts/ignore_finding.py" \
  --review-dir "$REVIEW_DIR" \
  --id "<finding-id>" \
  --reason "<why it is not actionable>"

如需提供更长的理由，请使用 --reason-file <path>。将重复问题标记为当前仍未关闭的另一个问题的重复项：

python3 "$SKILL_DIR/scripts/dedupe_finding.py" \
  --review-dir "$REVIEW_DIR" \
  --id "<duplicate-id>" \
  --canonical-id "<open-finding-id>"

修复后再运行一轮。当某个切片最新一轮中的所有问题都已忽略或去重时，该切片也算完成。

每个切片的运行次数上限为 max_passes（默认值为 3）。当切片在达到上限后仍有问题时，下一次调用 run_reviews.py 会先为该切片运行一个全新的裁定器，然后才开始新一轮。JSON 的 judge 数组会列出每项裁定及其理由：

• continue：该切片获得另一个 max_passes 周期。裁定器提示词会要求给出指出设计边界或修复质量问题的理由。运行器不会验证理由文本。请在下一轮开始前根据该理由采取行动。
• stop：该切片已完成。最后一轮的问题会在 out 中返回，并带有 "final":true。不要再为其运行新一轮；请修复或忽略每个 final 问题。

裁定器失败时，会返回一条 "st":"judge_failed" 的 err 记录，并保持切片不变；重新运行 run_reviews.py 即可重试。任何与裁定器规则相矛盾的裁定，无论朝哪个方向，也都视为裁定器失败。只有在所有非最终问题都已修复或记录为终结状态、所有 final 问题都已修复或忽略、相关检查均通过，且 JSON 返回 "ok":true 和 "rem":0 时，才算完成。

加入长时间运行的任务

classify_slices.py 和 run_reviews.py 可能运行一小时或更久。启动每个脚本后，都要等待其结束，并在继续下一步之前取得最终 JSON。选择测试框架提供的最高效等待方式：优先选择带退出通知的后台运行，最后再考虑超时最长的前台运行。

等待期间，请保持审查目标_不变_：审查者会读取实时 Git 状态。每个审查目录一次只运行一个脚本，并让它运行至退出。

如果等待一轮审查结束时连接中断（分离、超时、会话丢失），请使用：

python3 "$SKILL_DIR/scripts/await_reviews.py" --review-dir "$REVIEW_DIR"

用户明确要求的切片变更

只有用户的明确请求才授权由父级执行变更。使用 references/classifier-rules.md 中的审查者提示词契约提供完整提示词，并保留该请求：

python3 "$SKILL_DIR/scripts/add_slice.py" \
  --review-dir "$REVIEW_DIR" \
  --name "<slice-name>" \
  --harness "<harness>" \
  --prompt-file "<prompt-file>" \
  --user-directive-file "<verbatim-user-request-file>"

--shots <n> 设置每轮并行审查者任务的数量。省略该选项则使用已配置的默认值。每个未返回保留问题的任务，都会使该切片后续轮次的任务数减少一个，最低减至一个。--shot-passes <n|always> 设置从切片定义开始计数，有多少轮使用多个任务；后续轮次使用一个任务。省略该选项则使用已配置的默认值 1。

使用相同的授权标记移除切片：

python3 "$SKILL_DIR/scripts/remove_slice.py" \
  --review-dir "$REVIEW_DIR" \
  --name "<slice-name>" \
  --user-directive-file "<verbatim-user-request-file>"

移除操作会为该切片留下墓碑；重新添加其名称即可重新激活。定义可以更改，而运行记录、输出和历史记录会保留。重新激活的切片会获得新的 max_passes 周期。

脚本是状态、锁、输出名称、渲染、重试和完成情况的唯一管理者。不要编辑生成的审查 Markdown。