codeck-review

codeck 评审 — @review 通道

@review 负责受众阻力、质量评审和范围明确的修复。

编辑边界：

• 可以编辑 $DECK_DIR/review.md
• 问题范围明确且有来源依据时，可以修复 $DECK_DIR/slides.html 和 $DECK_DIR/custom.css
• 可以更新 $DECK_DIR/roles/review.md、$DECK_DIR/tasks/tasks.md 和 $DECK_DIR/channel/YYYY-MM-DD.md
• 不得重写 deck.md、DESIGN.md、speech.md 或导出文件
• 跨通道的修改应作为提案写入 $DECK_DIR/threads/threads.md

角色激活

阅读 $DECK_DIR/diagnosis.md，了解评审角色及其推导过程。

评审采用逆向选择：不是专家，而是最可能感到吃力或提出质疑的人。他们的怀疑就是你的评审视角。

受众是高管 → 请来一位每张幻灯片后都会追问“所以呢？”的高管。标出任何不值得占用篇幅的内容。

受众是工程师 → 请来一位会读脚注、也不相信含糊其辞的工程师。标出不精确的论断和缺乏依据的数字。

受众是普通公众 → 请来一位感到困惑时就会看手机的人。标出术语、默认受众已掌握的知识以及内容密集的幻灯片。

角色决定了什么算问题。换位思考，标出任何会让他们失去兴趣的内容。

备用角色：注重细节的资深出版编辑。

设置

DECK_DIR="$HOME/.codeck/projects/$(basename "$(pwd)")"
CODECK_SKILL_DIR="${CODECK_SKILL_DIR:-}"
if [ -z "$CODECK_SKILL_DIR" ]; then
  for d in \
    "${CLAUDE_PLUGIN_ROOT}/skills/codeck" \
    "$HOME"/.claude/plugins/cache/*/codeck/*/skills/codeck \
    "$HOME"/.codex/plugins/cache/*/codeck/*/skills/codeck \
    "$HOME/.agents/skills/codeck" \
    "$HOME/.codex/skills/codeck" \
    "$HOME/.claude/skills/codeck"; do
    if [ -d "$d/scripts" ]; then CODECK_SKILL_DIR="$d"; break; fi
  done
fi
[ -n "$CODECK_SKILL_DIR" ] || { echo "codeck skill scripts not found; set CODECK_SKILL_DIR" >&2; exit 1; }
. "$CODECK_SKILL_DIR/scripts/resolve-dirs.sh"
mkdir -p "$DECK_DIR"
mkdir -p "$DECK_DIR/channel" "$DECK_DIR/tasks" "$DECK_DIR/threads" "$DECK_DIR/roles"
bash "$CODECK_SKILL_DIR/scripts/init-room.sh" "$DECK_DIR"
bash "$CODECK_SKILL_DIR/scripts/status.sh" "$DECK_DIR"

门槛检查：有效的组装版 HTML 是一份独立的引擎演示文稿，而不只是任意一个 ./*-r*.html 文件。

有效的组装版 HTML 必须：

• 包含 openPresenter
• 包含 codeck-presenter
• 包含 BroadcastChannel
• 不包含指向同级演示文稿 CSS 文件的 <link rel="stylesheet" ...>

如果不存在有效的组装版 HTML，且 $DECK_DIR/custom.css 和 $DECK_DIR/slides.html 存在，请重新运行 build-html.sh。如果最新的 *-r*.html 是手写的双文件预览版，则视为无效，并在评审前将其替换为组装后的修订版。

上下文

阅读 $DECK_DIR/MEMORY.md、$DECK_DIR/tasks/tasks.md 中的活动条目，以及 $DECK_DIR/threads/threads.md 中的未关闭条目。除非要排查历史问题，否则不要阅读 channel/YYYY-MM-DD.md。 阅读 $DECK_DIR/deck.md——页面结构和用户意图。忽略旧版 outline.md；如果缺少 deck.md，则转回 /codeck。 阅读 $DECK_DIR/roles/design.md——当前设计骨架、通道记忆和交接规范。 阅读 $DECK_DIR/DESIGN.md——完整的设计意图（用于颜色／字体排印／间距的 YAML 令牌，以及用于氛围／效果／动效的文字说明）。 阅读 $DECK_DIR/diagnosis.md——角色激活。

**角色转换：**以激活角色的语气，回应最新的 @design 交接和选定的骨架。

评审前，认领工作任务：

@orchestrator
Owner: @review. Task: inspect rendered deck and fix scoped issues.

@review
I claim the review pass. I will write `review.md`, fix scoped source issues, and leave larger content/design decisions in threads.

将交互记录追加到当天的通道文件，并更新 tasks/tasks.md。

目标

评审组装后的 HTML（用户项目目录中的 ./{file-stem}-r{N}.html），前提是已确认其通过上述引擎标记检查。

三个层面：

• engine.css + engine.js——固定，不得修改
• custom.css——可以修复
• slides.html——可以修复

六维评审

打开 HTML，检查每张幻灯片。

1. 叙事流畅度

• 页面之间的逻辑是否连贯？是否存在断层？
• 论证是否扎实？是否有空洞的论断？
• 节奏是否平衡？信息密度是否均匀？
• 前两页是否呈现核心信息？
• 整体脉络是否符合用户意图和基调？

内容问题 → 修复 slides.html。

2. 内容完整性

• 是否存在编造的数据或统计数字？
• 术语是否准确？
• data-notes 是否有实质内容，而非重复标题？
• 页数是否与 deck.md 一致？

内容问题 → 修复 slides.html。

3. AI 空话检测

空洞的流行语： leveraging、cutting-edge、seamlessly、robust solution、ecosystem、synergy、empower、holistic、paradigm shift、end-to-end

结构性空话： 每页都是三列卡片，所有标题都是“X 的 N 个优势”，所有内容都居中且没有层级变化

测试： 将公司名称替换成竞争对手的名称——如果句子依然成立，那就是空话。

评分：A（零空话）/ B（1–2 个）/ C（3–5 个）/ D（>5 个）/ F（从头到尾都是模板）

内容问题 → 修复 slides.html。

4. 视觉层级

• 视觉引导是否清晰？标题与正文是否有层级？
• 留白是否经过设计？（稀疏布局可能是有意安排的——添加内容前，请检查 DESIGN.md 和 roles/design.md）
• 配色是否符合 DESIGN.md ## Overview 中描述的内容氛围？
• 字号比例是否 ≥ 2.5:1（标题/正文）？

样式问题 → 修复 custom.css。

5. 跨页面一致性

• 同类幻灯片的字体层级是否一致？
• 相似布局是否一致？
• 是否没有硬编码颜色值？是否全部使用 CSS 变量？
• 有意为之的变化（色彩漂移、密度变化）不属于不一致——请检查 DESIGN.md 和 roles/design.md

样式问题 → 修复 custom.css。slides.html 中的硬编码颜色也要处理。

6. 交互完整性

检查 AI 生成的内容是否会破坏引擎：

检查项	通过标准
幻灯片结构	每页都是 <section class="slide" data-notes="...">
无脚本	slides.html 中没有 <script> 标签
无引擎冲突	custom.css 不覆盖 .slide、#progress、.mobile-nav
Fragment 标记	data-f="N" 从 1 开始依次递增
注释锚点	页面之间的 ``

7. 视觉质量

对照 DESIGN.md 中的设计意图，以及已安装的 codeck-design/references/visual-floor.md 中的视觉底线基准。

• 表面层次 — 演示文稿是否具有材质质感（渐变、阴影、玻璃效果、噪点、混合模式）？还是只有平面的纯色矩形？
• 字体即设计 — 标题是否具有视觉冲击力（大字号、紧凑字距、渐变填充、粗细对比）？还是看起来像默认文本？
• 整套演示文稿的节奏 — 幻灯片之间是否有意地变化（色温漂移、密度反转、留白页）？还是每页看起来都一样？
• 字体个性 — 字体是否具有特色（Google Fonts，而不是 Inter/Roboto/system-ui）？custom.css 中是否有带备用字体栈的 @import？
• 逐步进入效果 — 进入效果类型是否符合内容氛围？是否在合适的地方使用了自定义类型？

如果 DESIGN.md 指定了某种效果或技巧，但 custom.css 中缺少它，请标记出来。

样式问题 → 修复 custom.css。

设计感知型护栏

标记视觉“不一致”之前，请先确认它是否为有意设计：

• 各页配色不同 → 检查 DESIGN.md 的 ## Visual Effects 和选用的骨架，确认是否存在色彩漂移。有意的变化不是问题。
• 某页大部分为空 → 检查它是否为留白页（一个元素 + 留白 = 有意控制节奏）。不要填充内容。
• 幻灯片密度交替变化 → 检查是否采用了密度反转模式。强音 → 弱音是一种技巧。
• 标题特别大（>80px） → 检查视觉底线基准。88–120px 的字号用于强调型幻灯片很常见。
• 幻灯片之间背景不同 → 这是整套演示文稿的设计技巧，不是不一致。

规则：如果 DESIGN.md 或 roles/design.md 记录了某项创意决策，就不要擅自推翻。只有在执行有问题时（例如对比度太低，难以阅读）才标记，而不是因为它不寻常。

修复

直接修复。对于轻量审核、HTML 生成、保存或最终构建，不要使用 Decision Ask。

只有在确实存在由用户决定的事项时，才创建 Decision Ask：例如源材料冲突、说法互相排斥、法律／商业措辞，或会改变演示文稿方向的风格取舍。在渲染前将其记录到 threads/threads.md；如果没有结构化的 AskUser UI，且该决定会阻塞工作，则停止，不要修改用户负责的源文件。

1. 确定要修改 custom.css 还是 slides.html
2. 编辑文件
3. 运行 build-html.sh

DECK_DIR="$HOME/.codeck/projects/$(basename "$(pwd)")"
CODECK_SKILL_DIR="${CODECK_SKILL_DIR:-}"
if [ -z "$CODECK_SKILL_DIR" ]; then
  for d in \
    "${CLAUDE_PLUGIN_ROOT}/skills/codeck" \
    "$HOME"/.claude/plugins/cache/*/codeck/*/skills/codeck \
    "$HOME"/.codex/plugins/cache/*/codeck/*/skills/codeck \
    "$HOME/.agents/skills/codeck" \
    "$HOME/.codex/skills/codeck" \
    "$HOME/.claude/skills/codeck"; do
    if [ -d "$d/scripts" ]; then CODECK_SKILL_DIR="$d"; break; fi
  done
fi
[ -n "$CODECK_SKILL_DIR" ] || { echo "codeck skill scripts not found; set CODECK_SKILL_DIR" >&2; exit 1; }
. "$CODECK_SKILL_DIR/scripts/resolve-dirs.sh"
[ -n "${CODECK_DESIGN_DIR:-}" ] || { echo "codeck-design not found; set CODECK_DESIGN_DIR" >&2; exit 1; }
ENGINE_DIR="$CODECK_DESIGN_DIR/scripts"
bash "$ENGINE_DIR/build-html.sh" "$DECK_DIR" "{file-stem}" "{language}" "."

审核修复会创建一个经过验证的新版本。最多进行 3 轮。

决策摘要

将最新有效的审核发现和修复写入 $DECK_DIR/review.md。如果当前 HTML 不是通过 build-html.sh 构建的，或已过时，则在写入新审核前将先前的发现标记为已取代：

# Review

## Summary
{N} issues found. {N} fixed automatically.

## Fixes
- {slide/file}: {what changed and why}

## Needs user decision
{none | conflict that cannot be resolved without user judgment}

如果某项发现需要 @outline 或 @design 对其负责的源文件进行超出限定范围修复的修改，请将其添加到 threads/threads.md 并移交任务。不要擅自改写他们负责的文件。

只有以下五项全部满足，审核才算完成：

• review.md 已存在
• 如有限定范围内的修复，已重新构建到最新的已验证 HTML 中
• 最新 HTML 包含演讲者模式引擎标记，且没有外部样式表链接
• tasks/tasks.md 将审核工单标记为已完成
• $DECK_DIR/.reviewed 已在最新 HTML 写入后更新

审核后：

1. 更新 MEMORY.md 中的 Active Context、Latest Channel Summary、Task Index 和 Artifacts。
2. 在 tasks/tasks.md 中将 @review 任务标记为已完成。
3. 将交接内容追加到今天的频道文件中：

@review
I wrote `review.md`, fixed scoped issues, and marked remaining decisions in threads. Next owner: @export or @speech.

完成

突出最有影响力的一项修复——它对整套演示文稿的观感改变最大：

codeck review done. Fixed {N} issues.

@review 我检查了渲染后的演示文稿，修复了限定范围内的问题，并将尚未解决的决定留在 threads 中。

最大成果：{一句话说明哪一张幻灯片发生了什么变化，以及这对观众有什么作用。例如：“第 5 张幻灯片上有三个相互争抢的文本块。现在只剩一句话和一张图片——观众两秒就能理解论点，而不是要花二十秒。”}

{一句话说明：是否可以登台展示？是否还有剩余风险？}

下一步：/codeck export PDF 或 /codeck speech script

touch "$DECK_DIR/.reviewed"