wenjunduan /polish — Athena Polish Stage Skill (v9.6.2)
何时触发
- 路径 ∈ {Refactor, System}
- 当前 stage = polish (review_pass1 后, ship 前)
- review_pass1 VERDICT ∈ {PASS, CONCERNS} (FAIL/REWORK 必须先修复)
其他路径 (Hotfix / Bugfix / Quick / Feature) 跳过 polish, 直接 review → ship.
启动检查
主 agent 进入 polish stage 时执行:
# 1. 验证前置条件
test -f .ai_state/details/reviews/sprint-${SPRINT}.md || { echo "无 review_pass1 结果, 不能 polish"; exit 1; }
# 2. 验证 path 适用
PATH_TYPE=$(rg -o 'path: "[A-Za-z]+"' .ai_state/_index.md | head -1)
case "$PATH_TYPE" in
*Refactor*|*System*) ;;
*) echo "$PATH_TYPE 不需要 polish, 直接进 ship"; exit 0 ;;
esac
# 3. 加载规则
cat ~/.agents/standards/doc-style.md
cat ~/.agents/standards/coding-standards.md
5 个检查项 (按顺序, 不允许跳)
1. 临时测试代码
# 扫描
rg -n "console\\.log|print\\(" src/ # 源文件 console.log
rg -n "// TODO|// FIXME|// XXX" src/ # 无 issue 号的标记
rg -n "test123|foo|bar" src/ # 在生产代码出现 hardcoded test
每个 finding → executed (立即修) 或 deferred (写入 cleanup-pass.md 「待办」段, 必须给 issue 链接).
2. 注释完善
- 公开 API (export) 缺 docstring → 补 (P0)
- 复杂函数 (≥ 30 行) 缺解释性注释 → 补 (P1)
- 注释掉的代码 → 删 (P2)
- TODO 无 issue 号 → 加 issue 或删 (P1)
3. 冗余检查
- 死代码:
rg <export-name>0 引用 → 删 - 重复实现: 同样逻辑两处 → 提取共享函数
- 配置 / 常量重复 → 合并
4. 低效检查
- N+1 查询 → SQL JOIN / batch fetch
- O(n²) where O(n log n) 可达 → 重写
- 同步阻塞 in async → 改 async
5. 过度设计 (YAGNI)
- 抽象层只 1 个实现 → 删抽象
- 未来才用的扩展点 → 删
- Generic 但只 1 个类型 → 删 generic
- Builder pattern with ≤ 3 params → 改普通函数
产出
写入 .ai_state/details/cleanup-pass-${SPRINT}.md:
模板见 ~/.agents/skills/pace/templates/details/cleanup-pass.md. 5 段对应 5 个检查项 + 合并 review 意见段.
合并 review 意见 (强制)
cleanup-pass.md 末尾必须有 "合并 review 意见" 段, 把 review_pass1 中 P2 级 (以及 polish 期间可顺手处理的 P1) finding 在 polish 阶段处理掉:
## 合并 review 意见 (来自 details/reviews/sprint-{N}.md)
- review finding F3 P1: 已在 polish 处理 (commit xxx)
- review finding F5 P2: 已在 polish 处理 (commit yyy)
- review finding IM-2 P1: deferred 到 docs sprint (写入 lessons.md)
VERDICT (polish 自己)
- PASS: 5 个检查项 executed 或 deferred (有明确 issue 引用), 改后测试 GREEN → stage 转 ship
- REWORK: polish 时发现新 P0 (例如清理时发现死代码其实被反射调用) → 回 review_pass1
CX 端实现路径
CX 端 polish stage 由主 agent执行 (不 spawn subagent).
工作流:
- 主 agent 读启动检查
- 主 agent 顺序执行 5 个检查项
- 主 agent 写 cleanup-pass.md
- 主 agent 把 stage 改成 ship
可选: 主 agent 可 spawn polish_worker (cx/.codex/agents/polish_worker.toml) 或 reviewer 做"polish 后的二次 review", 但不强制.
delivery-gate 强制
~/.codex/hooks/delivery-gate.py 会检查:
- path ∈ {Refactor, System}
- stage = ship
- → 必须存在
.ai_state/details/cleanup-pass-${SPRINT}.md, 否则 exit 2 + 提示运行 /polish
不要做
- 不引入新功能
- 不改 design.md 实现 (仅清理)
- 不删除合理的抽象 (Strategy 有 ≥ 2 个实现就保留)
- 不加新依赖
- 不修改测试逻辑 (除非清理临时 test value)
例外
- 项目自己声明跳过 polish (在 _index.md.skip_polish = true), 则仍写一份空 cleanup-pass.md 但所有段标 "(skipped: explicit opt-out)" → 仍可 ship