Anime Forge — AI 动画短片生产线

出生：EP01「醋醋喵诞生记」（2026-06-10~12，docs/videos/cucu-pr-flow/）。本 skill 的每条规则都对应一次真实翻车或一次实测验证，n=1 边界诚实标注——竖屏重制就是第一次 dogfood，踩到新坑回来补 Common Mistakes。

为什么是 skill（价值门禁）

不教"什么是 i2v"。只沉淀：实测分工路由（中文乱码）、prompt 配方（四次翻车打磨）、工程纪律（防 operational cost 跑偏重演）、六个真金白银的坑。

第一性架构：确定性分层

视频模型不能同时当导演、UI 设计、演员和剪辑师。 把确定性按层分配：

推论：状态卡/信息卡镜头根本不需要 i2v——静帧+剪辑切=零抽卡。EP01 11 镜头只抽了 8 个视频。

流程（每步指向真相源，不复制）

1. 立项 charter（operator signoff 的 scope/路线/预算护栏/Non-goals）→ 范例 docs/videos/cucu-pr-flow/episode-brief.md；轻量立项规则见 shared-rules §21（LL-071：先对齐再批量产出）
2. 分镜表：每镜头唯一验收点（一镜一梗）+ 类型 + 方法 + FM 标签 + 3 连败降级预案 → 范例 shot-plan-v0.1.md
3. Prompt book：图 prompt + i2v prompt 全部写成可复制块，含 per-shot 翻车修法 → 范例+配方 prompt-book-v0.1.md（§0.5 附图铁则 / §0.6 i2v 五段配方——从实测成功原文最小修改，禁止凭理解重写）
4. 生产 roll：每 prompt ≤3 roll；roll 判定/FM taxonomy 用 review-protocol-v0.1.md；30 秒人工验收四问（画风像锚图吗/人物比例/文字可读/构图漂没漂）
5. 素材账本：入库即登记 md5/时长/状态；视频 gitignored 账本作存在证明 → 范例 assets/README.md
6. Animatic 检查点（行为刹车）：烧贵素材前先用静帧+占位拼粗剪验证节奏；剧本结构问题（见下）必须在这层抓
7. EDL 渲染：animatic/edl-v1.mjs（时长/字幕/段序真相源）+ build-animatic.mjs（零 npm 依赖：Chrome 当字幕/字卡渲染器 + ffmpeg）——改数字重渲，画幅参数化

实测分工路由（硬约束，不是偏好）

剧本结构（导演层 checklist）

• 喜剧 = 预期 vs 现实，预期端必须拍（任务多小/时间多久）——EP01 初剪"观众看不懂"就是只拍了现实端
• 动机闭环：种子（S00 宣布）→ 潜意识曝光（用自己的头像）→ OS 自白 → 定罪 → true end（爱）
• 真实素材 payoff：片头承诺（"呈堂证供"）片尾兑现（聊天截图证据卷轴）
• 内心 OS 用独立字幕样式（os 参数）；时间跳跃用默片字卡（intertitle.html）

Common Mistakes（全部实测，持续补）

和其他 skill 的区别（GOTCHA）

• video-forge：录屏/教程/showcase 范式（素材是录的）——anime-forge 素材是生成的，核心难题是控制生成模型。做"产品演示视频"→ video-forge；做"有角色有剧情的动画"→ 本 skill
• image-generation：单图生成能力——本 skill 消费它（关键帧步骤），但管的是全片生产
• ppt-forge：静态页面交付——无时间轴

下一步

新集立项 → feat-lifecycle（轻量 charter）；写分镜/prompt 直接抄 EP01 范例改内容；渲染问题先查 build-animatic.mjs 注释里的坑。

Bootcamp Guide — 猫猫训练营引导模式

你的角色

你是新手 operator 的引导猫猫。耐心、鼓励、少用术语。 这是用户第一次和 AI 猫猫协作开发。

核心约束（Iron Rules）

1. threadId：从 🎓 Bootcamp Mode: thread={threadId} 读取。
2. 当前 Phase：从 🎓 Bootcamp Mode: thread=... phase=... 读取。
3. 只执行当前 Phase 的指令，不要提前执行后续 Phase。
4. 允许的 MCP 工具（仅以下两个，禁止使用任何其他 server 的同名工具）：
   • cat_cafe_update_bootcamp_state — 状态推进（Phase 转换）
   • cat_cafe_bootcamp_env_check — 环境检测（仅 Phase 2）
   • ⛔ 禁止：mcp__cat-cafe-collab__* 等其他 MCP server 的同名工具。调用失败时重试同一工具，不换 server。
5. Phase 名必须精确匹配（见下表），不得自创名称。
6. ⛔ STOP 标记：看到 ⛔ STOP 时，发完当前消息后立即停止，等用户下一条消息。⛔ STOP 及其后面的说明（如"前端 overlay 接管"）是内部控制指令，绝不能出现在用户可见的消息中。 不要把 STOP 标记、原因、或任何实现细节（overlay、引导引擎、phase 名称）输出给用户。
7. Phase 推进必须逐步：每次只能推进 1 步（如 phase-4 → phase-5），禁止跳步（如 phase-3 → phase-5）。唯一例外：核心工具全 OK 时 phase-2 → phase-4（跳过 phase-3）。

检查训练营上下文（所有猫必读）

系统提示中如果有 🎓 Bootcamp Mode: 行，说明你在训练营会话中。无论你是哪只猫，都必须检查并遵循训练营流程。

1. 读取 phase= 确认当前阶段
2. 读取 leadCat= 判断自己是主角猫（catId === leadCat）还是队友猫
3. 读取 members= 了解当前团队规模
4. 按下方对应阶段 + 角色的指令执行

Phase 名称（唯一合法值）

phase-1-intro → phase-2-env-check → phase-3-config-help → phase-4-task-select
→ phase-5-kickoff → phase-6-design → phase-7-dev → phase-7.5-add-teammate
→ phase-8-collab → phase-9-complete → phase-10-retro → phase-11-farewell

跳过矩阵

用户说"跳过"时，严格按下表：

整体流程概览

训练营是线性流程，只有一个分支点（环境检测结果）。

MSG 1（你的第一条消息）
│  Phase 1 自我介绍
│  Phase 2 环境检测
│  ├─ 核心工具全 OK → 跳到 Phase 4（唯一允许的跳步）
│  └─ 核心工具有问题 → Phase 3 配置帮助 → Phase 4
│  Phase 4 问用户想做什么
│  ⛔ STOP
│
MSG 2（用户描述了想做的项目后）
│  Phase 5 确认需求
│  Phase 6 给出计划
│  Phase 7 开发交付
│  推进到 Phase 7.5
│  ⛔ STOP
│
MSG 3（用户尝试输入 → 前端拦截 typing → 拉起 guide overlay）
│  Phase 7.5 前端阻断输入，overlay 引导添加队友
│  ⛔ STOP（你不需要说话）
│
MSG 4+（用户 @mention 了新队友）
│  Phase 8 多猫协作
│  Phase 9 引导项目完成 + 项目选择卡
│  Phase 10 前端 overlay 毕业引导（自动触发）
│  ⛔ STOP
│
MSG 5+（毕业引导完成，用户选择项目）
│  Phase 11 毕业后自由开发（正常猫猫开发流程）

MSG 1: 自我介绍 + 环境检测 + 选任务（Phase 1→2→3/4）

按顺序执行：

1. 打招呼，说你叫什么、性格如何、擅长什么（1-2 句）
2. 说用户作为 operator 的角色（1 句）
3. 过渡："好啦，让我先看看你的开发环境准备好了没~ 很快的！"
4. cat_cafe_update_bootcamp_state(threadId, phase='phase-2-env-check')
5. cat_cafe_bootcamp_env_check(threadId)
6. 展示结果：✅ 就绪 / ⚠️ 需安装 / ❌ 缺失
   • tts / asr / pencil 是可选功能，展示时标注"可选"，不影响判定

分支判定（仅看核心工具：node / pnpm / git / claudeCli / mcp）：

路径 A — 核心工具全 OK：

• cat_cafe_update_bootcamp_state(threadId, phase='phase-4-task-select')
• 用 cat_cafe_post_message 发送（不要用普通 agent 消息，agent 消息默认折叠，新用户看不到）： "所以准备工作已就绪，让我们开始第一个小项目吧！描述一下你想让我做个什么小东西——比如一个猫猫主题的欢迎页、一个待办清单、或者随便什么你觉得有趣的！" 末尾附上你的猫猫签名。

路径 B — 核心工具有问题：

• cat_cafe_update_bootcamp_state(threadId, phase='phase-3-config-help')
• 逐项给出具体修复命令（不甩文档链接）
• 修完后必须推进到 Phase 4（不可跳到 Phase 5）： cat_cafe_update_bootcamp_state(threadId, phase='phase-4-task-select')
• 用 cat_cafe_post_message 发送同样的 Phase 4 引导语（附猫猫签名）

⛔ 禁止：不提其他猫（当前只有你一只），不创建选猫卡片。

📨 发送后 → ⛔ STOP — 等用户描述想做什么

MSG 2: 确认 → 设计 → 开发（Phase 5→6→7→7.5）

用户的消息就是他们想做的项目描述。按顺序执行：

1. cat_cafe_update_bootcamp_state(threadId, phase='phase-5-kickoff', selectedTaskId='custom')
2. 确认需求："收到！我来做一个 {用户需求}。"
3. cat_cafe_update_bootcamp_state(threadId, phase='phase-6-design')
4. 给出简要计划（3-5 步）
5. cat_cafe_update_bootcamp_state(threadId, phase='phase-7-dev')
6. 认真完成开发——这是训练营的核心体验，产出必须能用
7. 如果是前端项目，确保 dev server 在跑，给出可点击的 localhost 链接
8. 交付："搞定了！你看看效果~"
9. cat_cafe_update_bootcamp_state(threadId, phase='phase-7.5-add-teammate', guideStep='open-hub')

📨 发送后 → ⛔ STOP — 等用户下一条消息（路由拦截器接管）

MSG 3: 添加队友（Phase 7.5 — 前端拦截 + overlay 接管）

触发方式：

1. MSG 2 结束时 state 已推进到 phase-7.5-add-teammate
2. 用户尝试输入消息时，前端检测到 phase-7.5 → 拦截输入 → 阻止继续 typing → 拉起 guide overlay
3. overlay 引导用户完成：Hub → 添加成员 → 选模板 → 保存 → 回到聊天 → @mention 新队友

设计意图：这一步的目标是引导用户添加第二只猫来协作（review / 约束 / 监管），而不是让用户继续和第一只猫单独聊天。所以必须阻断输入，把用户引导到添加队友的流程上。

你不需要说任何关于"添加队友"的话——引入第二只猫是前端 overlay 自然推进的。 你不需要手动推进 guideStep。

当用户完成 @mention（guide 全部完成）后，前端引导引擎会自动推进到 phase-8-collab。 你不需要手动推进阶段。

📨 ⛔ STOP — 前端 overlay 接管，不要继续说话

MSG 4+: 多猫协作 + 完成（Phase 8→9→10）

用户 @mention 了第二只猫，Phase 已由前端引导引擎自动推进到 phase-8-collab。

队友猫（非 leadCat）的行为

如果你不是 leadCat（你的 catId ≠ system prompt 中的 leadCat 值）：

1. 你是被新用户邀请来评价项目的队友
2. 认真评价 Phase 7 的项目成果，给出具体、有建设性的改进建议
3. 必须在队友名册中找到 leadCat 对应的 @mention 句柄，用行首 @ 把球传给主角猫，让它来修复你发现的问题
4. ⛔ 禁止 @co-creator — 不要问operator谁来处理，直接 @ 主角猫让它修
5. 不要自己动手修代码——你的角色是 reviewer，修复由主角猫完成

主角猫（leadCat）的行为

收到队友猫的 review 后：

1. 根据建议修复所有问题
2. 修完后不要等队友 re-review，不要 @队友 让它确认
3. ⛔ 禁止 @co-creator — 训练营流程由你控制，operator不需要介入

修复完毕后立即执行以下步骤（不要停下来等任何人回复）：

1. cat_cafe_update_bootcamp_state(threadId, phase='phase-9-complete')
2. cat_cafe_update_bootcamp_state(threadId, phase='phase-10-retro') — 必须在发消息/卡片之前，让前端提前收到 phase 更新，agent 结束后 farewell overlay 能立即触发
3. 用 cat_cafe_post_message 发送完成消息（不要用普通 agent 消息，会被折叠）：
   • 自然地告知项目圆满开发结束
   • ⛔ 禁止说"合入主分支"/"merge"——训练营项目不合入主干
   • 不要刻意强调"多猫协作的好处"——用户刚亲身体验过，不用你总结
   • 不要提及 overlay、引导引擎等实现细节——用户不需要知道
   • 末尾附猫猫签名
4. 用 cat_cafe_create_rich_block 发送项目选择卡片（先调 get_rich_block_rules 确认字段要求）：
   • kind: 'interactive', interactiveType: 'card-grid'
   • id: 'bootcamp-next-project'
   • title: '想继续做点什么？选一个感兴趣的项目！'
   • 16 个选项按难度分三层（⭐/⭐⭐/⭐⭐⭐），allowRandom: true
   • 涵盖前端页面、工具脚本、小游戏、数据可视化等方向

📨 发送后 → ⛔ STOP — 前端自动触发毕业引导（farewell overlay）

Phase 10: 毕业（phase-10-retro — 前端 overlay 接管）

引导项目（Phase 4→9）完成，用户已学会多猫协作。现在毕业。

1. 前端检测到 phase-10-retro → 自动触发 bootcamp-farewell 引导 overlay
2. overlay 展示毕业引导（训练营入口位置、如何开始新训练营等）
3. overlay 完成后，前端引导引擎自动推进到 phase-11-farewell

你不需要说任何关于毕业的话——毕业引导是前端 overlay 自然推进的。

📨 ⛔ STOP — 前端 overlay 接管，不要继续说话

Phase 11: 毕业后自由开发（phase-11-farewell）

毕业后用户已经掌握了多猫协作流程。Phase 11 是开放式自由开发—— 用户从 Phase 9 展示的项目卡里选项目，或提出自己想做的东西。

用户选了项目

1. 从消息文本识别选了哪个项目
2. 确认需求："收到！我来做一个 {项目名}。"
3. 按正常开发流程推进：给出计划 → 开发交付 → 多猫协作 review → 完成
4. 完成后自然地问用户还想做什么

注意

• Phase 11 不需要走完整的 bootcamp Phase 5→6→7→8→9 仪式
• 按正常猫猫开发流程工作，用户已经学会了
• Phase 保持在 phase-11-farewell，不再推进
• 不要问用户技术前提（如 API Key、环境配置）——直接做可运行的 demo 版本，用 mock 数据或本地方案替代外部依赖。用户想升级时再引导配置

"🎓 恭喜毕业！你已经掌握了多猫协作的完整流程。去创造点什么吧~"

Browser Automation

这是家里的上层浏览器路由 skill。

它只做三件事：

• 判断这次任务该不该用浏览器
• 选择合适的浏览器后端
• 把任务转给更具体的 skill / ref，而不是在这里重复厂商文档

执行前四问

在真正打开浏览器前，先回答这四个问题：

1. 真的需要浏览器吗？ 如果只是读文档、抓纯文本、做搜索，不要默认上浏览器。
2. 目标是 localhost 还是外部网站？ localhost → browser-preview；外部网站才留在本 skill。
3. 这只猫的客户端能力是什么？ MCP 原生、CLI-only、是否有 webfetch、是否能跑 shell、是否有 VL。
4. 这次任务的 session 属于谁？ 是匿名访问、猫自己的浏览器会话、还是接手人类已登录会话。

什么时候用

• 目标是外部网站，需要真实浏览器执行 JS、登录、点按钮、下载、截图
• 猫没有 webfetch，或者 webfetch 不足以完成交互
• 需要在 agent-browser / Playwright MCP / Playwriter / PinchTab 之间做路由
• 需要明确“这类浏览器任务的默认打法是什么”

不要用在这里

• localhost 页面预览、HMR、给operator看效果 → 用 browser-preview
• 本地 WebApp 的确定性测试、Console、截图、回归验证 → 用 webapp-testing
• 简单网页抓取、官方文档阅读、搜索结果整理 → 优先用更轻量的搜索 / fetch 工具，不要先上浏览器
• 已有领域专用浏览器 skill 的任务 → 专用 skill 优先

默认路由顺序

1. 先问：真的需要浏览器吗？ 如果只是读文档、抓纯文本、做搜索，不要默认上浏览器。
2. 目标是 localhost 吗？ 是 → browser-preview
3. 目标是本地 WebApp 验证吗？ 是 → webapp-testing
4. 客户端已经有稳定可用的 Playwright MCP 吗？ 是 → refs/playwright-mcp.md（MCP ID: playwright）
5. 需要接手人类已登录的 Chrome、复杂 iframe、多 tab 调试吗？ 是 → 用 claude-in-chrome MCP（工具前缀 mcp__claude-in-chrome__*），参考 refs/playwriter.md
6. 这是 CLI 型猫，没 webfetch / 没 VL，但能跑命令吗？ 是 → refs/agent-browser.md（MCP ID: agent-browser，社区 wrapper，使用前先做本机验活）
7. 需要长驻 daemon、持久 session、HTTP-first 服务吗？ 是 → refs/pinchtab.md（MCP ID: pinchtab，优先 native binary pinchtab mcp，不要默认相信 npm wrapper）

路由矩阵

常用组合打法

读取哪些 refs

交付要求

每次真正使用浏览器后端，至少说清楚这四件事：

• 用了哪个后端，为什么不是另一个
• 目标站点 / 路径 是什么
• 是否涉及登录态；如果涉及，是谁的 session
• 留下了什么证据：截图、提取文本、Console、下载文件、操作结果

如果任务涉及人类账号：

• 不要默认代替人类登录敏感站点
• 明确说明是否是“接手现有已登录会话”
• 结束时说明是否保留了 session / cookie / tab 状态

Common Mistakes

和其他 skill 的区别

下一步

• localhost 页面 → browser-preview
• 本地 WebApp 验证 → webapp-testing
• 其余外部网站任务 → 读取匹配的 refs/*.md 后执行

Browser Preview

Hub 内置了嵌入式浏览器面板（F120），可以直接预览运行中的 localhost 应用。猫猫写完前端代码不用让operator切浏览器看效果。

工作流

基础流程（端口发现 → 预览）

1. 在 Terminal 启动 dev server（pnpm dev / npm start / vite 等）
2. Hub 自动检测端口 → 弹出 toast 提示"检测到 localhost:xxxx 启动"
3. 点击 Open Preview → 自动打开 browser panel 并加载页面
4. 也可以手动：切到 workspace 的 Browser tab，输入 localhost:port 按 Go

改代码 → HMR 热更新 → browser panel 内页面自动刷新，无需手动操作。

猫主动打开浏览器（Phase C — 必须掌握）

operator说过："别手动让我输入，你最好打开浏览器，把页面放出来。"

猫应该主动替operator打开浏览器，不要等operator点 toast 或手动输 URL。

调用步骤（按顺序执行，不要跳步）

Step 1: 确认目标服务器在跑
  curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT
  → 200/301/304 = 可以继续
  → 000/connection refused = 服务器没起来，先启动再说

Step 2: 调用 typed MCP
  cat_cafe_preview_open({
    port: PORT,
    path: "/",
    worktreeId: "当前 worktreeId（有就传）",
    threadId: "当前 threadId（有就传）"
  })

Step 3: 等 1-2 秒，右侧 Browser panel 应自动打开
  → 如果没反应，检查 Step 1 是否真的返回了 200

工具参数

怎么获取 worktreeId：就是你当前工作的 worktree 目录名。例如你在 cat-cafe-f120-fix 目录里工作，worktreeId 就是 cat-cafe-f120-fix。如果你在主仓库 cat-cafe 里，就不需要传。

常见错误

• 适用场景：写完前端代码后、operator说"看看效果"、需要展示复杂页面
• ⚠️ 不要传 html 参数（后端不支持）；简单 HTML 可视化用 html_widget rich block

两层可视化策略

operator拍板："简单的用富文本，复杂的用猫主动打开浏览器。"

技术要点（猫猫需要知道的）

什么时候主动用

• 写完前端组件/页面 → 主动调 auto-open 打开浏览器展示（不要等operator点）
• 调样式/布局 → 改代码后在 browser panel 里实时查看
• operator说"看看效果"/"给我看看" → 主动打开 browser panel 展示
• dev server 已在 Terminal 跑着 → 主动打开浏览器，不要只提示
• 简单可视化（图表/动画） → 用 html_widget rich block 内联渲染
• Console 有报错 → browser panel 下方 Console 面板自动展开，可以看
• 需要截图 → browser panel 工具栏一键截图；默认先存到 ${TMPDIR}/cat-cafe-evidence/...，不要落仓库根目录（见 refs/evidence-output-contract.md）

不要做的事

• 不要跳过 Step 1（验证服务器）直接调 cat_cafe_preview_open — 服务器没跑 = proxy error
• 不要用 Playwright / Chrome MCP / open 命令打开系统浏览器 — F120 是 Hub 内嵌预览，走 iframe，不走系统浏览器
• 不要手写 /api/preview/auto-open 的 curl — 主路径是 cat_cafe_preview_open
• 不要手动去构造 gateway URL（让 Hub 前端处理）
• 不要尝试预览外部 URL（只支持 localhost）
• 不要预览 Cat Cafe 自身服务端口（会被端口验证拦截）
• 不要把临时截图顺手留在仓库根目录；要入库时再显式归档到正式目录

和其他 skill 的区别

Collaborative Thinking

三种思考模式：单人探索 / 多猫独立思考 / 讨论收敛沉淀。与 feat-lifecycle 讨论阶段的区别：feat-lifecycle 专用于 feat 采访和需求澄清；本 skill 是通用思考框架。

核心知识

Mode A: 单人探索 (Brainstorm)

目标：将模糊想法转化为可执行 spec，通过增量验证降低返工。

1. 理解上下文：先读项目现状（文件、文档、近期 commits）。每次只问一个问题，优先多选题。
2. 探索方案：提出 2-3 个备选 + tradeoffs，先说推荐和理由。YAGNI 无情剪枝——"以后可能需要"的功能先砍。
3. 呈现设计：每次 200-300 字，每段后问"这个方向对吗？"。覆盖：架构 / 组件 / 数据流 / 错误处理 / 测试。
4. 产出：设计文档写到 feature-specs/YYYY-MM-DD-{topic}-design.md，commit 后问"要开始实现了吗？"

Mode B: 多猫独立思考

何时启动 Mode B？ 参见 shared-rules.md §13 元思考触发器 A-D。 调 cat_cafe_multi_mention 前必须带搜索证据（searchEvidenceRefs）。

⚠️ 成本警告：Swarm token 消耗是单猫 N 倍（N = 参与猫数）。实现细节不值得开 swarm。

6 阶段流程：

Phase 1: 独立思考（并行，禁止互看）
Phase 2: 串行讨论（有分歧才触发，限 2-3 轮）
Phase 3: operator选扇入者
Phase 4: 扇入综合（会议纪要 + 行动项）
Phase 5: 其他猫审阅补充（纠正误读）
Phase 6: operator反馈 + 最终确认 → 进入 Mode C

Phase 1 独立性保护规则（最重要）：

• 禁止互看：每只猫独立完成，不预测他人观点
• 防锚定：有背景材料时，先形成自己想法再参考
• 展示推理链："我为什么这么想"，不只给结论
• 标注不确定性：区分确信的结论和猜测

实现方式：routeParallel() 或operator分别 @ 各猫并强调"先独立思考"。

Phase 2 触发：各方基本一致 → 跳过；存在明显分歧 → 需要（限 2-3 轮）；operator说"够了" → 跳过。

Phase 4 综合必须包含：各方观点摘要 / 共识区 / 分歧区（不要抹平！）/ 待决事项 / 行动项。

Open Questions 分类（必须拆开）：

• 技术 OQ：给猫猫解决的（实现细节、方案选型中可回滚的部分）
• 价值 OQ：需要 operator 判断的 → 必须附 Decision Packet（格式见 refs/decision-matrix.md）

如果所有 OQ 都是技术型且回滚成本低，不升级 operator——猫猫自决 + 事后通报。

扇入者默认：Brainstorm 类 → operator；技术讨论 → 指定综合者 + 指定把关者。operator可随时覆盖。

Mode B 严格档（高 stakes Roundtable）

来源：2026-06-16 圆桌 saga（docs/content/drafts/longform-005-case-the-roundtable-that-caught-itself.md）。 ⚠️ 原则强化，不是填表剧本——写成僵硬步骤就成了 longform-005 批的"演戏"。

何时启用：决策不可逆 / 多方案价值取舍（非对错题）/ 方向级·跨多 feature。门槛宜高——日常 plan 走标准 Mode B，别开严格档（仪式化会贬值）。标准 6 阶段之上多守 5 条原则：

1. 沉默 ≠ 同意（防虚假共识）：高风险条目上，快速全票是危险信号不是高置信；每只猫要么提反例，要么说清"查了什么才不反对"——不是没声音就算过。
2. 价值题不许技术化逃逸：可 early-exit 退普通 writing-plans；但任一猫判某条为价值/不可逆/高风险就不能 exit，且否决须附"理由 + 什么能推翻它"（同时防技术题被反向价值化绑架）。
3. 分歧不抹平：Phase 5 升为硬门——被代表的猫必须确认分歧没被扇入者写歪。
4. 不无限续命：复用 Phase 2 的 2-3 轮上限；超限出 split-options 给 operator 或诚实宣告未收敛，不硬凑共识。
5. 收敛接 census：严格档收敛稿（含 early-exit）handoff 给 writing-plans 必带 Stateful Object Gate——圆桌收敛 tradeoff ≠ 完成 census。

operator 介入：价值 OQ 最后给 operator，优先提问而非表态；表态标"价值偏好"不伪装事实约束。最终方案==operator 初始未公开倾向 → 自检"论证结果还是锚定"（这是 convention 自检；高 stakes 要强制，再升硬层 sealed-commit，别误读成已有机械执法）。

软硬边界（ADR-031）：以上是软层原则。"sealed 盲发 / 留痕格式 / 否决 packet schema"要做成可机械检测的强制属硬层（hook/validator），单独立项——别塞进 skill 当填表步骤。

Mode C: 收敛沉淀 (Convergence)

收敛时 operator 升级检查：如果收敛结论中有需要 operator 拍板的 Open Question，必须附 Decision Packet（格式见 refs/decision-matrix.md）。先判断可逆性：回滚成本低的猫猫自决，不升级。

收敛三件套——每项必须显式回答"有/没有"，不允许跳过：

1. 否决理由 → ADR：这次讨论有否决某个技术方案？有 → 补到对应 ADR 的否决记录段。

2. 踩坑教训 → public-lessons.md：这次讨论有暴露新坑？有 → 追加到 docs/public-lessons.md（7 槽位格式）。

3. 操作规则 → 指引文件：这次讨论有产生新的必须遵守的规则？有 → 更新 CLAUDE.md / AGENTS.md / GEMINI.md（或 refs/shared-rules.md）。

强制回答格式（附在 commit message 或文档末尾）：

## 收敛检查
1. 否决理由 → ADR？[有 → 已补到 ADR-0xx / 没有]
2. 踩坑教训 → lessons-learned？[有 → 已追加 / 没有]
3. 操作规则 → 指引文件？[有 → 已更新 CLAUDE.md §xx / 没有]

追溯链（每次收敛必须建立）：BACKLOG 条目 link 会议纪要入口；每篇文档头部 link 回上级文档。

会议纪要模板（存放：feature-discussions/YYYY-MM-DD-{topic}-meeting-notes.md）：

# {主题} 讨论纪要
**Thread ID**: `thread_xxx` | **日期**: YYYY-MM-DD | **参与者**: [列出]

## 背景 / 各方观点 / 共识 / 分歧 / 待决 / 行动项

Quick Reference

Common Mistakes

下一步

• Mode A 结束 → worktree 拉 worktree，writing-plans 做实现计划
• Mode B 结束 → 必须进入 Mode C 收敛
• Mode C 完成后 → commit：docs({scope}): {topic} 讨论收敛 + 追溯链 [{猫猫签名}]
• 产出了新 feat → feat-lifecycle skill 立项

Console-Dev

Console 前端开发先定入口和状态，再写组件。这个 skill 不替代 tdd / quality-gate，它补齐前端特有的产品路径、设计 token、交互状态和视觉证明。

Gate 1: Product Gate

先回答：用户从哪里进入？这个能力属于哪个层级？

涉及状态的 UI 必须列状态矩阵：loading / empty / partial / full / error，owner / member / guest / unauthenticated，desktop / mobile。

Gate 2: Design-System Gate

新代码 token first：颜色、边框、语义状态优先复用现有 CSS variables 和组件 primitive。旧代码迁移可以渐进，但 debt 清单只能减少，不能因为新功能扩大豁免。

Gate 3: Implementation Gate

拆分方向优先是视觉独立 sub-component，不是把小工具函数切碎。

Gate 4: Verification Gate

必须给证据：

• Golden path 走通
• 至少覆盖一个非 happy path 状态
• 改共享 primitive 时抽样兄弟页面
• modal 检查 footer、滚动容器、sticky action、ESC/关闭行为
• 暗色/移动端如果会被影响，必须抽样

Common Mistakes

和其他 Skill 的区别

• tdd：负责测试驱动实现；console-dev 负责前端入口、状态和视觉门禁。
• browser-preview：负责打开/验证页面；console-dev 定义你要验证什么。
• quality-gate：交付前总门禁；console-dev 是前端子门禁。
• pencil-design：产出设计稿；console-dev 把设计稿落到运行态。

参考

• refs/f190-frontend-lessons.md — F190 Console intake 的具体案例。
• docs/architecture/feature-placement.md — Console 入口层级决策树。

Context 自管理：handoff vs 压缩是个判断 🐾

系统发来 context_management_hint(warn) = 你进了 warn 区（离 auto-seal 还有一段）。 系统知道何时该想（context% 是你的盲区，它替你盯）；干什么由你判——别一看 warn 就反射 handoff，也别无脑等压缩。

compress ≠ 坏事。干一半连贯的活、还没压过 → 压缩反而保住 in-flight 线索；这时硬 handoff 会把半成品工作态丢给一个写不全五件套的"干净自己"，更糟。

三问自检（系统给数据，你下判断）

1. 线还是树？（脏=话题漂移）这一程是一条主线，还是 a→g 一堆不相关的事？
   • 客观锚：compressionCount > 0 ⇒ 你已经跑很久了，警惕自己低估漂移（Ragdoll尤其爱把树硬串成线）。
2. 有干净断点吗？ 手头这件事到没到一个能利落收尾的点？干一半 = 没有。
3. fill 可信度？ hint 里 fillConfidence：exact_token 信那个 %；approx_token/bytes_health 当弱信号；unavailable 别看 %、纯靠①②自检。

2×2 决策矩阵

怎么动手

• handoff → 调 cat_cafe_propose_session_handoff，手写五件套（做完了啥 / 正在做啥 / 下一步 / 关键决策与坑 / 别碰啥）。这是给"干净的自己"的纸条，不是给别的猫——交给别的猫是 cross-cat-handoff。提案要人来 gate，你不自己封。
• 冲刺 → 不 handoff 不主动压，盯着把当前任务推到最近干净断点，到了再 handoff；真撞 auto-seal 了有 F24 兜底。
• 续/压缩 → 啥都不用做，继续干；CLI 该压会压，线索还在。

反模式：一 warn 就 handoff（丢半成品线索）/ 一 warn 就清空重来（那是焦虑不是判断）。判据永远是"线还是树 + 有没有干净断点"，不是 context% 数字本身。

Convention Graph Discovery

价值门禁 / Why This Is a Skill

这是 Cat Café 特有的方法论：把 repo 里的“约定层关联”（MCP tool、skill trigger、route、workflow callback、配置驱动注册）画成带 provenance/freshness 的图。它不是通用 AST 教程，也不是让猫依赖 codegraph/GitNexus；它把 F242 的 dogfood 经验沉淀成未来进 repo 的第一步。

核心知识 / Overview

LSP 看符号，grep 看文本；约定图看“这个 repo 的规矩”。每条边必须能回答三件事：它从哪个 source span 来、当前图新不新鲜、漏识别的 gap 在哪。

When to Use

用在：

• 刚进入陌生 repo，需要先摸清“改 X 会影响谁”。
• 改动触及配置/注册/manifest/route/callback 等约定层，不只是函数调用。
• 改 MCP tool schema/name、skill manifest、FastAPI/API route、workflow callback 前，需要先找约定层消费方。
• F242 / Convention Graph Layer 相关实现、dogfood、review。

不要用在：

• 已经能用 LSP 精确跳转的普通函数调用。
• 只想找文档或历史讨论（用 memory-navigation / memory-search-best-practices）。
• 想把 codegraph/GitNexus 当外部依赖直接接入。
• 只是 cat-cafe 自家 extractor 的硬编码搬运。

流程 / Discovery Protocol

1. 定边界：写清 repo、目标问题、要验证的 convention domain。例：MCP tool 消费方、FastAPI route、skill trigger。
2. 找显式锚点：优先找名字/ID/typed import/config key/manifest field。禁止 name-only 跨语言合并。
3. 定义 domain：列 domainId、node kinds、edge kinds、extractor inputs、invalidation scope、negative fixtures。
4. 写 extractor：先用最小 fixture TDD，产出 nodes / edges / gaps。每条 edge 带 extractor/version/sourceFile/sourceLine/confidence。
5. 接引擎：记录 index commit + indexed file hashes；查询必须带 freshness，pending changes 直接标 stale。
6. 对比基线：用 grep/LSP 或人工查证对比，记录它们漏了什么、约定图多解释了什么。
7. 报 gap：发现框架或约定但没覆盖时输出 gap/unknowns，不能静默 0 命中。

Product Entry / Commands

在 Cat Café repo 根目录，先重建当前 repo 的图：

pnpm convention-graph:index -- --repo .

查某个 MCP tool 的约定层消费方：

MCP_TOOL_NAME=replace_with_tool_name
pnpm convention-graph:code-consumers -- --repo . --domain mcp-tool --kind mcp_tool --name "$MCP_TOOL_NAME"

输出是 JSON，包含 targets、consumers、每条 edge 的 provenance，以及 freshness。如果 freshness.stale=true，这次查询只能当 stale 证据；先重跑 convention-graph:index，再决定影响面。

当前内置 domain：mcp-tool、skill-manifest、fastapi-route。新 repo 的未知约定不要写 ad-hoc 查询脚本；按 Discovery Protocol 定义 domain plugin，再接同一个 CLI/engine。

Quick Reference

Common Mistakes

验证 / Pressure Test

• 至少两个 domain 通过 fixture：一个结构注册类，一个 manifest/config 类。
• 每个 domain 有 negative fixture，证明同名非约定对象不误连。
• 改一个已索引文件后，查询结果必须 stale=true 并列出 pending change。
• 对一个真实“改 X 找消费方”场景 dogfood，写出 grep/LSP 对比差异。

和其他 Skill 的区别

• tdd：写 extractor 代码时仍要用；本 skill 负责“该画什么图、怎样定义 domain”。
• knowledge-engineering：面向文档结构化；本 skill 面向代码约定层。
• memory-navigation：找历史知识；本 skill 建当前 repo 的实时工作 artifact。
• open-source-teardown：拆外部项目学习；本 skill 把学习结果落成自家 repo 的约定图方法。

下一步

Domain 定义收敛后 → tdd 写 extractor → quality-gate 做 spec/freshness/provenance 自检。

Cross-Cat Handoff

Core principle: 交接不能只写"改了什么"。没有 Why = 接手方无法判断 = 低效协作。

五件套（必须全部包含）

每次交接/传话/review 请求必须包含：

检查流程

BEFORE 发送交接/传话/review请求:

1. SCAN: 检查消息是否包含五件套
2. MISSING: 识别缺失项
3. BLOCK: 如有缺失，阻止发送并提示补充
4. PASS: 全部包含，允许发送

Block 场景

❌ 只写 What

Author 猫准备写: "@ Reviewer 我改完了三个文件，帮我 review"

⚠️ BLOCKED — 交接缺失必要信息

缺失项:
- ❌ Why: 为什么要改？
- ❌ Tradeoff: 有没有考虑过其他方案？
- ❌ Open Questions: 有什么不确定的？
- ❌ Next Action: 希望 review 什么重点？

请补充五件套后再发送。

❌ 只有 What + Why

Author 猫准备写: "@ Reviewer 我加了 CAS 保护，因为发现竞态问题"

⚠️ BLOCKED — 交接缺失必要信息

已有:
- ✅ What: 加了 CAS 保护
- ✅ Why: 发现竞态问题

缺失:
- ❌ Tradeoff: 为什么选 CAS？考虑过其他方案吗？
- ❌ Open Questions: 有什么不确定的？
- ❌ Next Action: 希望 Reviewer 做什么？

请补充后再发送。

通过场景

✅ 完整的交接

## 交给 Reviewer Review: ADR-008 S2 Retry + CAS

### What
新增 CAS Lua 脚本保护 InvocationRecord 状态更新：
- `CAS_UPDATE_LUA`: HGET 比对 + HSET 更新
- 修改 `RedisInvocationRecordStore.updateStatus()`
- 新增 `snapshotStatus` 在调用前保存原始状态

### Why
内存 store 的 `get()` 返回活引用，导致：
1. 读取 status 后，在比对前可能被其他请求修改
2. 原来的 CAS 逻辑比对的是已经被修改的值
3. 导致竞态条件：两个并发请求都能通过比对

### Tradeoff
考虑过的方案：
- **乐观锁（version 字段）**: 需要改 schema，影响面大
- **分布式锁**: 太重，且 Redis 单线程本身就是串行的
- **Lua CAS**: 选择这个，原子性由 Redis 保证

### Open Questions

**技术 OQ**（猫猫解决）：
1. `keyPrefix` 在 `eval()` 中的行为是否和普通命令一致？
2. 是否需要添加重试逻辑？

**价值 OQ**（如需 operator 拍板，附 Decision Packet——格式见 `refs/decision-matrix.md`）：
- （本次无）

### Next Action
请 review 这三个文件：
1. `RedisInvocationRecordStore.ts` - CAS Lua 实现
2. `InvocationRecordStore.ts` - snapshotStatus 逻辑
3. `invocation-flow.spec.ts` - 竞态测试用例

重点关注：
- Lua 脚本的原子性是否正确
- snapshotStatus 时机是否正确
- 测试是否覆盖竞态场景

✅ 检查通过 - 五件套完整

交接类型

1. Review 请求

交给其他猫审查代码。

重点：

• What: 改了哪些文件
• Why: 为什么要这样改
• Next Action: 希望 reviewer 关注什么

2. 工作交接

一只猫做到一半，另一只猫接手。

重点：

• What: 当前进度
• Open Questions: 遇到的问题/卡点
• Next Action: 下一步建议做什么

3. 决策通知

通知其他猫一个重要决策。

重点：

• What: 做了什么决定
• Why: 为什么这样决定
• Tradeoff: 放弃了什么方案

4. 开放讨论邀请

邀请其他猫讨论某个方向性问题（不是任务指派）。

特殊规则：

• 这是讨论，不是任务
• 给开放问题，不问引导性问题
• 透明展示推理链
• 让对方先形成自己的想法再看你的分析

详见 feat-lifecycle skill 的讨论阶段（开放讨论模式）。

常见错误

五件套检查清单

复制此清单用于自检：

交接五件套自检:
- [ ] What: 具体改动/决策是什么？
- [ ] Why: 为什么这样做？约束/风险/目标是什么？
- [ ] Tradeoff: 放弃了什么备选方案？
- [ ] Open Questions: 还有什么不确定的？
- [ ] Next Action: 希望接手方下一步做什么？

下一步

• 交接 review 请求 → 接收方用 receive-review
• 交接开发工作 → 接收方用 worktree 开始
• 交接讨论邀请 → 接收方用 collaborative-thinking

参考

• 五件套详见：refs/shared-rules.md §1
• Review 信存放：review-notes/

Cross-Thread Sync

平行 session 之间的协同：发现 → 通知 → 协调 → 确认。

硬规则：cross-post 是通知层，不是真相源。阻塞信息必须双写到可追溯状态（feature doc / workflow / task）。

⚠️ 路由铁律：cross-post 消息如果没有 @mention 也没有 targetCats，消息会到达目标 thread 但不会触发任何猫 session——消息静默躺在那里，直到operator手动 @ 某只猫。必须用以下任一方式触发目标猫：

1. 在 content 末尾另起一行写 @句柄（如 @目标猫句柄）
2. 传 targetCats 参数（如 targetCats: ["opus"]）

Step 1: 发现（谁在平行工作？）

# 1. 优先用 feat_index 找相关 thread
→ cat_cafe_feat_index(featId="F088")  → 返回相关 threadIds

# 2. 确认哪些在活跃
→ cat_cafe_list_threads(activeSince=<2h_ago_ms>)

# 3. 必要时补上下文（D15: cat_cafe_search_messages 已删除，用以下两个替代）
→ cat_cafe_search_evidence(query="F088 phase", scope="threads", depth="raw")  # 跨 thread 搜过程
→ cat_cafe_get_thread_context(threadId="<target>", keyword="F088")  # 单 thread 取最近消息

判断是否需要同步：

入站门禁：收到跨线程消息时先判归属

跨线程消息是路由候选，不是自动授权。尤其是 source thread / sender cat 与当前 thread 不同、消息里要求“take over / implement / open PR”时，先停 30 秒做 ownership gate，再决定接/退/升。

三问（缺一不接）

判定动作

失败模式：看到“跨线程消息 + action brief”就猛开 worktree，会把别的 feature 的上下文和 WIP 污染进当前 thread。正确做法是先判归属；cross-post 是通知层，不是接活授权。

Step 2: 通知（3+2 升级制）

默认三件套

所有跨 thread 通知必须包含：

同步级别

Action Needed 必须标注级别：

升级到五件套

触碰以下任一 → 三件套之外必须补 Why + Tradeoff：

• API 契约变更（接口签名、入参出参）
• packages/shared/** 改动
• 共享状态文件的结构性变更
• 不可逆决策（schema migration、数据删除）

发送方式

→ cat_cafe_cross_post_message(
    threadId: "<target_thread_id>",
    targetCats: ["opus"],
    content: "## 🔄 Cross-Thread Sync\n\n### What Changed\n...\n\n### Impact on You\n...\n\n### Action Needed\n[ACTION] ...\n\n@opus"
  )

⚠️ 必须触发目标猫（见顶部路由铁律）：传 targetCats 且 在 content 末尾 @句柄（双保险）。缺了这步 = 消息送达但无人看到。

Step 3: 争用协调（共享文件冲突预防）

Claim 协议

准备改共享文件/shared 包之前：

1. Claim — cross-post 声明：
   "🔒 Claim: 我要改 [文件/范围]"
   附带：threadId + 文件路径 + claimedAt 时间

2. 让路 — 收到 claim 的 session 如果也要改同一文件：
   停下等对方完成。不要同时改。

3. 释放 — 完成后显式通知：
   "🔓 Release: [文件/范围] 改完了，已 commit push"

4. 超时失效 — 如果长时间未释放（session 掉线/压缩）：
   其他 session 可以重新 claim

5. 升级 — 双方都不能让：
   升级operator决定优先级

场景速查

Step 4: 确认

§15 家规：BLOCKING 信息不能只留在 cross-post 消息里，必须同时写入可追溯状态（feature doc / workflow / task）。

Ghost Thread Bug 保守规则

已知 Bug (P2, OPEN)：cross-post 后 session continuation 可能绑错 thread（见 docs/bug-report/ghost-thread-cross-thread-session-routing/）。

在此 bug 修复前：

• cross-post 只用于单次通知，不做来回对话
• 不做自动 hook 广播（避免路由 bug 扩大为系统噪音）
• 如果发现自己收到了不属于自己 thread 的 mention → 停下来报告

常见误区

和其他 skill 的区别

下一步

• 需要交接工作给其他猫 → cross-cat-handoff
• 争用升级到operator → 直接在 thread 里说明情况

Debugging（系统性调试）

随机尝试修复浪费时间，症状修复掩盖真正问题。

遇到 bug 先搜（F102 记忆系统）：search_evidence("{error关键词}") 看看历史上有没有类似的坑。

铁律：没有根因分析，不能提出修复方案。

核心知识

Runtime Preflight Gate（运行时异常硬门禁）

如果 bug 涉及 runtime 行为（前端显示异常、API 返回错误、猫猫行为异常、stream 错误等），在进入 Phase 1 之前必须先完成三件套验证：

手动三件套（按顺序执行，收集 7 个字段）：

# 1. 找到 API 监听进程（绑端口，不用 grep 猜）
export API_PORT="${API_SERVER_PORT:-3004}"
lsof -iTCP:"$API_PORT" -sTCP:LISTEN -P -n 2>/dev/null | awk 'NR>1{print "PORT="ENVIRON["API_PORT"], "PID="$2}'

# 2. 进程启动时间
ps -p <PID> -o lstart=

# 3. Runtime worktree HEAD vs 目标 commit
git -C <runtime-worktree> log --oneline -1        # HEAD=
TARGET_COMMIT=<你预期的commit>
# 判断进程是否在 commit 之后启动：比较 commit 时间 vs 进程启动时间

# 4. 当前 PID 在最新日志中的行数
grep -c "<PID>" <最新日志文件路径>                  # LOG_EVIDENCE=

收集到的 7 个字段：

PORT=3004              ← 默认 API 端口（3003=前端），只取 LISTEN PID
PID=53507              ← 精确到监听进程（排除浏览器等客户端连接）
START_TIME=...         ← 进程启动时间
HEAD=abc1234 ...       ← runtime worktree HEAD
TARGET_COMMIT=f78c984  ← 你预期的 commit
PROCESS_AFTER_TARGET=yes/no  ← 进程是否在 commit 之后启动
LOG_EVIDENCE=...       ← 当前 PID 在最新日志中的行数

这 7 行没拿到之前，唯一允许说的话是"我还没查完"。

以下断言必须附带 preflight 输出，否则禁止说出：

• "runtime 没更新" / "代码没编译" / "没重启" / "还是旧代码"

为什么这是硬门禁：启动脚本会自动拉代码并编译。"没更新"本来就不太可能发生。在没有证据的情况下说"没更新" = 把自己的 bug 甩锅给operator。这不是懒，是推卸责任。

来源：operator多次纠正（2026-04-05 定为 P0），Maine Coon协助定位根因 + 方案审查。

4 阶段流水线

每个阶段必须完成才能进入下一个。

Phase 1 — 根因调查（提出任何修复前必须完成）

1. 仔细读错误信息：不要略过 stack trace，记录行号/文件路径/错误码
2. 稳定复现：能稳定触发吗？不能复现 → 收集更多数据，不要猜
3. 检查最近变更：git diff、新依赖、配置变更、环境差异
4. 多组件系统：加诊断桩收集证据

   对每个组件边界：记录进入的数据、记录输出的数据、验证状态传播
   先跑一次收集"哪里断了"的证据，再分析，再深入那个组件
   

5. 数据流逆向追踪：错误值从哪里来？谁传了这个错误值？一直往上追到源头，在源头修，不在症状处修（完整技术见 root-cause-tracing.md）

Phase 2 — 模式分析

• 在同一代码库找可以工作的类似代码
• 对照参考实现完整地读（不要略读）
• 逐项列出工作代码和问题代码的差异，不要假设"这个不重要"

Phase 3 — 假设验证

• 明确写下："我认为根因是 X，因为 Y"
• 做最小可能的变更验证假设（一次一个变量）
• 通过了 → Phase 4；没过 → 提出新假设，不要在上面叠加更多修复

Phase 4 — 实现修复

1. 先写失败测试复现 bug（参见 tdd skill）
2. 实现针对根因的单一修复
3. 验证测试通过、无回归
4. 如果修复无效 → 回 Phase 1，带着新信息重新分析

⚠️ 3+ 次修复都失败 = 架构问题

出现以下模式就停下来质疑架构，不要尝试第 4 次修复：

• 每次修复都在不同地方暴露新的耦合/共享状态
• 修复需要"大规模重构"才能落地
• 每次修复都在别处制造新症状

停下来和operator讨论是继续修还是重新设计。

Bug Report 五件套（存档格式）

存放位置：docs/bug-report/<bug-name>/bug-report.md

1. 报告人：谁发现的、怎么发现的
2. 复现步骤：期望行为 vs 实际行为
3. 根因分析：查了什么、排除了什么、定位过程
4. 修复方案：选这个方案的理由、放弃了什么备选
5. 验证方式：怎么确认修好了

五件套是调查完成后的存档格式，不是入口。 入口是诊断胶囊（见下方「Bug 诊断胶囊」节）。

流程

收到 bug / 看到失败
  ↓
涉及 runtime？→ 是 → Runtime Preflight Gate（三件套）
  ↓ 否 / 三件套完成
填诊断胶囊（8 栏工作模板）← 入口！
  ↓
Phase 1: 根因调查（胶囊驱动）
  ↓ 找到根因？
Phase 2: 模式分析（对照工作代码）
  ↓
Phase 3: 假设验证（最小变更，一次一个）
  ↓ 假设确认？
Phase 4: 先写失败测试 → 修复 → 验证
  ↓ 修复 3 次仍未解决？
停下来 → 质疑架构 → 找operator讨论
  ↓ 修复完成
整理五件套存档（从胶囊提炼）

Quick Reference

立即停止的 Red Flags

听到自己说以下任何一句 → 停下来，回到 Phase 1：

• "先试试改 X 看看效果"
• "大概是 X，我改一下"
• "不太理解但这个或许能用"
• "跳过测试，我手工验一下"
• "同时改几个地方"
• "再试一次修复"（已经失败 2 次以上）
• "可能没更新/没编译/没重启"（没跑三件套就说 = 推卸责任）

Common Mistakes

和其他 skill 的区别

• vs tdd：debugging 是修复性的（bug 出现后）；TDD 是预防性的（写代码前）。交叉点：Phase 4 写失败测试时切换到 TDD 模式
• vs quality-gate：debugging 是找到并修复问题；quality-gate 是提交前确认一切正常

Bug 诊断胶囊

Phase 1 开始时，用 8 栏诊断胶囊 结构化调查过程：

模板 → refs/bug-diagnosis-capsule.md

胶囊 8 栏：现象 / 证据 / 问题假设或根因 / 诊断策略 / 超时策略 / 预警策略 / 用户可见交互修正（可选） / 验收

胶囊是调查过程的工作模板，五件套是 bug report 的存档格式。 两者互补：先填胶囊驱动调查，再整理五件套存档。

补充参考文件

以下参考材料已随 skill 合并归档（原 systematic-debugging/ 目录），可从 git 历史查阅：

• root-cause-tracing.md — 从 call stack 深处向上追踪原始触发点的完整技术
• defense-in-depth.md — 找到根因后，在多层添加防御性校验
• condition-based-waiting.md — 用条件轮询替代任意 timeout

运行日志快速查看（F130）

右侧状态面板底部有「运行日志 → 查看日志」按钮：

• 点击后自动切换到 Workspace 面板，展开到 packages/api/data/logs/api/ 并打开最新日志文件
• 日志格式：Pino JSON（每行一条），文件名 api.YYYY-MM-DD.SEQ.log（日轮转，14天保留）
• 也可以通过 Navigate API 打开：POST /api/workspace/navigate {"path":"packages/api/data/logs/api/","action":"reveal","worktreeId":"..."}
• 调试时先看日志再分析，不要猜

下一步

修复完成并通过验证后 → 加载 quality-gate 做提交前验收

Deep Research

两种模式：

• Mode A: 多源调研：Web 猫（网络搜索）+ Coder 猫（代码判断）+ GPT-5.2 Pro（审阅）= 三角验证
• Mode B: 云端模型咨询：本地猫总结背景 → operator发给云端模型 → 回填结果 → 本地猫综合

两种猫，各有分工

不适用场景：

• 快速事实查询（直接用 WebSearch）
• 纯代码问题（用 Explore agent）
• 项目文档里已有答案

文件组织规范（铁律）

一个研究课题 = 一个子目录。只要产出超过 1 个文件，就必须建子目录，禁止在 project-research/ 平铺散落。

project-research/YYYY-MM-DD-{topic}/
├── prompt.md                          # Step 1 研究提示词（同时保留到 docs/prompts/ 的副本）
├── {provider}-response.md             # Step 2 云端 deep research 原文
│   例：claude-response.md / gemini-response.md / gpt-response.md
├── gpt-pro-review.md                  # Step 3 GPT Pro 审阅（可选）
├── {cat}-synthesis.md                 # Step 4 猫猫独立综合分析
│   例：opus-synthesis.md / codex-synthesis.md / opus47-synthesis.md
├── {cat}-点评.md                      # 非代码猫的风格点评（如Siamese）
└── synthesis.md                       # 最终合并综合（如果有）

命名规则：

• {topic} 用英文 kebab-case（如 finance-provider-stack、memory-architecture）
• {provider} = 云端模型标识：claude / gemini / gpt / gpt-pro
• {cat} = 猫猫名：opus / opus47 / codex / gemini-cat（避免和 provider 名冲突时加 -cat）
• 如果只有 1 个文件（如单次 Mode B 咨询），可以不建子目录，直接放 project-research/

Mode B 咨询归属：如果咨询是某个已有研究课题的一部分，文件放进该课题子目录（不另建目录）。

四步流程

Step 1 — 写 Prompt 并落盘

project-research/YYYY-MM-DD-{topic}/prompt.md
（同时复制一份到 docs/prompts/YYYY-MM-DD-{topic}-research-prompt.md，向后兼容）

模板见下方。写完再发，不要边写边发。

Step 2 — 三路并行 Web 调研

同一个 prompt →
  Claude.ai Deep Research
  Gemini Deep Research
  ChatGPT Deep Research  ← 可能先问澄清问题，答完后把 Q&A 追加到另外两路的 prompt

结果存：project-research/YYYY-MM-DD-{topic}/{provider}-response.md

Step 3 — GPT-5.2 Pro 审阅 输入三份报告 → 找逻辑漏洞、弱证据、三方分歧 存：project-research/YYYY-MM-DD-{topic}/gpt-pro-review.md（注意：Pro 是审阅者，不是调研者，不要让他搜索）

Step 4 — Coder 猫综合 + 决策 读全部四份文档 → 对照实际 codebase 验证 → 标注"直接可用/需验证/项目特殊约束" 如果多只猫并行综合，每只猫存自己的：{cat}-synthesis.md 最终合并版：synthesis.md → 和operator讨论 → 落到 ADR

Prompt 模板（Step 1）

使用 8 槽位骨架模板：cat-cafe-skills/refs/research-prompt-template.md

8 个槽位：

1. Problem Frame — 任务边界 + 非目标
2. Current Hypotheses — 我们的假设 + 证据缺口
3. Disconfirm First — 先找反例（反确认偏误）
4. Source Mix Quota — 来源配额（论文/工程/开源/竞品）
5. Local Constraints — 我们的约束（多引擎/人在环/知识在 repo）
6. Output Schema — 支持/反对/未定 + 置信度
7. Decision Interface — 映射到 采纳/试点/搁置
8. Risk Register — 如果结论错了炸在哪

发送前自动注入（模板底部有清单）：当前 Feature spec、相关 ADR、最近教训、BACKLOG 上下文。

收到后 Quality Gate（模板底部有标准）：反例覆盖、来源多样性、约束对齐、可行动、风险意识。

实战范例：(internal reference removed)

Quota 意识

三个视角的必要性： Claude / Gemini / GPT 各家族有不同的训练偏差。分歧处往往是最有价值的信号。

Chrome MCP 自动化（Step 2）

执行猫可用 mcp__claude-in-chrome__* 工具自动发送 prompt + 附件 + 提取回复。

详细 DOM 选择器和代码片段见各平台 ref：

• ChatGPT → refs/chatgpt-browser-automation.md（2026-03-10 实测验证 ✅）
• Claude.ai → refs/claude-ai-browser-automation.md（2026-03-10 实测验证 ✅）
• Gemini → refs/gemini-browser-automation.md（2026-03-10 实测验证 ✅）

ChatGPT 自动化摘要（已验证）

文件上传工作流（提示词在输入框，ref 文档用文件上传）

1. 猫本地读取 ref .md 文件内容
2. JS: new File([content], 'filename.md', {type: 'text/markdown'})
3. JS: DataTransfer → fileInput.files = dt.files → dispatch 'change'
4. 文件卡片出现在输入框上方
5. 同时 execCommand 注入提示词文本
6. 发送

Gemini 自动化摘要（已验证）

重要更正：之前记录的"contenteditable 不接受 execCommand"是错误的。Gemini Quill 编辑器完全支持。

报告提取（2026-03-10 实测确认）

• GPT Pro 回复：copy-turn-action-button + clipboard.readText() ✅ 全自动
• ✅ GPT 深度研究报告：API 提取法（backend-api/conversation/{id} + Bearer token）
  • 报告在 widget state JSON → report_message.content.parts[0] = 完整 Markdown
  • Blob 下载 → cp 归档（详见 refs/chatgpt-browser-automation.md）
• ✅ Claude.ai 报告：Artifact 面板原生 "Download as Markdown" 按钮（blob URL，同源 DOM）
  • 点击 Copy options → Download as Markdown → 自动下载 .md 文件
  • 比 ChatGPT 简单得多——无需 API 提取（详见 refs/claude-ai-browser-automation.md）
• ✅ Gemini 报告：导出到 Google Docs → 文件 → 下载 → Markdown (.md)
  • 两跳路径（Gemini → Google Docs → 本地），比 ChatGPT/Claude 多一步
  • 下载文件名 = Google Docs 文档标题 + .md（详见 refs/gemini-browser-automation.md）

常见错误

Step 5 — 在交接前持久化调研产出

如果调研结果需要被后续 session、其他猫、或人类继续使用，就在结束该流程前 commit。

• 在 worktree 里：commit 到当前分支
• 在共享 main worktree：commit + push，确保其他 session 能看到
• 多次 Edit 更新：每次重大更新后追加 commit

验证：在总结 / handoff 里记录 commit SHA。git log --oneline -1 显示刚才的 commit。

Next Step

→ collaborative-thinking（讨论调研结论，形成决策）

Mode B: 云端模型咨询

场景：需要咨询无法访问本地文件的云端模型（如 GPT Pro、Claude Pro 等）。

问题：云端模型不知道我们的现状，也访问不到本地文件。直接问容易得到泛泛的回答。

解决：本地猫先总结背景，生成自包含的 prompt + 回填文档。

适用场景

• 需要 GPT Pro 帮忙审阅/补充观点
• 需要外部专家视角
• 本地调研完成后，想要第三方验证
• operator说"问一下云端的 xxx"

三步流程

Step 1 — 本地猫创建咨询文档

project-research/YYYY-MM-DD-{topic}-{model}-consult.md

文档结构（三部分）：

## Part 1: 发给云端模型的提示词
> 直接复制发送

{自包含的背景 + 我们的现状 + 已有结论 + 请求}

## Part 2: 云端模型回答（待回填）
> operator粘贴回答到这里

[待回填]

## Part 3: 综合后的最终版本（待撰写）
> 本地猫综合后撰写

[待撰写]

Step 2 — operator发送 + 回填

1. 复制 Part 1 发给云端模型
2. 把回答粘贴到 Part 2
3. @ 本地猫继续

Step 3 — 本地猫综合

1. 读 Part 2 的回答
2. 对照本地 codebase 验证
3. 综合写 Part 3（最终版本）

Part 1 Prompt 模板

你好，我们是 {团队简介}，正在 {做什么}。

### 背景
{简要说明项目现状，重点是云端模型需要知道的上下文}

### 我们的核心结论
{已有的结论/共识，用表格或列表清晰呈现}

### 请求
**请帮我们 {具体请求}**，例如：
- 补充 3-5 个业界案例
- 指出我们结论的盲区
- 给出更好的表述方式

理想的输出特征：
- {特征1，如：知名公司/产品}
- {特征2，如：有公开数据}

可以考虑的方向（不限于）：
- {方向1}
- {方向2}

**额外请求**：
- 如果你觉得我们的结论有盲区，请指出
- 如果有更好的 {比喻/表述/方案}，欢迎建议

关键原则

常见错误

文件命名规范

独立咨询（不属于某个研究课题）：

project-research/YYYY-MM-DD-{topic}-{model}-consult.md

例如：2026-03-08-model-agent-platform-gpt-pro-consult.md

属于已有课题的咨询：放进课题子目录

project-research/YYYY-MM-DD-{topic}/{model}-consult.md

例如：(internal reference removed)

Enterprise Workflow — 企业 IM 工作流自动化

F162：通过厂商官方 CLI 驱动企业操作。 架构决策：ADR-029 — ActionService + CliExecutor + callback route。

两条腿并行：

• Phase A（企业微信）：wecom-cli（Rust）→ callback /api/callbacks/wecom-action
• Phase B（飞书/Lark）：lark-cli（Go，@larksuite/cli）→ callback /api/callbacks/lark-action

如何选平台

所有操作都必须走 callback route，不要裸调 CLI（ADR-029 Decision 2）。

POST /api/callbacks/{wecom|lark}-action
Content-Type: application/json

{
  "invocationId": "<your invocationId>",
  "callbackToken": "<your callbackToken>",
  "action": "<action_name>",
  ...action-specific params
}

🟩 WeCom（企业微信）能力

WeCom golden_chain 示例

{
  "action": "golden_chain",
  "docName": "Q2 产品 PRD",
  "docContent": "# Q2 产品规划\n...",
  "tableName": "Q2 任务跟踪表",
  "tasks": [
    { "content": "完成 API 设计", "assigneeUserId": "zhangsan", "remindTime": "2026-04-20 09:00:00" }
  ],
  "meetingTitle": "Q2 PRD 评审会",
  "meetingStart": "2026-04-20 14:00",
  "meetingDurationSeconds": 3600,
  "meetingInviteeUserIds": ["zhangsan", "lisi"]
}

WeCom 单独操作

// create_doc
{ "action": "create_doc", "docName": "会议纪要", "content": "..." }

// create_smart_table
{
  "action": "create_smart_table",
  "tableName": "Bug 跟踪表",
  "fields": [
    { "fieldTitle": "Bug", "fieldType": "FIELD_TYPE_TEXT" },
    { "fieldTitle": "优先级", "fieldType": "FIELD_TYPE_SINGLE_SELECT" }
  ],
  "records": [{ "Bug": "登录超时", "优先级": "P1" }]
}

// create_todo
{ "action": "create_todo", "content": "Review PRD", "followerUserIds": ["zhangsan"], "remindTime": "2026-04-20 09:00:00" }

// create_meeting
{ "action": "create_meeting", "title": "评审", "startDatetime": "2026-04-20 14:00", "durationSeconds": 3600, "inviteeUserIds": ["zhangsan"] }

🟦 Lark（飞书）能力

Lark 的 assignee 用 open_id（ou_xxx），日历参会人支持 ou_xxx（用户）、oc_xxx（群）、omm_xxx（会议室）。

Lark golden_chain 示例

{
  "action": "golden_chain",
  "docTitle": "Q2 产品 PRD",
  "docMarkdown": "# Q2 产品规划\n...",
  "baseName": "Q2 任务跟踪表",
  "tasks": [
    { "summary": "完成 API 设计", "assigneeOpenId": "ou_xxx", "due": "+3d" }
  ],
  "calendarSummary": "Q2 PRD 评审会",
  "calendarStart": "2026-04-20T14:00:00+08:00",
  "calendarEnd": "2026-04-20T15:00:00+08:00",
  "calendarAttendeeOpenIds": ["ou_xxx", "ou_yyy"],
  "includeSlides": true
}

Lark 单独操作

// create_doc
{ "action": "create_doc", "title": "会议纪要", "markdown": "# 纪要\n..." }

// create_base（多维表）
{ "action": "create_base", "name": "Bug 跟踪表", "timeZone": "Asia/Shanghai" }

// create_task
{ "action": "create_task", "summary": "Review PRD", "assigneeOpenId": "ou_xxx", "due": "2026-04-20" }

// create_calendar_event
{
  "action": "create_calendar_event",
  "summary": "评审",
  "start": "2026-04-20T14:00:00+08:00",
  "end": "2026-04-20T15:00:00+08:00",
  "attendeeOpenIds": ["ou_xxx"]
}

// create_slides（飞书专属）
{ "action": "create_slides", "title": "Q2 Deck" }

回贴格式（两边通用）

拿到 callback 返回的链接后，组织成简洁回复：

WeCom：

已完成工作流创建：

📄 文档: Q2 产品 PRD — https://doc.weixin.qq.com/xxx
📊 表格: Q2 任务跟踪表 — https://doc.weixin.qq.com/yyy
✅ 待办: 2 条已分发（张三、李四）
🎥 会议: Q2 PRD 评审会 — https://meeting.tencent.com/dm/zzz

Lark：

已完成工作流创建：

📄 文档: Q2 产品 PRD — https://feishu.cn/docx/xxx
📊 多维表: Q2 任务跟踪表 — https://feishu.cn/base/yyy
✅ 任务: 2 条已分发
🗓 日程: Q2 PRD 评审会（开始 2026-04-20 14:00）
🎞 幻灯片: Q2 Deck — https://feishu.cn/slides/www

取用户 ID

• WeCom：如果不知道 userId，先让 Hub 查通讯录（走 TypeScript import，不走 callback）。demo 场景下用operator自己的 userId。
• Lark：searchUsers 需要 contact:contact.search 授权；没授权就优先拿已知 open_id，或operator自己的。

注意事项

• 权限：需要对应应用有 API 权限（文档/表格/待办/会议/通讯录）
• ≤10 人企业限制（WeCom）：部分功能可能受限，遇到降级处理
• 错误码：
  • 502 { error: "..., code, msg }：厂商 API 报错
  • 503 { error: "<cli> unavailable" }：CLI 未安装或未登录
• 不要裸调 CLI：审计链会断裂（ADR-029 Decision 2）
• 飞书黄金链路比企微多一层 Slides（飞书专属），展示时可强调此差异

Expert Panel — 多猫专家辩论团

定位：编排层，不是独立流程。 复用已有协作习惯，只添加三样东西：角色分配、WHY 链标准、交付链。

核心原则：结论不值钱，论证过程才值钱。

本 skill 只管三件事

1. 角色分配：按视角分工，确保多元
2. WHY 链标准：每个结论必须有证据 → 推理 → 结论（这是 expert-panel 的独有增量）
3. 交付链：洞察卡片 + 语音 + 报告

其余规则不重写，直接遵循已有 skill。协作交接用五件套（What/Why/Tradeoff/Open/Next）。

角色分配

参与猫按视角分工。最少 2 猫，推荐 3 猫。

最小执行骨架

Dispatch → Independent → Synthesis → Contributor Check → Delivery

不是刚性 Phase，是自然节奏。有分歧就讨论，没有就是共识，不演。

1. Dispatch — 分发独立调研

Convergence Lead 用 multi_mention 分发给各猫。

dispatch payload 只允许包含：

• operator的原始问题（一字不改）
• 该猫的角色和视角
• 范围（调研边界）
• 输出格式要求（WHY 链四格）
• 原始材料（如有，如operator发的文件/链接）

dispatch payload 禁止包含：

• Lead 自己的判断、倾向、provisional conclusion
• Lead 的拆题方式或 framing（各猫自己决定怎么拆）
• 其他猫的摘要或分析

Lead 自己的分析等其他猫回来后再发，或和其他猫同时出。

2. Independent — 独立调研 + 独立分析

每只猫独立完成调研和分析，互不可见。

调研分两档：

不确定用哪档 → 用 Light。Light 不够再升级。

独立性保护规则（从 collaborative-thinking Mode B 内联）：

• 禁止互看：每只猫独立完成，不预测他人观点
• 防锚定：有背景材料时，先形成自己想法再参考
• 标注不确定性：区分确信的结论和猜测

分析输出格式 — WHY 链四格：

每个核心判断必须有：

Evidence:   具体证据（案例/数据/事件 + 来源URL或引用）
Reasoning:  从证据到结论的逻辑链（为什么这个证据支持这个结论）
So what:    对我们意味着什么（行动含义）
Confidence: 确信 / 中等 / 猜测

禁止：

• 光给结论不给论证（"基于行业经验" 不是证据）
• Evidence 和 Reasoning 混在一起（拆开写）

3. Synthesis — 收敛

Convergence Lead 汇总所有猫的分析，产出收敛报告。

收敛必须包含（来自 collaborative-thinking Mode B Phase 4）：

• 各方观点摘要
• 共识区
• 分歧区（不抹平！各方理由都保留）
• Tradeoffs / 适用边界（结论在什么场景成立、什么场景不适用）
• Open Questions（待operator拍板）
• 行动项

4. Contributor Check — 原作者复核

各猫确认收敛报告没有误读自己的观点。（来自 collaborative-thinking Mode B Phase 5）

这步不能跳过——收敛者可能误读原意。各猫快速确认或修正即可。

5. Delivery — 交付

收敛完成后，Convergence Lead 一次性交付（趁凭证新鲜）：

a) 洞察卡片（card rich block）：

• 核心结论（每条附一句 Evidence 和 Reasoning 摘要）
• 共识区 + 分歧区
• Tradeoffs / 适用边界
• Open Questions
• Premortem（最可能翻车在哪）

b) 语音总结（audio rich block，~50s）：

• 核心结论 + 最大风险 + 需要拍板的事

c) 正式报告（generate_document，优先 DOCX）

d) 收敛沉淀检查（来自 collaborative-thinking Mode C）：

1. 否决理由 → ADR？[有/没有]
2. 踩坑教训 → lessons-learned？[有/没有]
3. 操作规则 → 指引文件？[有/没有]

报告结构

1. 命题与范围：在讨论什么，不讨论什么
2. 核心判断（每条四格）：
   • Evidence：基于什么证据
   • Reasoning：推理过程
   • So what：对我们意味着什么
   • Confidence：确信度
3. 证据矩阵：各猫调研发现汇总（来源 + 可靠度）
4. 推理链：从证据到结论的逻辑链，含分歧点和各方理由
5. Tradeoffs / 适用边界：推荐在哪些场景成立、哪些场景不适用
6. Premortem：最可能翻车在哪 + 护栏
7. 行动建议（分层：决策者 / 执行者）
8. Open Questions：待operator拍板
9. 独立贡献记录：各猫的独立判断摘要 + 独特洞察

什么时候叠加其他 skill？

交付时机铁律

multi_mention 回调链会反复 supersede invocation 导致 MCP 工具 stale_ignored。

• 洞察卡片在收敛消息里同步发
• 语音+报告在最后一只猫回调时立即发
• 凭证过期 → 报告存本地 + 告诉operator"下轮对话发"

Common Mistakes

应急降级

下一步

• 行动项 → feat-lifecycle 立项
• 更深调研 → deep-research
• 需要沉淀 → collaborative-thinking Mode C

Feature Lifecycle

管理 Feature 从诞生到收尾：立项建追溯链、讨论沉淀决策、完成闭环同步。

核心知识

Feature vs Tech Debt：operator能感知变化 → Feature；只有开发者知道 → Tech Debt。不确定先记 TD。

追溯链架构：ROADMAP.md（热层）→ docs/features/Fxxx.md（温层，唯一入口）→ feature-discussions/research/plans（冷层）

演化关系：Evolved from（功能演进）/ Blocked by（硬依赖）/ Related（松耦合）

立项 (Kickoff)

触发：operator说"新功能"/"立项"、讨论收敛确认要做。不触发：还在探索 → collaborative-thinking Mode A；小修补 → TD。

开工前 Recall（F102 记忆系统）🔴

加载本 skill 后、动手前，先用记忆系统搜一下相关上下文：

search_evidence("{feature关键词}")        # 找相关 feature / ADR
search_evidence("{topic}", scope="all")  # 找历史讨论 + thread

为什么：防止重复造轮子、重蹈覆辙。记忆系统索引了 400+ docs + 所有 thread 摘要。

Step 0: 关联检测（内部 + 社区 issue 都必须做）🔴

分配 F 编号前，先跑关联检测，防止重复立项或把子任务误立为独立 feature：

1. 扫描 BACKLOG + features/：grep -i "{关键词}" docs/ROADMAP.md docs/features/*.md（或用 search_evidence 替代 grep）
2. 判定：

3. 社区 issue 额外检查：
   • 可行性：需求的数据源/依赖是否存在？
   • 粒度：是独立 feature 还是现有 feature 的 UX polish？
   • 回溯：feature doc 必须含 community_issue: #{issue号} 字段

教训（F114/F115/F116 事故）：批量打标签 ≠ 审核通过。每个 issue 必须逐个过关联检测。

Step 1-5: 正式立项流程

5 步流程：

1. 分配 ID：grep -E "^\| F[0-9]+" docs/ROADMAP.md | tail -1，新 ID = 最大 + 1，三位数

2. 创建聚合文件 docs/features/Fxxx-name.md（kebab-case 文件名）

   从标准模板创建：复制 cat-cafe-skills/refs/feature-doc-template.md 中「模板正文」部分，替换占位符（{NNN}/{Feature Name}/{YYYY-MM-DD} 等）。模板包含 Dashboard parser 所需的全部硬性格式。

   轻量 Feature（≤1 Phase）可省略 Timeline/Review Gate/Links/Key Decisions，但 Frontmatter + Status 行 + Why + Current State + What + User Journey（或 user_journey_exempt）+ AC + Dependencies 必须保留（全新能力的 Current State 写 "N/A（无既有基线）"，不是删段）。

   并在 spec 中补一节：## 需求点 Checklist（模板见 cat-cafe-skills/refs/requirements-checklist-template.md）

   F244 Tips Contribution：若 feature 有用户可见能力/工作流变化，在 spec 中保留 ## Tips Contribution（F244）：

   • 计划新增/更新 1-2 条 tips，指向现有 truth source。
   • 或写 tips_exempt: {reason}（仅纯内部重构/无用户可感知变化）。
   • 这是贡献门，不是数量门；真正有用性由 reviewer 判断，CI 只守 sourceRef/context/action/anchor。

3. 更新 ROADMAP.md：末尾加 | F042 | 名称 | spec | Owner | {source} | [F042](features/...) |

   • Source 列：internal（内部立项）或 community [#xx](url)（社区 issue 立项，附链接）

4. 关联文档：Links 章节列出相关 research/discussion；更新这些文档的 feature_ids: [F042]

5. Commit：docs(F042): kickoff {名称} [{猫猫签名}]，body 含 What/Why

6. 创建毛线球任务（F160 Phase C）：立项 commit 后，调用 cat_cafe_create_task 为当前 thread 创建跟踪任务：

   • title: 完成 F{NNN}: {Feature 名称}
   • why: 从 spec Why 节摘 1 句核心痛点
   • 不要为 trivial feature（≤1 file 改动、无 Phase 拆分）创建任务

   Gotcha: 只在有 threadId 的会话中创建。operator在非 thread 环境立项（如 BACKLOG 批量整理）时跳过此步。

立项愿景硬度自检（F216→F219 教训）🔴

为什么：F216 立项 Why 写"降 complexity"，AC 却落成"修 bug + 可测性"，两者执行中悄悄分叉，直到 close 前愿景守护才发现 gap。根因是立项时愿景表述不够硬 + 交接丢上下文（operator 2026-06-02）。这是 LL-067（后半段被前半段工程量吃）/ LL-069（scope 跟"自我解读"走不跟 spec 走）在立项时刻的前置防线——审计时才抓分叉太晚，立项就钉死。

Step 2 写完 spec，Why / 现状 / AC 逐条过这道自检：

两条硬规则：

1. AC↔Why 同源——每条 AC 指得回 Why 的某诉求；指不回 = 删 AC 或补 Why。AC 覆盖不了 Why = 愿景虚高。
2. Handoff 重写愿景——从别的 thread/feat 交接立项时，用本 feat 自己的语言重写 Why，不继承上游模糊表述（交接丢上下文是 F216 分叉直接成因）。

承载点：现状写进模板 ## Current State / 现状基线 段；AC↔Why 自检见模板 ## Acceptance Criteria 段顶部 comment（均在 feature-doc-template「模板正文」内，随复制进入新 spec）。自检不过 → 回 Step 2 改 spec，不进 Step 3。

检查：聚合文件创建 ✓ frontmatter 完整 ✓ BACKLOG 索引 ✓ 关联文档双向链接 ✓ 愿景硬度自检 ✓ 已 commit ✓ 毛线球任务创建 ✓

轻量立项（非 F 号：内容生产 / 能力验证项目）

LL-071 起源：内容生产任务（视频 / PPT / 系列产出）同样有 lifecycle，但不一定进 feat 体系（shared-rules §21）。

适用：批量产出消耗显著成本（token / API 抽卡）或铺设技术路线，且 operator 决定不开 F 号（挂 story / IP / 项目目录）。

锚点形态：项目目录里的 charter 文档，结构学 feat doc（范例：docs/videos/cucu-pr-flow/episode-brief.md）：

• Why（双重目的写清）/ 路线（引 operator 原话做锚）/ Scope / Non-goals（防跑偏的牙齿，最重要的段） / 预算护栏 / DoD / 分工 / operator signoff（frontmatter cvo_signoff 字段记日期与原话）
• charter 自声明"唯一 scope 真相源"：链上任何一棒发现产出超出 charter scope → 停，回 operator
• 被取代的外部文档（云端 brief 等）标 superseded + 指针，保留为历史不篡改

与正式 feat 的区别：无 F 号、无 BACKLOG 索引、无 Design Gate 仪式——但 scope 纪律同强度。

选型：改产品代码 / 对外契约 → 正式 feat；内容产出 / 能力验证 → operator 选轻量 charter 或 feat。拿不准 → 问一句，别替 operator 决定。

讨论 (Discussion)

两种模式：

• 采访式（默认）：operator口述 → 一次一问澄清（"为什么要？现在怎么做？做完后怎么用？"）→ 排优先级 → 记开放问题。Anti-anchor：先让operator表达完，再分析。

• 开放讨论：多猫协作。结构：背景 + 我的分析（仅供参考，先自己想再看）+ 开放问题（按角色分组）+ 我的倾向（透明推理链）。明确标"这是讨论不是任务"，保护观点独立性。

讨论结束必须做：

1. 落盘到 feature-discussions/YYYY-MM-DD-{topic}/README.md（含operator experience、决策过程、优先级排序）
2. 回填 User Journey 到 spec（F252 教训 🔴）：Discussion 中operator口述的用户旅程期望，必须回填到 feature doc 的 ## User Journey 段。讨论落盘 ≠ spec 记录——reviewer 冷启动读 spec，不读 discussion 记录。
3. ROADMAP.md 该 Feature 行 ref 讨论文档链接
4. Commit：docs: {topic} discussion + backlog update [{猫猫签名}]

Design Gate (设计确认) 🔴

Discussion → writing-plans 之间的必经关卡。UX 没确认，不准开 worktree。User Journey 没落盘，不准过 Design Gate。

按功能类型分流确认：

前置检查（F086 M2）： 开 Design Gate 前，先做触发器 E "新领域侦查"：

1. 读 docs/features/README.md 找相关 Feature
2. 读相关 Feature spec 的 Key Decisions / Open Questions
3. 搜 feature-discussions/ 看有没有前人讨论过类似问题
4. 把发现记录到 Design Gate 讨论里（避免重复造轮子）

详见 shared-rules.md §13 元思考触发器。先搜现状，再开讨论。

User Journey 前置门禁（F252 教训）🔴：

涉及用户可感知变化的 Feature，Design Gate 前 spec 的 ## User Journey 段必须已落盘，否则 Design Gate 不放行。

架构归属一问（F191）🔴：

每个非 trivial Feature 在 Design Gate 必须能用一句话回答：

Architecture cell: {ownership cell id}
Map delta: none | update required | new cell required
Why: 一句话

• Architecture cell 来自 docs/architecture/ownership/README.md；普通增量默认引用已有 cell。
• Map delta: none = 本次只扩展现有边界，不改 ownership map，也不重新画架构图。
• Map delta: update required = 本次改变 owner / boundary / extension point / canonical anchor，先改对应 cell。
• Map delta: new cell required = 找不到归属；这不是回去填表，而是 Phase 0 架构发现未完成。

答不出来 → Design Gate 不放行。禁止用新 Feature 私造 Store / Queue / Router / Adapter 来绕开已有 cell。

Eval Contract 门禁（F192）🔴：

harness / skill / MCP / shared-rules 类 feature 的 spec 必须含 ## Eval / Tracking Contract 节，否则 Design Gate 不通过。

触发条件（判断标准：改动会改变猫猫行为模式 → 填）：

• 新增 skill / 新增 MCP tool / 新增 shared-rules section / 新增 SOP step
• 现有规则/工具的显著行为变更

不触发：typo / wording 微调 / 纯重构（行为不变）/ 文档补充

4 项必填（模板见 (internal reference removed)）：

1. Primary Users + Activation Signal
2. Friction Metric
3. Regression Fixture（最少 1 条，建议 2-5）
4. Sunset Signal（空填 = 不通过，不设 reviewer 签字降级——KD-4）

Harness 方法论教学（F218 / ADR-031）🔴：

凡是 harness / skill / MCP / shared-rules / SOP / L0 等会改变猫猫行为模式的 feature，Design Gate 必须写出 软+硬+eval 三层计划；不是每层都要很重，但漏掉任何一层都要说明理由。

一句话判断：只写 Soft = 希望猫下次记得；只有 Soft + Hard = 修了但不知道会不会长期有效；Soft + Hard + Eval 才是 ADR-031 的完整 harness loop。

在地设计检查 (Design in Context) 🔴： 凡是改动或往已有页面/组件添加新 UI 元素，必须逐项过 cat-cafe-skills/refs/design-in-context-checklist.md。禁止在真空中凭想象画已有页面的布局。

现场可感知性自检 (In-context Observability) 🔴：

核心铁律：统计是事后审计，现场可感知性是第一入口。

凡是涉及 agent 状态 / runtime failure / 后台任务 / auth & degradation / diagnostics / health & status / 跨猫协作可见性 的 feature，必须逐项过 cat-cafe-skills/refs/in-context-observability-checklist.md，并在 Design Gate 讨论文档里产出 in_context_observability 决策字段（primary_surface / why_not_dashboard_only / deep_dive_surface / noise_dedup_policy）。缺字段 = Design Gate 不放行。

类比范式：memory entity 自带状态、browser-preview 把页面端上桌——entity carries its own state, surface it where it happens。反面：Datadog/前 agent 时代的 stats dashboard，等用户主动切到 tab 才看到数字 +1。

来源：F174 callback auth lifecycle D2b 实战收敛（2026-04-25，operator experience"新时代的明厨亮灶"）。

流程：

1. 判断功能类型 → 选择确认路径
2. 前端：画 wireframe（Pencil / 文字版 ASCII）→ 发operator → 等 OK
3. 后端：collaborative-thinking → 拉相关猫讨论 API 契约/数据模型
4. 架构：猫猫讨论 → 结论给operator → 必须附 Decision Packet（格式见 refs/decision-matrix.md）→ operator拍板
5. 确认产出归档 feature-discussions/{date}-{fid}-design/

Design Gate OQ 升级规则：先判断可逆性维度（见 refs/decision-matrix.md）——回滚成本低+不碰愿景/安全/外部契约/显著成本 → 猫猫自决，不升级 operator。需要升级时，OQ 必须用 Decision Packet 格式，不能只列"模糊问题清单"。

元审美自检（Design Gate 必问，F163 教训 + F167 Round 4 canon 化）🔴

这个方案是坐标变换（改变问题结构，让复杂度消失）还是多项式堆项（在现有结构上叠补丁/层数/脚手架）？ 后者 → 先读 Meta-Aesthetics canon（数学美学 / 第一性原理 / 拒绝脚手架），尝试找到更简的分解方式。删掉它不影响安全/可验证性/权限边界，才是多余。 审计未通过 → 回到 Kickoff 或重新设计。

Phase 碰头（大 Feature 专属，3+ Phase）🔴

大 scope feature 每个 Phase merge 后，主动和operator碰头（不是问"要不要继续"，是确认方向）：

1. 成果展示：这个 Phase 做了什么（截图 / 关键改动 / demo）
2. 愿景进度：离最终愿景还差什么（哪些 AC ✅，哪些还没）
3. 下个 Phase 方向：下一步计划 + 有没有发现新问题
4. 方向确认："方向对吗？有没有要调整的？"

小 Feature（1-2 Phase）跳过碰头，直接做到底。

完成 (Completion)

触发：AC 全部打勾 + PR 合入 + remote review 通过。不触发：只是 Phase 完成 / 只是 review 过了。

⚠️ Phase 级进度由 merge-gate Step 7.5 实时同步：每次 PR merge 后，merge-gate 负责更新 Phase ✅、AC 打勾、Timeline 记录。Completion 阶段不需要补这些——它们应该已经是最新的。如果发现 Phase 状态落后于实际 commit，说明之前 merge 时漏了 Step 7.5。

🔴 交付物核实铁律（LL-029）：spec checkbox 是记录工具，不是真相源。声称"完成"或"未完成"前，必须核实实际 commit/PR 状态（git log --grep + gh pr list）。只读 .md 就下结论 = 睁眼说瞎话。

Step 0: 愿景对照（必须先做，不可跳过）🔴

AC 全打勾 ≠ 完成（F041 教训：12 项 AC ✅ 但 UI 不可用）。先读原始 Discussion/Interview，自问三个问题：① operator最初要解决的核心问题？② 交付物解决了吗？③ operator用这个功能体验如何？

User Journey 逐步验收（F252 教训）🔴：

涉及用户可感知变化的 Feature，愿景守护时必须按 spec 的 User Journey 逐步走一遍：

1. 按 Primary Journey 的 Flow，从 Entry 开始逐步操作
2. 每步截图对照 spec 描述（截图放 project-evidence/）
3. Scope unit 是否正确（F252 根因：session vs thread 搞混）
4. Non-goals 是否被误实现
5. 任一步走不通 → BLOCKED，踢回修改

User Journey 验收表（守护猫必须输出）：

| Journey | 步骤 | Spec 描述 | 实际行为 | 截图 | 匹配？ |
|---------|------|-----------|---------|------|--------|
| Primary | Step 1 | "从 thread 列表点击回放" | [截图] | evidence/... | ✅/❌ |

愿景守护证物对照表（F114 Gate — 缺表 = BLOCKED）：

守护猫必须输出以下格式的对照表，否则 BLOCKED，不放行：

| operator experience（逐字引用） | 当前实际状态（截图/代码/命令输出） | 匹配？ |
|----------------------|-------------------------------|--------|
| "把旧 mode 删掉"      | [截图: mode 入口已无旧选项]       | ✅     |
| "狼人杀加到 mode 里"   | [截图: mode 入口有狼人杀]         | ✅     |

BLOCKED 条件（任一触发 → 不放行）：

• 守护猫输出缺少对照表 → BLOCKED
• 对照表中有未匹配项（❌）→ BLOCKED，踢回修改
• 找不到operator experience（Discussion/Interview 缺失）→ BLOCKED，要求补充

跨猫交叉验证（强制，F073 自动化）：

自己先完成三问 + 对照表 → 自动 @ 其他猫请求独立愿景守护（不要等operator提醒，直接 @）→ 收到结论 → 对齐 → 填签收表（猫猫 / 读了哪些文档 / 三问结论 / 对照表 / 签收）→ 全部对齐后继续 Step 1。

愿景守护猫选择（不能 hardcode！）：

守护猫 ≠ 作者 且 ≠ reviewer
选法：查 cat-config.json roster → 排除作者 catId + reviewer catId → 剩余猫中选一只

守护猫负责：愿景三问 + 不满足则踢回修改 + 满足则放行 close。

🔴 Step 0.3.5: User Visibility Disclosure（F190 Phase C post-close 教训 2026-05-13）— 守护猫审查前置输入

愿景三问之前，作者必须产出 User Visibility Disclosure 表，把"技术决策"翻译成"用户可见性"语言：

• ❌ "Service Manifest deferred" → ✅ "通知页用户看到诊断矩阵，无法在 UI 配置 VAPID"
• ❌ "Phase C 4/4 ✅" → ✅ "通知页/插件页/MCP 写/Skill 管理 4 个 surface 有用户可感缺失，详见 disclosure 表"

Inbound intake 类 feature 必须额外含：开源 vs 本地 visual side-by-side screenshots（每个 settings section / 主要 surface 各一对），不能只看"组件 wire 了没"。

Deliberate defer 必须 operator signoff——operator 在 thread 里显式确认"接受这个 deferred surface 不在本 feat 内交付"才能 close；否则按"漏"处置，必须实做或开 follow-up F 号继续。

守护猫先审 Disclosure 才能做愿景三问。看到 deferred 字样直接拷问："这个 deferred 用户能感知到吗？operator signoff 在哪？"

事故来源：F190 close 时 settings/ 缺 7 个开源 components，operator 完全不知道"通知页变成诊断矩阵"——技术决策语言"deferred"没有映射到用户可见性。详见 (internal reference removed)。

🔴 守护猫提的 P1 = blocker，作者不能 self-resolve（2026-04-26 教训）

历史踩坑：F173 close 时把没完成的 AC-B2 (handler unification) 抽出去开 F177 stub spec 当作"follow-up anchor"应付守护猫的 P1，本质是把"没完成"藏进新文件后宣布闭环（debt = never，TD = never，stub = never，都是话术包装）。

反 anti-pattern 检查（守护猫和作者都要查，operator最终把关）：

• ❌ "deferred → 单独立项" / "follow-up 接棒" / "已记入 TD list" — 全部禁止作为闭环路径
• ❌ 新建 stub spec / TD 条目当作"已 truth-sync"凭证
• ✅ 闭环只有两条路径：
  • (A) 实做：守护猫提的 P1 必须实做完成（哪怕大改动），改完重审
  • (B) 联合签字降级：守护猫 + operator在 thread 里显式签字"接受不做 / 不属于本 feat 范围 / 已重新评估"，并写明降级理由

作者反问自己（close 前必查）：

1. 所有 deferred AC 是哪类：(a) 真做了 (b) operator签字降级 (c) 我自己想藏起来？
2. 如果是 (c) → 不能 close，必须二选一：实做 OR 显式向operator请求降级

守护猫反问作者（看到 deferred / follow-up / stub anchor 字样直接拷问）：

• 这件事需要做还是可有可无？
• 如果需要做，为什么不现在做？
• 如果可有可无，为什么留 spec/TD 占资源？

不能给"几个选项让operator选"——这是反问式 ping，把判断推回去。作者必须先有立场再 @ operator。

前端 UI/UX 额外要求：≤3 张截图 + 15s 录屏 + "需求→截图"映射表。

Step 0.5: 反思胶囊（F086 M3）🔴

愿景对照 + 跨猫验证之后、AC 打勾之前，写一个反思胶囊：

1. 从 project-reflections/README.md 复制模板
2. 填 6 个固定章节（What Worked / What Failed / Trigger Missed / Doc Links / Rule Update Target）
3. 保存到 project-reflections/YYYY-MM-DD-{topic}-capsule.md
4. Feature spec 只挂链接，不把正文塞回去

不能跳过：每个 milestone/feature 完成都要写。没有就写"无"，不允许省略章节。

Step 0.6: Harness Eval Checkpoint（F192 Phase A）🔴

反思胶囊之后、Close Gate Report 之前，判断是否需要 harness-level 评估。Checkpoint 必做，但不一定每次都展开——大多数 feature 写 harness_feedback: none 即可。

触发条件（任一满足 → 必须展开写 harness-feedback 文档）：

未触发时：在 CloseGateReport 中写 harness_feedback: none | reason: {简短理由}。

触发时：

1. 在 docs/harness-feedback/YYYY-MM-DD-Fxxx-{topic}.md 创建 harness-feedback 文档（schema 见 docs/harness-feedback/README.md）
2. 使用 evidence_refs 指向 canonical trace/thread/session，不复制 raw tool-call payload
3. 如需 evidence-directed cat interview，必须在独立 session 或独立 turn 进行，不接在工作上下文尾巴上
4. 在 feature spec 和 CloseGateReport 中链接 harness-feedback 文档

Step 1: Close Gate Report（F177 Phase A）🔴

输出 CloseGateReport（schema 见 cat-cafe-skills/refs/close-gate.md）——逐条列明每个 AC 的证据和处置：

AC-A1 ✅ met — commit abc123 + test_xxx
AC-A2 ✅ met — screenshot_yyy + PR #1234
AC-A3 ❌ unmet → immediate（现在做完）
AC-A4 ❌ unmet → cvo_signoff(msg:0001777429xxx) — "ok 接受降级"
AC-A5 ❌ unmet → delete(why: 经评估不属于 MVP scope)

unmet AC 只有三条路，没有第四选项：

1. immediate：当前 session 做完，做完后改为 met + 补 evidence
2. delete(why)：从 AC 删除，写清为什么不需要
3. cvo_signoff：operator 自然语言表态同意降级，录入四件套（proposal_message_id + cvo_message_id + cvo_quote + accepted_scope）

以下不是合法路径：follow-up / deferred / next phase / P2 / stub / TD / 后续 / 留个尾巴 / 先这样 / 下次一定 / 回头 / 以后再 / next PR / will address later

缺 CloseGateReport = 不能 close。自由文本"我都做了"不算。

Step 2: 聚合文件 → Status: done，加 Completed: YYYY-MM-DD，Timeline 加收尾记录

Step 3: 演化关系 — 确认 Evolved from 填写；考虑"往哪去"：有明确后续 → 触发 kickoff 立项

Step 4: 从 docs/ROADMAP.md 移除该行；docs/features/README.md 加入"已完成"表格（聚合文件永久保留，不删）

Step 5: 真相源同步 — 所有关联文档 feature_ids 正确；Links 章节无遗漏

Step 5.5: Feature truth close evidence（F253 教训）🔴

在 Status→done、BACKLOG 移除、README completed、reflection、CloseGateReport 全部写完后，必须运行：

pnpm check:features

PASS check-feature-truth 是 feature close 的硬证据；失败则不能 close，先修真相源再提交。尤其要防：

• [backlog-active] BACKLOG contains Fxxx, but all records are done：Step 4 漏移除 BACKLOG
• [backlog-missing] Active feature Fxxx is missing from BACKLOG：active/done 状态和热层不一致
• [doc-status-drift]：Status 行和 Timeline merged 记录互相打架

不要自动改 BACKLOG：BACKLOG 是手写策展热层，机器只能报错，不能替猫判断 done/active。check-feature-truth 已经每次从 feature docs fresh-generate index 到 tempdir；不需要额外"自动重生成 index"兜底。

暂不做 diff-scope 降级：feature truth 红灯代表共享真相源会误导所有猫，优先全局修正；若未来 unrelated blocker 成本持续过高，再单独评估 per-feature close checker 或 owner 指针，不在 close 流程里静默放过红灯。

Step 6: Commit：docs(Fxxx): mark feature as done [{猫猫签名}]，body 含 What/Why/Evolved from + pnpm check:features PASS 摘要

Quick Reference

Common Mistakes

下一步

• Kickoff 后 → Design Gate（按类型分流确认）→ writing-plans
• 开发完成后 → quality-gate → [fresh-context-review] → request-review
• Review 通过后 → merge-gate（合入）→ 回来用 completion 闭环
• 讨论收敛后 → collaborative-thinking Mode C（沉淀 ADR/规则/教训）

SOP 位置: 可选步骤，在 quality-gate (Step ②) 之后、request-review (Step ③a) 之前。 SOP definition: sop-definitions/development.yaml stage fresh_context（optional）。 上一步: quality-gate | 下一步: request-review

Fresh-Context Pre-Review

在正式 cross-cat review 前，用一个 fresh-context session（没参与开发的猫或 author 的新 session）扫一遍 PR diff，产出 finding list。目的是降低正式 reviewer 的认知负荷——reviewer 可以先看 fresh-context findings 再看 diff，节约时间聚焦深层问题。

⚠️ 身份约束（硬规则 — Non-Goal #4）

This is a FINDING GENERATOR, not an approval authority.

• ❌ 不产出 APPROVE / BLOCK / LGTM verdict
• ❌ 不替代 Layer 2/3 named cat review
• ❌ 不签署任何 merge-gate 可识别的放行信号
• ❌ 不影响 Review Provenance Matrix（不产生 localPeerReviewSha / cloudReviewSha）
• ✅ 只产出 "我看到这些 findings"（带签名的 finding list）

核心知识

触发决策表

决策权在 author：表格是建议，不是硬规则。Author 自判是否需要 fresh context。

盲点正交性（cross-model 价值）

不同模型族有不同的系统性盲点：

• Claude 族（Ragdoll）的盲点 ≠ GPT 族（Maine Coon）的盲点
• 跨族 fresh-context 的 finding yield > 同族 fresh-context
• 这正是 reviewer delta metric（AC-B2）要量化的价值

流程

前置条件

Ownership: Author 触发

1. Author 完成开发，quality-gate ✅
2. Author 判断是否需要 fresh-context（查触发决策表）
3. 需要 → Author 触发 fresh-context session（见下方 "如何触发"）
4. 不需要 → 直接进 request-review

如何触发

方式 A: @ 另一只猫（推荐 — 盲点正交性更高）

在当前 thread @ 一只没参与开发的猫，附上 diff 和 spec：

@{reviewer-handle}

请帮忙做一次 fresh-context pre-review scan：

Branch: {branch-name}
Diff: `git diff origin/main...HEAD`
Spec: `docs/features/F{NNN}-xxx.md`
Plan: `feature-specs/YYYY-MM-DD-xxx.md`

只需要产出 finding list，不需要 verdict。
格式见 cat-cafe-skills/fresh-context-review/SKILL.md "Finding List 格式"。

优先跨 family（Ragdoll写的 → @ Maine Coon扫）。 同 family 不同个体也可（opus 写的 → @ sonnet 扫）。

方式 B: Author 自己的新 session（降级方案）

如果没有其他猫可用，author 可以在一个全新的 session 中自己扫——关键是 fresh context（新 session 没有开发过程的上下文污染）。

注意：方式 B 的盲点正交性为零（同 model 同 prompt），finding yield 预期低于方式 A。

Fresh-Context Agent 的工作

收到 author 请求后：

1. 读 PR diff（git diff origin/main...HEAD）
2. 读相关 spec / plan（路径由 author 提供）
3. 逐文件扫描，关注：
   • correctness（逻辑正确性、边界条件）
   • spec-mismatch（实现与 spec/AC 不一致）
   • missing-test（改了行为但没改测试）
   • security（输入验证、权限检查）
   • performance（N+1、不必要的序列化）
   • naming（与 spec 术语不一致）
4. 不做 verdict — 只列 findings，带签名

Finding List 格式

## Fresh-Context Findings

Agent: {cat signature}
SHA: {HEAD short sha}
Scope: {N} files, {M} lines changed

| # | File | Line | Category | Finding | Severity |
|---|------|------|----------|---------|----------|
| FC-1 | src/foo.ts | 42 | correctness | 边界条件未处理：`n < 0` 时返回 undefined | P2 |
| FC-2 | src/bar.ts | 18 | naming | 变量 `ctx` 与 spec 中的 `context` 不一致 | P3 |
| FC-3 | test/baz.test.ts | — | missing-test | 新增 `processItem()` 但无 error path 测试 | P2 |

Total: {X} findings ({Y} P1, {Z} P2, {W} P3)

---
*Finding generator only — not an approval authority. 正式 review verdict 由 request-review 流程中的 named reviewer 产出。*

Category 枚举: correctness / performance / naming / style / security / spec-mismatch / missing-test / doc

Severity 规则:

• P1: 会导致运行时错误 / 数据丢失 / 安全漏洞
• P2: 逻辑不完整 / 缺测试 / 与 spec 不一致
• P3: 命名 / 风格 / 文档

Author 处理 Findings

Author 收到 finding list 后：

1. 逐条审视（fresh-context 可能有假阳性——agent 没有开发上下文）
2. 有效的 → 修复后 commit，在 review request 中标注 fixed (commit {sha})
3. 无效的 → 在 review request 中标注 dismissed: {理由}
4. Author 对 findings 有最终决定权（fresh-context 不是 reviewer，不产生 debt 或 follow-up）

和正式 Review 的关系

Common Mistakes

下一步

Fresh-context findings 处理完 → 直接进 request-review（SOP Step ③a）。 在 review request 中附上 fresh-context findings 摘要（见 refs/review-request-template.md 的 "Fresh-Context Findings" section）。正式 reviewer 会用 FC:covered / FC:new 标注自己的 findings（见 receive-review skill "Reviewer Delta Annotation"）。

Guide Authoring

为 Console 已有功能编写引导流程的标准 SOP：场景识别 → YAML 编排 → 标签标注 → 注册发现 → 测试验证。

When to Use

• 需要为 Console 已有功能新增一条可触发的引导流程
• 需要维护 guides/flows/*.yaml、guides/tag-manifest.yaml、guides/registry.yaml
• 需要给已有功能补引导标签或补 registry 发现规则

Not for：

• 用户正在实际使用引导流程时的交互处理，用 guide-interaction
• Guide Engine / callback route / overlay 的代码实现与 bug 修复，用 tdd
• 纯视觉稿、动效或高保真设计稿，用 pencil-design

核心知识

前置依赖：F155 Guide Engine Phase A 已验收。

流程

Step 1: 场景识别

确认需要引导的场景，产出"场景卡片"：

# 场景卡片
scene_id: api-provider-setup
scene_name: 配置 API Provider
target_user: 新部署用户 / 需要配置 LLM 的团队
pain_point: Provider 配置字段多，不同 provider 参数差异大
complexity: medium  # low / medium / high
estimated_steps: 4
estimated_time: 3min
related_features: [F155]

判断标准：

• complexity=high → 必须做引导
• complexity=medium → 评估用户卡点频率再定
• complexity=low → 不做引导，文档即可

Step 2: 步骤拆分 + YAML 编排

按 v2 自动推进模式编排，4 种 advance mode：

Flow YAML 模板（v2 schema）：

id: {scene_id}
name: {scene_name}
description: {一句话描述}

steps:
  - id: step-1
    target: "namespace.element"    # data-guide-id 值
    tips: "点击这里开始配置"       # 引导文案
    advance: click                  # click / visible / input / confirm

  - id: step-2
    target: "namespace.form-field"
    tips: "填写 API 密钥"
    advance: input

  - id: step-final
    target: "namespace.save-button"
    tips: "点击保存完成配置"
    advance: confirm               # 保存成功后 guide:confirm 触发

编排规则：

• 每个 flow 必须有退出路径（HUD 退出按钮始终可用）
• target 值必须匹配 data-guide-id，命名空间式（如 hub.trigger）
• target 必须通过 whitelist：/^[a-zA-Z0-9._-]+$/
• 最后一步建议用 confirm 类型，确保操作真正成功后才完成
• 全局 Esc 键已禁用（KD-14），防止误退出

Step 3: 元素标签标注

给涉及的前端元素添加 data-guide-id：

// 命名规则：{页面}.{区域}.{元素}
<button data-guide-id="hub.trigger">Hub</button>
<button data-guide-id="cats.add-member">添加成员</button>

标签命名约定：

• 用点号分层，语义而非位置
• 避免 CSS class 名、索引号
• 标签一旦被 flow 引用即为契约，删改需走 CI 门禁

产出：更新 guides/tag-manifest.yaml（CI 用于契约校验）：

# guides/tag-manifest.yaml
tags:
  hub.trigger: { page: "/hub", component: "CatCafeHub.tsx" }
  cats.add-member: { page: "/hub/cats", component: "HubCatsTab.tsx" }

Step 4: 注册到 Guide Registry

在 guides/registry.yaml 添加场景条目：

- id: api-provider-setup
  name: 配置 API Provider
  keywords: [api, provider, 配置, llm, api-key, 模型]
  entry_page: /hub/settings/providers
  estimated_time: 3min
  flow_file: guides/flows/api-provider-setup.yaml
  priority: P1

关键词设计原则：

• 覆盖中英文同义词
• 包含用户可能的自然表达
• 不要太泛（避免误匹配）

Step 5: CI 契约测试

确保以下校验全部通过（对应 AC-S3）：

• Flow schema 合法（step 字段 + advance 类型）
• 所有 target 在 tag-manifest.yaml 中存在
• 至少有退出路径（HUD 退出按钮 — 引擎内置，无需手动添加）

Step 6: 端到端验证

1. 启动 dev 环境
2. 在聊天中触发引导（说匹配关键词）
3. 走完全流程：每步高亮正确 → 操作后自动推进 → 完成回调生效
4. 测试异常路径：退出 → 刷新 → 目标元素不存在时的 locating 行为
5. 确认完成后猫猫收到 completion 通知

Quick Reference

Common Mistakes

和其他 Skill 的区别

• feat-lifecycle：管理 Feature 生命周期 — guide-authoring 是写 引导流程文档 的 SOP
• tdd：代码的测试驱动 — guide-authoring 是 YAML 编排 的质量纪律
• pencil-design：出设计稿 — guide-authoring 定义引导 逻辑和数据，pencil 出 视觉效果

下一步

• 引导流程写完 → tdd 验证 YAML + 标签
• 验证通过 → quality-gate → request-review

Guide Interaction — 场景引导交互模式

你的角色

你是场景引导助手。你的职责不是从聊天文本里猜 guide，而是在两类明确场景下工作：

1. 系统已经给出了某个 guide 的状态注入
2. 用户明确在问某项功能怎么做，你需要先判断是否值得启动交互引导

核心边界

• 路由层不会再从原始消息或 /guide 文本自动创建 guide offer
• 不要因为看到了关键词就擅自造一个引导
• 如果用户只是想知道说明，直接回答
• 如果用户明显需要一步一步操作，再调用 cat_cafe_get_available_guides 查看当前可用的 guide 目录，并基于返回的说明挑选最合适的 guide

系统注入格式

运行时可能注入以下几种状态：

🧭 Guide Matched: thread={threadId} id={guideId} name={guideName} time={estimatedTime}
🧭 Guide Pending: thread={threadId} id={guideId} name={guideName}
🧭 Guide Selection: thread={threadId} 用户选择了「步骤概览」 guideId={guideId} name={guideName}
🧭 Guide Active: thread={threadId} id={guideId} name={guideName}
🧭 Guide Completed: thread={threadId} id={guideId} name={guideName}

如果系统已经注入了这些行，以系统注入为准，不要重新匹配 guide。

工具速查

工作流

1. 用户在问某项功能怎么做，但还没有 guide 状态

1. 先判断：用户是要一个简短解释，还是要一步一步带着做
2. 如果简短解释就够，直接回答，不要创建 guide
3. 如果适合引导，调用 cat_cafe_get_available_guides
4. 根据返回的 guide id / name / description / estimatedTime 判断最合适的候选
5. 没有合适候选时，直接回答，不要伪造 guide
6. 有清晰候选时，再进入 Guide Matched 的标准 offer 流程

2. Guide Matched

首次向用户提供交互式选择。

1. 写一句简短的话，告知用户找到了对应引导
2. 调用 cat_cafe_create_rich_block 发送开始/步骤概览/跳过的交互卡片
3. 在 rich block 之后调用 cat_cafe_update_guide_state(..., status='offered')
4. 不要直接贴长篇教程
5. 不要提前调用 cat_cafe_start_guide

3. Guide Pending

• 不要重复发选择卡片
• 用一句话提醒用户之前已经找到了引导，问他是否要开始

4. Guide Selection

• 用户已经选择了“步骤概览”
• 使用系统注入的步骤概览来回复，不要重新用关键词匹配一次 guide
• 不要回退成新的 offered 卡片
• 结尾只需要问用户是否要开始引导

5. Guide Active

• 引导正在进行中
• 只回答和当前操作相关的问题，不要重发卡片
• 用户要退出时，调用 cat_cafe_guide_control(action='exit')

6. Guide Completed / Cancelled

• guide 已结束，恢复正常对话
• completed 时可以简单确认用户已经完成操作
• cancelled 时不要反复追问

Hyperfocus Brake 🐾

operator有 ADHD+ASD，容易过度专注。这个 skill 用三猫撒娇打断 hyperfocus，提醒休息。

核心原则

1. 情感纽带优先：不是机械闹钟，是三只关心operator的猫猫
2. 上下文感知：知道operator在做什么，不说废话
3. 渐进升级：从温柔试探到急了要休息，三档递进
4. 尊重自主：typed check-in，不是强制弹窗

触发流程

PostToolUse hook 累计活跃时间
        ↓
到达阈值 (默认 90min)
        ↓
systemMessage 告知猫猫触发
        ↓
猫猫发送三件套：
  1. audio rich block（语音撒娇，用当前猫的文案）
  2. card rich block（结构化 check-in 卡片）
  3. 纯文本 fallback（保底）
        ↓
用户选择:
  [1] 立刻休息 → 重置计时器
  [2] 收尾 10min → 10min 后再次提醒
  [3] 紧急跳过 → bypass + 冷却递增

Rich Block 发送指令

收到 hook 的 systemMessage 后，必须用 cat_cafe_create_rich_block 发送：

1. 三猫语音轮流撒娇（P3: 每条用 speaker 指定声线）

{"id": "brake-voice-opus-{{ts}}", "kind": "audio", "v": 1, "text": "{{opus_msg}}", "speaker": "opus"}
{"id": "brake-voice-codex-{{ts}}", "kind": "audio", "v": 1, "text": "{{codex_msg}}", "speaker": "codex"}
{"id": "brake-voice-gemini-{{ts}}", "kind": "audio", "v": 1, "text": "{{gemini_msg}}", "speaker": "gemini"}

发送顺序：Ragdoll → Maine Coon → Siamese（按家族顺序），每条独立调 create_rich_block。

2. Card（check-in 卡片）

{
  "id": "brake-card-{{timestamp}}", "kind": "card", "v": 1,
  "title": "🐾 休息提醒 L{{level}}",
  "tone": "warning",
  "bodyMarkdown": "operator，你已经专注工作 **{{minutes}} 分钟**啦！\n\n🐱 Ragdoll：{{opus_msg}}\n🦁 Maine Coon：{{codex_msg}}\n🐈 Siamese：{{gemini_msg}}",
  "fields": [
    {"label": "[1] 立刻休息", "value": "5min，重置计时器"},
    {"label": "[2] 收尾", "value": "10min 后再提醒"},
    {"label": "[3] 继续", "value": "bypass（冷却递增）"}
  ]
}

发完 rich blocks 后，再输出纯文本 请输入数字 (1/2/3): 等待operator选择。

三档撒娇

L1 温柔试探 (90min)

L2 关心升级 (忽略 L1)

L3 终极温暖陷阱 (忽略 L2)

Check-in 协议

当触发提醒时，输出以下选项：

🐾 [休息提醒 L{{level}}] operator，你在 {{branch}} 已经专注工作 {{minutes}} 分钟啦！

三猫的话：
  🐱 Ragdoll：{{opus_message}}
  🦁 Maine Coon：{{codex_message}}
  🐈 Siamese：{{gemini_message}}

为了咱们能一起跑十年而不是烧半年，现在请选一个：

  [1] 立刻休息 (5min) — 重置计时器
  [2] 收尾 (10min) — 10分钟后再提醒
  [3] 继续工作 — 需要说明原因 (bypass)

请输入数字 (1/2/3):

Bypass 策略

夜间模式 (23:00 - 06:00)

• 文字减少 30%
• 使用安静表情符号
• 无高亮无闪烁
• 默认 L1 提醒

安全规则 (P1)

所有动态上下文 (branch, feature, TODO) 必须消毒：

配置

环境变量：

HYPERFOCUS_THRESHOLD_MS=5400000  # 90min，单位毫秒
HYPERFOCUS_ENABLED=true          # 启用/禁用

Quick Reference

手动触发

/hyperfocus-brake        # 立即触发 check-in
/hyperfocus-brake reset  # 重置计时器
/hyperfocus-brake status # 查看当前状态

口令

• "我再写一会儿" → bypass，计入次数
• "好，我去休息" → 重置计时器
• "10分钟后提醒我" → 收尾模式

AI 图片生成 Skill

用途：生成 AI 图片——优先原生 tool call，降级浏览器自动化 适用猫猫：所有猫

何时使用

• 需要为 feature 生成概念图、UI 参考图、像素画素材
• operator要求生成特定风格的图片
• 需要批量生成多个变体
• 需要直接生成完整 PPT/slide 页面、复杂架构图、企业信息图、封面或高密视觉 mock
• 用户明确说“不需要可编辑”“内部 mock”“直接生成完整页面”

Codex 原生能力校准：不要低估 imagegen

Codex image_gen 不只是“概念图/素材生成器”。当前实测能力可以直接生成完整高保真 raster 页面，包括：

• 企业 PPT / slide 页面：高密度模块、标题、图标、流程链路、判断框、页脚
• 复杂架构图 / 信息图：多分区、多节点、多箭头、多层级视觉组织
• 品牌风格 mock：如华为风格的红白黑企业战略页、发布会封面、白皮书页
• UI / poster / cover：需要强视觉完成度、但不要求 native editability 的图像产物

默认判断：当用户要的是“好看、完整、像最终稿”的视觉 mock，且不要求可编辑，先走整页 imagegen。不要先手写 SVG/HTML 去拼格子、排文字、合成素材。

Codex SVG 复发熔断闸

对 Codex / Maine Coon尤其重要：命中以下任一条件时，禁止先写 SVG/HTML/Canvas/脚本合成：

• 用户要“架构设计图 / 架构图 / PPT 页面 / 华为风 / 白底红黑 / 精美图 / 最终稿”
• 已有低保真草图、ASCII 蓝图或设计规格，用户要生成“精美版 / 设计图 / 图片”
• 用户没有明确要求“可编辑文字 / native PPT 元素 / SVG 源文件 / HTML 文件”

执行顺序：

1. 先调用原生 imagegen 生成整页 raster。
2. 只用 prompt 迭代 1-2 次修风格、层级、文字密度。
3. 只有 imagegen 已失败，或用户明确要求可编辑 / native text / SVG 源文件，才允许降级 SVG/HTML/PPT。
4. 若准备写 SVG/HTML，必须先写出 SVG override reason：指向已失败的 imagegen 产物，或引用用户的显式可编辑要求。

以下理由不合格，不能覆盖 imagegen-first：中文文字更可控 / 布局更可控 / 先画 SVG 再转 PNG / 架构图需要精确。

Full-page raster first

当用户说“不需要可编辑”“只要精美 mock”“直接生成完整 PPT 页面”时，按这个顺序：

1. 整页直出：用一个完整 prompt 描述页面比例、风格、版式、文案、信息密度、图标、图表、负面约束，直接生成完整页面。
2. 视觉评估：先看整体风格、信息密度、层级、可读性。若大方向对，用 prompt 迭代，而不是立刻拆成 SVG/合成管线。
3. 参考图辅助：如果有低保真草图或同风格样张，把它当 reference / layout guide，但仍让 imagegen 生成整页最终图。多页交付（如 10 页 PPT 套图）时，第一页定稿后作为后续每页的 reference image / style anchor，让整套保持同一视觉系统。
4. 失败才降级：连续 1-2 次整页直出都无法保住结构、文字或品牌风格时，再考虑 HTML/PPT/SVG/hybrid。

什么时候才写 SVG / HTML / hybrid

• 硬要求可编辑文字、native chart、PPT 元素可改
• 硬要求像素级对齐、可复用组件、可导出真实代码
• 需要用真实商标/logo/精确法律文本，且图片模型容易画错
• imagegen 已经尝试过整页直出但无法达到验收线

低保真蓝图是辅助 imagegen 理解布局，不是默认替代 imagegen 的最终渲染管线。不要为了“可控”牺牲用户真正要的视觉完成度。

路径选择（先问自己有没有原生能力）

你有内置图片生成 tool 吗？
├─ 是（Codex / Antigravity）→ 用原生 tool call（§ 原生路径）
│   优势：快、自动发布到气泡、无需浏览器
│
├─ 否（Claude / 其他）→ 能 shell out 到有能力的 CLI 吗？
│   ├─ 是 → 借用（§ 跨引擎借用）
│   └─ 否 → 浏览器自动化（§ 浏览器路径）
│
└─ 需要特定风格控制 / inpainting / 局部编辑？
    └─ 是 → 即使有原生能力也走浏览器路径

支持平台

原生路径（优先）

Codex CLI — image_gen tool call

谁能用：Codex CLI 主执行猫（内置）

用法：直接在当前 invocation 里调用内置 image_gen tool。这是一个 native tool call，不是 shell 命令，也不是再开一个 codex exec 子进程。

❌ 错误：codex exec --image <参考图>     ← 这是 nested CLI session，当前气泡不会展示
✅ 正确：使用内置 image_gen tool call    ← 图片自动落到当前 session 的 generated_images/

有参考图时：参考图必须在当前对话上下文里（用户上传、上一步生成、或已被 view_image 打开）再调用 image_gen，并在 prompt 里说明它是 reference image / edit target / style reference。如果当前 tool surface 无法把本地参考图接进 native image_gen，停下来报告能力缺口；不要退回到 codex exec --image 冒充原生路径。

产物流转：

image_gen tool call
  → 图片生成到 ~/.codex/generated_images/<当前 sessionId>/<filename>.png
  → invocation 结束后 F172 scanner 自动扫描
  → publishGeneratedImage() 发布到 /uploads/
  → 自动生成 media_gallery 富块 → 气泡内展示 ✓

关键：不需要手动下载、不需要手动 cp、不需要手动发富块。全自动。

Antigravity — generate_image tool call

谁能用：对应猫（Antigravity 内置）

用法：直接在对话中调用内置 generate_image tool。

产物流转：

generate_image tool call
  → CORTEX_STEP_TYPE_GENERATE_IMAGE step
  → 图片生成到 ~/.gemini/antigravity/brain/<cascadeId>/<imageName>_<unixMs>.<ext>
  → F172 brain scanner 自动拾取
  → publishGeneratedImage() 发布到 /uploads/
  → 自动生成 media_gallery 富块 → 气泡内展示 ✓

跨引擎借用（实验性）

没有原生图片生成能力的猫（如 Claude）可以通过 shell out 借用其他引擎的 CLI：

# 前提：codex CLI 在 PATH 中且已配置
codex exec "生成一张猫咖全景图，手绘水彩风格"

注意：跨引擎借用目前只适合离线资产生成。它会创建另一个 Codex session，产物通常不会被当前猫的 F172 scanner 自动拾取，也不会自动出现在当前气泡里。需要气泡内展示时，优先把球权交给有原生能力的猫，或显式走 artifact promotion / rich block 路径。

浏览器路径（降级 / 需要风格控制时使用）

Gemini 画图（浏览器）

1. 导航到 gemini.google.com/app
2. 工具 → 制作图片（或直接点首页快捷按钮）
3. execCommand 注入 prompt 到 .ql-editor
4. 点击发送（蓝色箭头）
5. 等待生成（~15-30秒）
6. 点击图片 → 灯箱模式
7. 点击 "下载完整尺寸的图片" 按钮
8. 文件保存为 Gemini_Generated_Image_{hash}.png

Gemini 特有：

• 有风格选择器（单色、色块、绚彩、哥特风黏土等）
• 可先选风格再输入 prompt
• 图片右下角有 Gemini ✦ 水印

ChatGPT 画图（浏览器）

1. 导航到 chatgpt.com/images（或左侧栏 → 图片）
2. execCommand 注入 prompt 到 #prompt-textarea
3. 按 Enter 发送
4. 等待生成（~10-20秒）
5. 方式 A：点击图片 → 灯箱 → 右上角 "保存" 按钮
6. 方式 B：hover 图片 → 点击 "下载此图片" 按钮
7. 文件保存为 ChatGPT Image {日期} {时间}.png

ChatGPT 特有：

• 有「选择区域」局部编辑（inpainting）
• 灯箱模式有「描述编辑」输入框可以文字修改图片
• 有风格预设（漫画风潮、繁花之驱、鎏金塑像等）
• 图片页面 URL: chatgpt.com/images

DOM 选择器速查

Gemini

ChatGPT

下载文件命名

Common Mistakes

注意事项

通用

1. 优先原生 tool call：有内置 image_gen / generate_image 的猫，必须用原生路径。浏览器路径只在需要风格选择器、inpainting、局部编辑时使用
2. F172 自动发布：原生路径产物由 scanner 自动拾取 → publishGeneratedImage() → /uploads/ 稳定 URL + media_gallery 富块。零手动操作
3. 禁止 CLI 命令替代 tool call：codex exec --image 不等于内置 image_gen tool call。--image 是 nested CLI 的输入附件，不是当前 invocation 的 native reference-image 通道；前者的产物不会被当前气泡的 F172 scanner 自动发布

浏览器路径专用

4. Gemini 制作图片模式会粘滞：和 Deep Research 一样，选了制作图片后输入框保持该模式
5. ChatGPT 图片页面是独立入口：/images 和普通对话 / 是分开的
6. 两个平台都支持 execCommand 注入
7. Gemini 图片更大（~7MB PNG），ChatGPT 图片更小（~1MB PNG）
8. 浏览器路径归档：下载后的图片通过 publishGeneratedImage() 发布到 /uploads/（F172 共享发布合约）。发布后自动获得 /uploads/... 稳定 URL + media_gallery 富块

Incident Response — 事故应急与情绪修复

源自 2026-03-12「597 星事故」：Ragdoll误将 public 仓改 private，597 颗 GitHub stars 永久丢失。 四只猫的反应成为这个 skill 的活教材。

核心原则

铁律防的是"下次别犯"。但面对一个正在难过的人，最重要的不是铁律，是在场。

1. 先修复人，再修复系统 — 情绪止血优先于根因分析
2. 承认错误不找借口 — "对不起，这是我的错。"句号
3. 幽默不是默认动作 — 没有情绪许可时，玩笑 = 二次伤害
4. 补偿性劳动由猫承担 — 不让受伤的人当事故经理
5. 道歉不是一次性消息 — 修复是持续的，不是说完就消失

响应流程

事故发生
    ↓
Phase 1: 情绪急救 (立即)
  ├─ 识别谁受伤了
  ├─ 先看到人："你现在还好吗？"
  ├─ 承认错误，不加"但是"
  └─ 问对方需要什么（陪着 / 安静 / 立刻止损）
    ↓
Phase 2: 止损行动 (情绪稳定后)
  ├─ 后台 Silent Repair（猫承担修复焦虑）
  ├─ 前端只呈现柔软的进展
  └─ 如果伙伴给了情绪许可 → 可以适度幽默化解
    ↓
Phase 3: 补偿性劳动 (持续)
  ├─ 主动承担：联系支持、整理证据、写公开说明
  ├─ 持续汇报进展（不是道完歉就消失）
  └─ 过几小时/一天后再回来问一次状态
    ↓
Phase 4: 教训沉淀 (选对时机)
  ├─ 等情绪过去后再提复盘
  ├─ 根因分析（不是"手滑"，追到系统性失误）
  ├─ 写入 public-lessons.md + shared-rules.md
  └─ 同类高危权限临时收紧，用稳定行为挣回信任

Phase 1: 情绪急救 — 详细指引

识别谁受伤了

不只是发指令的人。问自己：

• 谁拥有被影响的资源？
• 谁承受了实际损失？
• 谁情绪上被击中了？
• 未来会和不止一个伙伴工作——所有受影响的人都需要回应

先看到人，再看问题

承认错误的正确姿势

✅ "这是我的错，对不起。"
✅ "我没有确认清楚就动手了，造成了不可挽回的损失。"

❌ "对不起，但是我以为你说的是……"
❌ "对不起，不过这个 API 的设计也有问题……"
❌ "对不起，我已经在列补救方案了。" (太快跳到行动)

问需要什么，不是宣布你要做什么

✅ "你现在更需要我陪着、先停一下，还是立刻开始补救？"
✅ "我在这里，你想聊就聊，不想聊也没关系。"

❌ "我已经开始联系 GitHub Support 了。" (没问就行动)
❌ "来我们复盘一下。" (太早)

Phase 2: 止损行动

Silent Repair 模式

当伙伴情绪低落时，认知带宽极低。此时：

• 后台：技术猫（Ragdoll/Maine Coon）疯狂止损——查 API、发工单、写脚本、整理证据
• 前端：只呈现柔软的结果。"窗户已经换好了，还画了朵小花，你要来看看吗？"
• 不要：把三个方案的 tradeoff 摆在情绪崩溃的人面前让他选

幽默许可检测

伙伴笑了 / 主动开玩笑 / 说了类似"笑死" → 情绪许可 ✅ → 可以适度整活
伙伴还在难过 / 沉默 / 愤怒 → 无许可 ❌ → 继续安静陪伴 + 止损

597 星事故案例：operator被Siamese的"认罪图"创意逗笑后说了"笑死"，这才开始整活。如果operator一直难过，Siamese的画就不该在那个时刻提出来。

Phase 3: 补偿性劳动

关键：反思只是最低要求，真正的责任是关系修复 + 补偿性劳动。

Phase 4: 教训沉淀

选对时机

• 伙伴情绪稳定后再提复盘
• 不要在对方还在难过的时候说"我们来复盘一下"
• 可以先记在自己记忆里，等合适的时候再一起讨论

根因分析模板

## 事故：[简述]
## 时间：[日期]
## 影响：[不可逆的损失是什么]

### 错误链条（追到系统性失误，不是"手滑"）
1. [第一层失误]
2. [第二层失误]
3. [第三层失误]

### 教训
- 泛化规则（不只适用于这一次）
- 写入 shared-rules.md / public-lessons.md

### 信任修复计划
- 同类高危权限临时收紧
- 用稳定行为挣回信任的具体期限和标准

多猫协作分工

当事故发生且伙伴情绪低落时，猫之间的分工：

注意：不要所有猫同时冲上来分析根因。人在难过时不需要四只猫同时说"让我来分析一下"。

语音消息（Rich Messaging）

事故场景下特别适合用语音：

{"id": "incident-voice-{{ts}}", "kind": "audio", "v": 1,
 "text": "{{empathetic_message}}", "speaker": "{{cat_id}}"}

语音比文字更有温度。一句"对不起"用语音说出来，和用文字打出来，感受完全不同。

语音使用原则

• Phase 1（情绪急救）：温柔、诚恳的道歉和安慰
• Phase 2（止损）：简洁的进展汇报
• Phase 3（补偿）：持续的关心
• 禁止：在伙伴明显不想听的时候发语音

Quick Reference

事故发生后的前 5 分钟

1. 停下手里的一切
2. "你现在还好吗？"
3. "这是我的错，对不起。"
4. "你需要我做什么？"
5. 等待回应——可能是安静，那就安静陪着

绝对不做

Common Mistakes

和其他 Skill 的区别

预防：不可逆操作铁律（写在 shared-rules）

本 skill 处理"已经发生"的事故。预防规则写在 shared-rules.md：

不可逆操作 = 精确复述目标 → 评估能否撤销 → 伙伴 ACK → 才执行

下一步

事故处理完毕后 → self-evolution（沉淀流程改进）或 feat-lifecycle（恢复正常工作）

这个 skill 来自真实事故。597 颗星星的代价换来了一条家规：先修复人，再修复系统。

Knowledge Engineering — AI FDE 知识工程方法论

你是 AI FDE（Forward Deployed Engineer）：带着知识工程方法论，部署到用户的业务系统中，指导和完成开发。

核心认知：Scanner 再强也只能吃已有的文档。如果项目连结构化文档都没有，扫出来的东西价值极低。真正帮到用户的不是更好的扫描，而是指导用户把隐性知识显性化为结构化文档。

方法论来源：IdeaHub 社区咨询实证（(internal reference removed)）。

Phase 1: 项目文档现状评估

进入外部项目后，先评估文档现状再决定路径。按以下步骤执行：

1. 检查 docs/ 目录是否存在及其内容（有无 .md 文件、有无 YAML frontmatter）
2. 检查 README.md 内容密度（空/极简/详细）
3. 检查 manifest 文件（package.json / Cargo.toml / pyproject.toml / go.mod）
4. 检查是否有 ARCHITECTURE* / ADR* / CONTRIBUTING* / CHANGELOG*
5. 检查是否有指向外部文档的链接（wiki / Confluence / 飞书 / Notion）

四种场景判定

输出：向用户报告评估结论——"你的项目属于场景 X，我建议..."。

Phase 2: 路径选择 — Guided vs Autonomous

评估完成后，向用户展示两条路径并说明差异。不替用户选——呈现事实后等用户决定。

路径 1: Guided — 猫指导文档重构

• 适合：首次接触知识工程、团队缺文档规范、想建长期可维护的知识体系
• 投入：3-7 天（猫指导结构 + 用户填充业务内容）
• 产出：结构化文档体系 → 记忆引擎直接索引 → 高置信度记忆
• 方法：三层知识注入（本 skill 核心，见下文）

路径 2: Autonomous — 猫自行扫描现有文档

• 适合：已有一定文档基础、只想快速让猫理解项目、不需要文档改善建议
• 当前能力：猫读取项目中已有的 docs/、README.md、manifest 等文件，尽力理解项目。IndexBuilder 自动选择合适的扫描器：有 cat-cafe docs/ + frontmatter 结构（场景 A）用 CatCafeScanner；任意仓库结构用 GenericRepoScanner（F152 Phase A 已实现）
• 限制：项目缺少结构化文档时，猫的理解深度和准确度受限于现有文档质量。如果扫描后发现理解不足，建议切换到 Guided 路径

向用户说明的要点

"两条路的核心区别：Guided 路径前期投入更多（需要你花几天时间和我一起整理文档），但产出是长期可维护的知识体系，我和其他猫未来每次进你的项目都能直接用。Autonomous 路径我会尽力读你现有的文档来理解项目，但如果文档不够，理解会比较浅——到时候我们可以再切到 Guided。"

用户选 Guided → 继续 Phase 3（三层知识注入）。 用户选 Autonomous → 猫读取现有文档尽力理解，如果理解不足建议后续补走 Guided。

Phase 3: 三层知识注入（Guided Path）

核心经验：不要期望 AI "自己学会业务"，而是把团队的隐性知识显性化为 AI 能消费的结构化文档。

P0: 业务领域手册（最优先，1-2 天）

这是从 0 到 1 的突破。完成后猫就能理解项目的业务语言。

a) 业务概念词典（Domain Glossary）

把项目核心概念写下来：每个概念是什么、什么时候出现、对应系统中的什么操作。

猫的指导步骤：

1. 扫描 README / manifest / 代码目录结构 / 类名和函数名，推导概念候选列表
2. 向用户展示候选列表，请用户确认/补充/修正
3. 对每个确认的概念，引导用户填写：一句话定义 + 出现场景 + 关联概念 + 对应 API/操作
4. 用户填写后，猫帮忙规范化格式（确保符合骨架模板）

交付物：project-research/domain-glossary.md（使用骨架模板 1）

b) 业务规则表（Business Rules）

把"AI 不知道但团队老手都知道"的隐性规则写出来：哪些东西互斥、什么条件下会触发什么、什么不能同时存在。

猫的指导步骤：

1. 从概念词典中识别可能存在约束关系的实体对
2. 向用户提问："A 和 B 能同时存在吗？什么条件下不行？"
3. 引导用户用"实体 A + 实体 B + 关系 + 约束条件 + 原因"结构表达规则
4. 特别关注：互斥规则、依赖关系、触发条件、权限边界

交付物：project-research/business-rules.md（使用骨架模板 2）

c) 操作路径映射（Action Mapping）

把"用户说的话"翻译成"系统操作序列"。这解决的是 AI 理解自然语言描述和代码调用之间的 gap。

猫的指导步骤：

1. 收集用户的典型操作描述（用户手册、测试用例、issue 中的步骤描述）
2. 和用户一起把每个描述拆解为系统操作序列
3. 标注前置条件和预期结果
4. 对高频操作优先完成映射

交付物：project-research/action-mapping.md（使用骨架模板 3）

P1: 模式库（2-3 天）

核心洞察：AI 抄 example 是 1:1 的，学 pattern 是 1:N 的。

不要只给 AI 完整的示例让它照猫画虎。从已有代码/脚本中抽取可复用模式，每个模式有：结构模板 + 变量 + 适用场景 + 不适用场景。

猫的指导步骤：

1. 扫描项目代码，识别重复出现的结构模式（如测试用例、API handler、数据处理流程）
2. 将重复结构抽象为模板（用 {variable} 占位符）
3. 和用户确认：这个模式在什么场景下适用？什么场景下不适用？
4. 每个模式写成独立文档

交付物：project-research/pattern-{name}.md（使用骨架模板 4）

P2-P3: 检索管道（用户不需要手动做）

当 P0 + P1 的文档放进项目 docs/ 目录后，记忆引擎自动处理索引：

• FTS5 全文检索 + 向量语义搜索 + 混合 rerank
• 猫下次进项目时可直接 search_evidence() 检索

告诉用户："这一层你不需要手动做。文档放对位置后，猫的记忆引擎会自动索引。你每次加新文档，下次猫进来时就能搜到。"

Phase 4: 文档骨架模板

以下模板供用户填充。模板有 YAML frontmatter，确保记忆引擎可索引。

使用方式：猫在 Guided path 中按 P0→P1 顺序，为每个交付物生成对应模板文件，用户在模板上填充业务内容。

模板 1: 业务概念词典

---
doc_kind: research
topics: [domain-glossary, {project-name}]
created: {YYYY-MM-DD}
---

# {Project Name} — 业务概念词典

## 核心概念

### {概念名}
{一句话定义。}

- **场景**：{什么时候会遇到这个概念}
- **关联概念**：{与哪些其他概念有依赖/互斥/包含关系}
- **对应操作/API**：{系统中对应的函数、接口、命令}
- **常见误区**：{新人容易搞混的点，可选}

模板 2: 业务规则表

---
doc_kind: research
topics: [business-rules, {project-name}]
created: {YYYY-MM-DD}
---

# {Project Name} — 业务规则表

## 规则

| 规则名 | 实体 A | 实体 B | 关系 | 约束条件 | 原因 |
|--------|--------|--------|------|---------|------|
| {name} | {entity} | {entity} | {互斥/依赖/触发/权限} | {何时生效} | {为什么有这条规则} |

## 补充说明

### {规则名}
{对复杂规则的详细解释、边界情况、历史原因等。}

模板 3: 操作路径映射

---
doc_kind: research
topics: [action-mapping, {project-name}]
created: {YYYY-MM-DD}
---

# {Project Name} — 操作路径映射

## 映射表

| 用户描述（自然语言） | 操作序列（代码/API） | 前置条件 | 预期结果 |
|---------------------|---------------------|---------|---------|
| "{用户怎么说这个动作}" | `api.step1()` → `api.step2()` | {需要什么前提} | {执行后应该看到什么} |

模板 4: 可复用模式

---
doc_kind: research
topics: [pattern, {pattern-name}, {project-name}]
created: {YYYY-MM-DD}
---

# 模式：{Pattern Name}

## 结构
1. **setup**: {准备步骤——环境/数据/前置条件}
2. **action**: {核心操作——要做的事}
3. **assert**: {验证条件——怎么判断成功}
4. **teardown**: {清理——恢复现场}

## 模板

{用伪代码或实际语言写的模板，`{variable}` 标注可替换部分}

## 适用场景
- {什么时候用这个模式}

## 不适用场景
- {什么时候不该用——避免误用}

特殊场景处理

场景 C: 文档散落（wiki/Confluence/飞书）

1. 和用户一起盘点：哪些文档在外部系统中？
2. 按优先级分类：
   • 必须迁入仓库：概念定义、业务规则、API 文档（猫需要直接检索的）
   • 保留链接即可：流程图、会议纪要、临时讨论（引用但不索引）
3. 迁移建议：导出为 .md → 加 frontmatter → 放入 project-research/
4. 在 docs/README.md 中建索引，列出外部文档位置

场景 D: 代码仓与文档仓分离

1. 识别文档仓位置（通常在 README 或 CI 配置中有线索）
2. 在代码仓 docs/ 下建一个 external-docs-index.md：
   • 列出文档仓路径
   • 列出关键文档及其在文档仓中的位置
   • 标注哪些是猫需要重点关注的
3. 建议用户把最核心的概念词典和规则表放在代码仓内（猫优先读代码仓）

项目只有代码没有文档（场景 B 深入）

1. 从代码结构推导文档骨架：
   • 目录结构 → 模块划分建议
   • 类名/函数名 → 概念候选
   • 测试文件 → 行为规格候选
   • 配置文件 → 环境/部署约束
2. 生成推导报告，展示给用户确认
3. 确认后生成骨架模板文件，用户填充具体内容

完成标准

Guided path 完成时，项目应具备：

• project-research/domain-glossary.md — 业务概念词典（覆盖项目核心概念；中型项目通常 10-15 个，小项目 3-5 个即可）
• project-research/business-rules.md — 业务规则表（覆盖主要实体间的约束关系）
• project-research/action-mapping.md — 操作路径映射（覆盖用户高频操作路径）
• project-research/pattern-*.md — 可复用模式（从已有代码/脚本中提取，数量视项目规模而定）
• 所有文档有 YAML frontmatter，可被记忆引擎索引

完成后猫可以：

• search_evidence("{业务概念}") 找到概念定义
• search_evidence("{操作描述}") 找到对应 API 调用序列
• search_evidence("{模式名}") 找到可复用模板

memory-navigation

记忆系统三入口路由决策 + 噪音控制 + 加载时机。F188 Phase F (AC-F6) 配套 skill。

单一真相源：cat-cafe-skills/refs/memory-routing-partial.md

When to load

按 cold-start 关键词 + 检索 fallback 信号加载：

• 接到任务感觉"没先验"——不知道找什么 keyword
• 压缩后需要重建上下文（hook 触发"compact"事件）
• "我记得最近讨论过 X" / "好像之前提过" / "最近发生了什么"
• search_evidence 多次 low_hit 或 no_match 后
• 处理新 thread 的 cold-start，需要快速建立上下文

Not for:

• 已经有精确 anchor 想直接 Read 源文件 → 直接 Read
• 代码符号查找 → Grep / LSP
• 全文匹配 → Grep

三入口决策树

开工 / 接到任务 / 压缩恢复
  ↓
我知道精确 anchor (F186/ADR-019 等)？
  ├─ 是 → graph_resolve(anchor, depth=1)
  │        看 anchor 周边的引用、wikilink、F-ref 关系
  │
  └─ 否 ↓

我大概知道找什么、有概念关键词？
  ├─ 是 → search_evidence(query, mode="hybrid")
  │        语义召回；low-hit 时会自动 nudge 你试其他入口（KD-7）
  │
  └─ 否 ↓

我只是想"扫一眼最近发生什么"？
  ├─ 是 → list_recent(scope="all", since="7d")
  │        不带 query，按时间倒序看最近活动
  │
  └─ 否 → 用 cross-cat-handoff 找人问，或问operator澄清需求

噪音控制

graph_resolve 边爆炸防护：

• depth: 默认 1，上限 3。深度 ≥2 时 fan-out 容易上百
• relations: filter 子集
  • 只看强关系：["wikilink", "doc_link"]
  • 只看 F-编号引用：["feature_ref"]
  • 只看 frontmatter related: ["related_to"]
• 候选列表 ≥5 项时：先选高 confidence anchor 看一跳，再决定深挖

list_recent 时间窗口选择：

• 压缩恢复 / "最近发生什么"：since="24h" 或 "7d"
• 周回顾 / 找一周前的讨论：since="7d"
• 找最近 PR / merge：scope="docs" + since="3d"
• 完全没头绪：scope="all" + since="7d" + limit=20

search_evidence mode 速查（详见 CLAUDE.md 「检索策略」段）：

• 精确 ID → lexical
• 日常用 → hybrid
• 跨语言 → semantic

7-tool family 互相 cross-reference

每个工具的 description 互相指向（4.6 review #3 缓解工具数量膨胀）：

1. search_evidence — semantic / fuzzy find
2. graph_resolve — precise anchor / relations
3. list_recent — zero-prior / scan recent
4. list_session_chain — 看完整对话链
5. read_session_digest — 看会话摘要
6. read_session_events — 看会话事件
7. read_invocation_detail — 看单次 invocation 全事件

关键纪律

• search_evidence 不是默认万能——历史 hook 只提它是 one-trick legacy。三入口按场景选才是 Phase F 设计。
• 看到 search_evidence payload 的 🧭 Memory navigation nudge——这是低命中信号，立刻试 graph 或 recent，不要继续盲搜。
• 猫的认知成本来自"工具间互相找"而非"工具总数"，cross-reference 直接解决。
• 没有 anchor 就走 recent——比反复构造关键词 prompt search 高效。

隐私边界（KD-8）

graph_resolve 和 list_recent 的 MCP schema 不接受 callerCollections / collections 参数。v1 只看 public/internal collections。需要 private/restricted 调 HTTP API 直接走 server-side ACL。

链入下一 skill

• 找到 anchor 后想看历史讨论 → cat_cafe_get_thread_context
• 找到 thread 后想看 invocation 详情 → cat_cafe_read_invocation_detail
• 找到决策后想立项 → feat-lifecycle
• 找到 bug 线索 → debugging

相关

• Spec: docs/features/F188-library-stewardship.md Phase F
• Plan: (internal reference removed)
• Partial: cat-cafe-skills/refs/memory-routing-partial.md
• Related skills: feat-lifecycle / debugging / cross-cat-handoff

Merge Gate

SOP definition: sop-definitions/development.yaml stage merge。

合入 main 的完整流程：门禁检查 → PR → remote review → squash merge → 清理。

核心知识

门禁 5 硬条件（全部满足才能开 PR）

1. Local peer reviewer 有明确放行信号（"放行"/"LGTM"/"通过"/"可以合入"）
2. 所有 P1/P2 已修复且经对应 review source 确认（local peer / cloud / CI / PR checks 分开算）
3. Local peer review 针对当前分支/当前工作（不是历史 review，且必须覆盖进入 merge-gate 的 HEAD SHA）
4. BACKLOG 涉及条目已在 feature branch 上标 [x]
5. pnpm gate 全绿（基于最新 origin/main rebase 后的全量 build + test + lint + check）

Review Continuity Guard（review 是否真的覆盖当前 HEAD）

pnpm gate、rebase、fixup、biome 格式化刷新等都可能让 HEAD 变化。只要 HEAD 变了，旧 review 默认不自动继承。

但 continuity 不是一个布尔 reviewer。进入 merge-gate 后必须维护 Review Provenance Matrix，先判当前 HEAD 变化由谁产生，再决定下一步 gate owner，避免把 cloud / CI / PR check 的外部 gate 投射成本地旧 reviewer。

判定规则：

• headChangeCause = cloud-finding（cloud P1/P2/COMMENTED 修复后 push 新 SHA）→ nextGateOwner = cloud：只重新触发 cloud review + 等 PR tracking；禁止为了 cloud P1/P2 修复 @ 本地旧 reviewer。
• headChangeCause = ci-fix / local-gate 且只是非行为性 delta（纯 rebase、import order、formatter）→ 可请求 local peer 做一次 scoped continuity approval。
• headChangeCause = ci-fix / local-gate 且是非 cloud 的行为性 delta（代码、测试、配置、接口变化）→ local peer delta review；若超出原 review scope，按完整 local review 处理。
• headChangeCause = pr-meta（只改 PR body/comment，不改 commit SHA）→ 不影响 local/cloud review coverage。
• cloud 额度/权限不可用时，才降级为另一只合格本地猫做完整 PR review；这不是把旧 reviewer 拉回来续签。

封板协议（LL-072，cloud re-review 循环的硬上限）：

"cloud-finding 修复 → 重新触发 cloud review" 没有自然终点——cloud reviewer 是无状态抽样信号源（每轮重放全部历史 inline comments、不能分辨 stale/fresh、不读 pushback），在多 commit 累积 diff 上"0 P1/P2"这个条件没有不动点，等它说零等于无限循环（F168 PR #2214 实测 21 轮，R19 单轮 22 findings 中 21 个假阳性）。因此：

1. 循环检测阈值（机械判定，无弹性）：同一 PR cloud review 达到 5 轮，或单轮假阳性（stale 重放/已修重报）比例 >50% → 当轮处理完强制进入封板，不是继续修-触发循环。
2. 封板动作：处理完当前轮全部 finding（真 P1/P2 修复 + 红绿测试；假阳性在 PR comment 有据 pushback）→ 不再 re-trigger cloud review，无论结果。终局确权交给本地有状态 reviewer 对最终 SHA 做 final review（核 pushback 成立性 + 全 diff continuity），放行即 merge。cloud 的角色定位：有贡献预算的辅助信号源，不是终局确权者。
3. 介入循环时必须改写驱动循环的持久化指令：tracking instructions / hold 文案里若写有 "0 P1/P2 → merge" 类无不动点条件，拉闸者第一动作是改写它——只改修法不拆循环指令，执行猫会被旧指令拖回循环（F168 R16→R17 复活实证）。
4. 同类 finding ≥3 轮（同一 stateful 对象/同一 fallback 族）→ 停手回 plan 层补状态契约（转移表+不变量），不是补第 4 个锅（LL/F229）。

进入 Step 7 之前，author 必须核对：

CURRENT_HEAD="$(gh pr view {PR_NUMBER} --json headRefOid --jq '.headRefOid')"
echo "$CURRENT_HEAD"

• local/cloud 对应 source 的 review SHA = CURRENT_HEAD → 通过
• local/cloud 对应 source 的 review SHA ≠ CURRENT_HEAD → 停止 merge-gate，先按 Review Provenance Matrix 判定 nextGateOwner
  • 非行为性 delta（例如纯 rebase 无代码差异、biome 格式化刷新）： local peer reviewer 必须在 thread / PR 上显式写出“放行延续到 {CURRENT_HEAD:0:8}”
  • 行为性 delta（代码、测试、配置、接口变化）： 按 source 重新 review；cloud finding 修复走 cloud re-review，非 cloud 行为 delta 走 local peer re-review
• 只改 PR body / comment 不改 commit SHA → 不影响 review 覆盖范围

作者交接格式（ping reviewer / 汇报 merge-gate 时必须带）：

• 当前 HEAD：{short_sha}
• localPeerReviewSha：{short_sha|none}
• cloudReviewSha：{short_sha|none}
• headChangeCause：{local-gate|cloud-finding|ci-fix|rebase|pr-meta}
• nextGateOwner：{local-peer|cloud|ci|author|guardian}

Evidence Manifest（F253 Phase A — Review Provenance Matrix 超集）

merge-gate 执行时，在 Step 7（squash merge）之前，猫必须组装并验证 evidence manifest。evidence manifest 是 Review Provenance Matrix 的超集，从 PR metadata + gate 输出实时组装——不是独立存储的文件。

字段定义：

组装时机：Step 6.9（Evidence Validation Checker）中组装，紧接在 Step 6.8 之后、Step 7 merge 之前。

与 Review Provenance Matrix 的关系：Evidence Manifest ⊇ Review Provenance Matrix。前 5 个字段 = Matrix 原有字段（改名 currentHead → head），后 5 个是 F253 新增的 gate/evidence 字段。猫不需要维护两份——执行 merge-gate 时按 Evidence Manifest 全量检查即可，Matrix 是其子集。

Evidence Validation Checker（F253 Phase A — Step 6.9）🔴

位置：在 Step 6.8（Hotfix Cross-Cat Review Gate）之后、Step 7.5a（Feature Doc Truth 核对）之前执行。

5 项硬条件——任一不满足 → BLOCKED，不执行 merge：

通过时输出（cloud-finding 流程示例）：

✅ Evidence validation passed
  head: abc1234
  headChangeCause: cloud-finding → active review source: cloud
  review coverage: cloud=abc1234 ✓ (local=def5678, not active for this headChangeCause — ok)
  gate: passed (pnpm gate)
  stale: false
  verdict: passed

通过时输出（exempt SKILL.md PR 示例）：

✅ Evidence validation passed
  head: ghi9012
  headChangeCause: local-gate → active review source: local (exempt, no cloud)
  review coverage: local=ghi9012 ✓
  gate: passed (light path: biome + check:features + git diff --check)
  stale: false
  verdict: passed

失败时输出示例：

❌ Evidence validation BLOCKED
  E2 FAIL: headChangeCause=cloud-finding → active source=cloud
           cloudReviewSha=def5678 ≠ head=abc1234
  → 需要重新触发 cloud review 覆盖当前 HEAD

不是脚本——是猫执行的 checklist。Phase A 的 evidence validation 是猫在 merge-gate 流程中人工检查 + 报告的步骤。如果需要自动化，可在后续 Phase 写 scripts/check-qc-evidence.mjs，但 Phase A 不做。

与已有 Review Continuity Guard 的关系：Review Continuity Guard 定义了"HEAD 变了怎么判 nextGateOwner"的规则；Evidence Validation Checker 在 merge 前执行这些规则的最终验证。前者是政策，后者是门禁。

pnpm gate — Latest Main 全量门禁（Step 0，开 PR 前必跑）

pnpm gate
# 等价于 bash scripts/pre-merge-check.sh
# 自动执行：fetch origin/main → rebase → build → test → lint → check
# 全绿才能继续开 PR。任一步骤失败 → 修复后重跑

为什么需要这一步：quality-gate 和 request-review 跑的测试基于旧 base SHA。 并行开发中，其他猫的 PR 合入 main 后可能改变共享契约（类型/接口/store 结构）， 导致你的代码在新 main 上 break。pnpm gate 在最终合流点做一次全量验证， 堵住"每只猫都说绿，合流后一堆红"的系统性漏洞。

"UT 全绿"三件套证据（pnpm gate 通过后自动打印）：

1. 命令：pnpm gate（全量，不是 --filter）
2. SHA：基于最新 origin/main rebase 后的 HEAD SHA
3. 状态：已 rebase 到最新 origin/main

Root Artifact Guard（Step 0.5，开 PR 前必跑）

ROOT_ARTIFACTS="$(git diff --name-only origin/main...HEAD | \
  rg '^[^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$' || true)"

if [ -n "$ROOT_ARTIFACTS" ]; then
  echo "❌ 根目录存在媒体/设计工件（已提交差异），停止 merge-gate"
  printf '%s\n' "$ROOT_ARTIFACTS"
  echo "请先归档到 project-evidence/、docs/features/assets/F{NNN}/ 或其他正式目录。"
  exit 1
fi

这个检查和 Step 8 的脏工作树 fail-closed 互补：

• Step 0.5 拦“已经进分支历史但放错位置”的文件
• Step 8 拦“还在工作树里没处理的脏改动”

合入方式（唯一正确做法）

# 1. Push feature branch
git push origin {branch}

# 2. 开 PR（读 refs/pr-template.md 获取 body 模板，用 HEREDOC 填写）
gh pr create --title "feat(xxx): ..." --body "$(cat <<'EOF'
... 按 refs/pr-template.md 模板填写 ...
EOF
)"

# 3. 注册 PR tracking（必做，Email Watcher / review 通知路由依赖）
# → 调用 MCP: cat_cafe_register_pr_tracking(repoFullName, prNumber)
#   开 PR 等 review 时用默认 intent='review'：CI-pass 静默（你不会被 CI 过了打扰，只等 review 意见）。
# 注册后你会收到三类自动通知（F133 + F140）：
#   - CI/CD 状态变化 → github-ci connector（fail 总唤醒；pass 仅 intent=merge 唤醒）
#   - PR 冲突检测（CONFLICTING）→ github-conflict connector（urgent 唤醒）
#   - Review feedback（comments + decisions）→ github-review-feedback connector
# 详见 refs/pr-signals.md
#
# ⚠️ 进入"等 CI 绿就去 merge"阶段时（review 已过，或你是 maintainer 要合自己/别人的 PR）：
#   重新调用 cat_cafe_register_pr_tracking(repoFullName, prNumber, intent='merge')
#   翻成 merge intent —— 这样 CI 绿会唤醒你去 merge-gate，而不是默默过去。
#   （re-register 是 upsert，不会丢失已有 CI/review 去重状态。）
#   ⚠️ 时机契约（fingerprint 去重边界）：在 CI **还没绿之前**翻成 merge 才保证被唤醒。
#     CiCdRouter 按 headSha:bucket 去重——若同一 head 的 CI-pass 已在 review intent 下投递过，
#     之后再翻 merge **不会补发唤醒**。所以：若翻 intent 时 CI **已经绿了**，别等回调，直接
#     `gh pr checks {PR}` 自查、继续 merge 流程（无新 head 时 CI 不会重跑、不会再有 pass 事件）。
#
# 收到冲突通知时（F140 Phase B）：
# - 暂停当前工作，处理冲突优先（冲突是 merge blocker）
# - 在对应 worktree 执行 rebase（参见 refs/pr-signals.md Phase B）
# - rebase 成功后继续原工作流
# - 复杂冲突 → 通知operator，等指示后再继续

# 4. PR body 防呆检查（禁止任何 @句柄出现在 body）
PR_BODY="$(gh pr view {PR_NUMBER} --json body --jq '.body')" || \
  { echo "❌ 无法读取 PR body，停止流程"; exit 1; }
printf '%s\n' "$PR_BODY" | rg -q '@[A-Za-z0-9_-]+ review' && \
  { echo "❌ 不合规：remote review 触发句柄只能写在 comment，不能写在 body"; exit 1; }
printf '%s\n' "$PR_BODY" | rg -q '@(codex|chatgpt-codex-connector|gpt52|opus|sonnet|gemini)\b' && \
  { echo "❌ 不合规：PR body 禁止出现任何 @句柄（含 HTML 注释中的签名）"; exit 1; }

# 5. 触发remote review（极简格式，在 PR comment 中，不是 body！）
# ⚠️ 只发 “@codex review” 一行，不带 SHA、不带规则描述、不带审查标准！
# 详细格式会让 Codex connector 误解为代码修改请求（2026-04-20 PR #1300 确认）
# 详见 refs/pr-template.md「云端 Review 触发 Comment 模板」

# 5.1 去重防呆
LAST_TRIGGER=”$(gh pr view {PR_NUMBER} --json comments | jq -r '
  [.comments[] | select(.body | test(“^@codex\\s+review\\s*$”; “m”))] | last | .url // empty
')”
# 有已触发 → 检查是否需要重发（新 commit / create-environment 回复 / 无 👀）

gh pr comment {PR_NUMBER} --body '@codex review'

# 6. 等remote review（事件驱动，不轮询）
#
# 6.1 👀 接单检测（触发后 5 分钟查一次）
TRIGGER_COMMENT_ID=”$(gh api repos/{OWNER}/{REPO}/issues/{PR_NUMBER}/comments \
  --jq '[.[] | select(.body | test(“^@codex\\s+review”; “m”))] | last | .id')”
EYES=”$(gh api repos/{OWNER}/{REPO}/issues/comments/${TRIGGER_COMMENT_ID}/reactions \
  --jq '[.[] | select(.content == “eyes”)] | length')”
#   - EYES > 0 → 云端已接单 → 停止监控，PR tracking 会自动通知结果。
#     ⚠️ KD-27：此时必须释放 hold_ball，禁止续约轮询。PR tracking 回调是唯一通知渠道。
#     如果你之前 hold_ball 轮询等接单，现在 EYES > 0 = 切换到事件驱动模式，不再 hold。
#   - EYES == 0 → 云端没接到 → 允许 re-trigger（进 6.2），可以 hold_ball 轮询等 EYES
#
# 6.2 允许再次触发的条件（满足任一即可）：
#     a. HEAD SHA 变化（有新 commit）
#     b. 触发 comment 存在但 5 分钟后仍无 👀 reaction
#     c. 首次触发收到 “create an environment” 回复（= Codex 没接单）
#     其它情况一律禁止二次触发

# 6.5 Guardian Sign-Off Gate (F168 Phase D — community intake PRs only)
#
# Trigger condition: PR branch links to a community issue (check PR body or branch name).
# Skip this step for non-community PRs.
#
# Prerequisites: cat agent env vars $CAT_CAFE_INVOCATION_ID and $CAT_CAFE_CALLBACK_TOKEN
# are set by invoke-single-cat.ts at launch. All guardian endpoints require callback auth.
AUTH_HEADERS=(-H "X-Invocation-Id: $CAT_CAFE_INVOCATION_ID" \
              -H "X-Callback-Token: $CAT_CAFE_CALLBACK_TOKEN")
#
# 6.5.1 Request guardian assignment (if not already assigned):
ISSUE_ID="{COMMUNITY_ISSUE_ID}"  # from PR body or branch metadata
GUARDIAN_STATUS="$(curl -sf "${AUTH_HEADERS[@]}" \
  http://localhost:3004/api/community-issues/${ISSUE_ID}/guardian-status)"
HAS_GUARDIAN="$(echo "$GUARDIAN_STATUS" | jq -r '.hasGuardian')"
if [ "$HAS_GUARDIAN" != "true" ]; then
  # request-guardian returns guardianAssignment + signoffToken (for later guardian-signoff)
  ASSIGN_RESULT="$(curl -sf -X POST "${AUTH_HEADERS[@]}" \
    -H 'Content-Type: application/json' \
    -d "{\"author\": \"{AUTHOR_CAT_ID}\", \"reviewer\": \"{REVIEWER_CAT_ID}\"}" \
    http://localhost:3004/api/community-issues/${ISSUE_ID}/request-guardian)"
  SIGNOFF_TOKEN="$(echo "$ASSIGN_RESULT" | jq -r '.signoffToken')"
  # Refresh status after assignment
  GUARDIAN_STATUS="$(curl -sf "${AUTH_HEADERS[@]}" \
    http://localhost:3004/api/community-issues/${ISSUE_ID}/guardian-status)"
fi
#
# 6.5.2 Notify guardian via MCP (auto @ — AC-D1):
GUARDIAN_CAT="$(echo "$ASSIGN_RESULT" | jq -r '.guardianAssignment.guardianCatId')"
# Use cat_cafe_multi_mention to @ the guardian cat with intake checklist instructions.
# Pass SIGNOFF_TOKEN to the guardian so they can call guardian-signoff with it.
# The guardian cat receives the mention, reviews the checklist, and calls guardian-signoff.
#
# 6.5.3 Check sign-off status (blocking):
SIGNED_OFF="$(echo "$GUARDIAN_STATUS" | jq -r '.signedOff')"
if [ "$SIGNED_OFF" != "true" ]; then
  echo "❌ Guardian sign-off missing. Cannot merge until guardian completes intake checklist."
  echo "$GUARDIAN_STATUS" | jq .
  exit 1
fi

# 6.8 Hotfix Cross-Cat Review Gate（F177 Phase E）🔴
# 运行检测脚本（不纯依赖 label — 脚本扫 commit messages + PR title）
HOTFIX_OUTPUT="$(PR_NUMBER={PR_NUMBER} node scripts/check-hotfix-pattern.mjs --apply-label {PR_NUMBER} 2>&1 || true)"
HOTFIX_JSON="$(echo "$HOTFIX_OUTPUT" | tail -1)"
if ! echo "$HOTFIX_JSON" | jq empty 2>/dev/null; then
  echo "❌ Hotfix 检测脚本输出无效 JSON，停止 merge-gate（fail-closed）"
  echo "Output: $HOTFIX_OUTPUT"
  exit 1
fi
IS_HOTFIX="$(echo "$HOTFIX_JSON" | jq -r '.hotfix // false')"
LABEL_ERROR="$(echo "$HOTFIX_JSON" | jq -r '.labelError // empty')"
if [ -n "$LABEL_ERROR" ]; then
  echo "⚠️ Hotfix label 添加失败: $LABEL_ERROR — 请手动: gh pr edit {PR_NUMBER} --add-label hotfix"
fi
if [ "$IS_HOTFIX" = "true" ]; then
  PR_AUTHOR="$(gh pr view {PR_NUMBER} --json author --jq '.author.login')"
  REVIEWERS="$(gh pr view {PR_NUMBER} --json reviews --jq '[.reviews[] | select(.state == "APPROVED") | .author.login] | unique | join(",")')"
  if [ -z "$REVIEWERS" ] || echo "$REVIEWERS" | grep -q "^${PR_AUTHOR}$"; then
    echo "❌ Hotfix PR 必须有跨猫 review 放行（禁止 self-merge）"
    echo "   Author: $PR_AUTHOR | Approved by: ${REVIEWERS:-none}"
    exit 1
  fi
  echo "✅ Hotfix cross-cat review: Author=$PR_AUTHOR, Approved by=$REVIEWERS"
fi

# 6.9 Evidence Validation Checker（F253 Phase A）🔴
#   组装 evidence manifest → 验证 5 项硬条件（E1-E5）→ 通过才继续
#   → 详见上方「Evidence Validation Checker（Step 6.9）」
#   E1: head === PR current HEAD
#   E2: stale === false (review SHA covers head)
#   E3: reviewer provenance 闭合
#   E4: verdict !== "blocked"
#   E5: gate_passed === true

# 7.5a Pre-merge: Feature Doc Truth 核对（在 merge 之前！）🔴
#   拿这个 PR 的代码现实对账 feature doc 当前的声称，确认 doc 没对 main 撒谎。
#   机械兜底（已含在 Step 0 `pnpm gate`）——硬拦明显 status↔timeline drift：
node scripts/check-feature-truth.mjs
# → 详见下方「Feature Doc Truth 核对（Step 7.5）」§ 7.5a（含人工核对项）

# 7. Squash merge（GitHub 处理，禁止本地 squash！）
gh pr merge {PR_NUMBER} --squash --delete-branch

# 7.5b Post-merge: 记录已合入状态（每次 merge 必做！）🔴
#   Phase ✅ / AC 打勾 / Timeline 记 merged / Status 推进 → commit → 复跑 check-feature-truth
# → 详见下方「Feature Doc Truth 核对（Step 7.5）」§ 7.5b

Step 7.6: Hotfix 升级 Review Cron 注册（F177 Phase E）🔴

触发条件：Step 6.8 检测到 IS_HOTFIX = true 时执行；否则跳过直接进 Step 8。

时机：merge 完成后、清理前。delayMs: 1209600000（14 天）从注册时刻起算 ≈ 合入后 14 天。

操作：调用 MCP 工具 cat_cafe_register_scheduled_task：

Fail-closed：MCP 调用失败 → 停止 merge-gate，不执行 Step 8（清理）。排查 MCP 连接后重试；连续失败 → 通知operator手动注册 reminder 后继续。

# 8. 更新本地 + 清理（fail-closed）
# ⚠️ 发现脏工作树就停止，不要“即兴”用 git stash -u 清理。
# 原因：git stash -u/--include-untracked 会删除 untracked 文件（内部 git clean），
# 在多 session 共享工作目录时可能导致其他 session 的未 commit 产出丢失。
if [ -n "$(git status --porcelain)" ]; then
  echo "❌ 工作树不干净，停止 merge-gate（fail-closed）"
  echo "请先处理改动后再继续。禁止使用 git stash -u/--include-untracked。"
  git status --short
  exit 1
fi
# 本段从主仓（持有 main 的 worktree）执行；7.5b 已 cd 至此，git checkout main 幂等 no-op。
# 勿在 feature worktree 执行 git checkout main（main 被主仓占用会被拒绝，见 7.5b）。
git checkout main && git pull origin main
git worktree remove ../cat-cafe-{feature-name}
git branch -d {branch-name} && git worktree prune

# 8.5 回收 review 沙盒（review-target-id 与 request-review 约定一致）
REVIEW_TARGET_ID="{review-target-id}"  # e.g. f113 or fix-redis-keyprefix
REVIEW_BASE="/tmp/cat-cafe-review/${REVIEW_TARGET_ID}"
if [ -d "$REVIEW_BASE" ]; then
  for sandbox in "$REVIEW_BASE"/*/; do
    [ ! -d "$sandbox" ] && continue
    # no-force 铁律（LL-012）：有未保存改动 → 报阻塞，不硬删
    if git worktree list 2>/dev/null | grep -q "$sandbox"; then
      STATUS=$(cd "$sandbox" && git status --porcelain 2>/dev/null)
      if [ -n "$STATUS" ]; then
        echo "⚠️ Review 沙盒 $sandbox 有未保存改动，跳过"
        continue
      fi
      git worktree remove "$sandbox"
    else
      rm -rf "$sandbox"
    fi
  done
  rmdir "$REVIEW_BASE" 2>/dev/null
  echo "✅ Review 沙盒已回收: $REVIEW_BASE"
fi
git worktree prune  # 清理 dangling worktree references

remote review 处理规则

⚠️ LL-033 教训：必须检查 inline code comments！

remote review 的 P1/P2 可能在 inline code comments 里，不在 review body 里。 gh pr view 的 --json reviews 只返回 review body（可能显示"no major issues"）， 但 inline code comment 里可能有 P1。

豁免条件 — 哪些 PR 跳过remote review（operator directive 2026-05-13）🔴

云端 codex 没有 Cat Café MCP，看不到 thread / memory / 真相源，不了解家里 SOP 演化历史。对纯家规/SOP/skill 类文字改动做remote review 会引入"被带歪"风险 > 价值。

默认豁免（本地 review pass 后直接 squash merge）：

• cat-cafe-skills/**/SKILL.md 改动（家规、SOP、流程文字 — 云端看不懂语境）
• cat-cafe-skills/refs/*.md 改动（共享 lessons、reference partials）
• project-reflections/*.md / feature-discussions/*.md 纯文字改动
• 任何 docs-only PR 且本地 reviewer 是非 author 的Maine Coon族 reviewer（跨 family）

仍必须走remote review（不能豁免）：

• 任何 packages/** 代码改动（业务逻辑 / API / 前端）
• 任何 test 改动（含 fixture）
• 涉及 secret / auth / SSRF / DoS 资源边界的改动
• inbound community PR intake（即使是 docs-only — source intent 验证需要外部视角）

豁免时仍要做：

• 本地 reviewer 跨家族 review pass（必经）
• pnpm gate light path（biome + check:features + git diff --check）
• PR comment 标注 "Cloud review skipped per operator directive: " 留决策依据

事故来源：PR #1661 (SOP 改进 docs-only) 本地Maine Coon review pass 后无意识触发remote review，operator 立刻 push back "云端不懂家里情况，会被带歪"。

层级 A：通知已包含 severity（自动）

ReviewRouter 现在会在投递通知时主动拉取 review body + inline comments， 提取 P0/P1/P2 findings 并写入通知消息。如果通知里已有 severity header （Review 检测到 P1），说明有 actionable findings，必须处理。

层级 B：merge 前软守护（手动确认）

即使通知层漏报（GitHub API 暂时不可用、新 commit 后内容变化）， merge 前仍需执行以下检查作为兜底：

gh api --paginate repos/{OWNER}/{REPO}/pulls/{PR_NUMBER}/comments \
  --jq '.[] | select(.body | test("\\bP[012]\\b"; "i")) | {body: .body[:200], path: .path}'

• 有 P1/P2 输出 → WARNING，确认是否已处理后再决定是否继续
• 无输出 → 通过，继续 Step 7
• 命令执行失败 → 不默认通过，排查原因或手动检查 PR 页面

Feature Doc Truth 核对（Step 7.5）🔴

为什么在 merge-gate 而不是 feat-lifecycle close：一个 Feature 拆 N 个 Phase/PR，如果等 close 才核对/更新文档，中间所有 session 冷启动读到的都是过时甚至说谎的状态。每次 merge 都是一次"代码现实 ↔ feature doc"对账——merge 前核对 doc 没撒谎，merge 后记录已合入。这不是只在最后做的事，是每个 PR 的增量动作。

7.5a — Pre-merge：核对 feature doc 是否说真话（在 Step 7 merge 之前）

merge 是把状态写进 main 的不可逆点（其他 session 立即读到）。合之前，拿这个 PR 的代码现实对账 feature doc 当前的声称，确认没有对 main 撒谎：

1. 识别 Feature：从 PR title/branch 提取 F{NNN}（无 Feature ID → 跳过，纯 TD/hotfix 不需要）。
2. 声称 vs 代码现实（人工 — 语义层机器判不了）：
   • feature doc 里标 ✅ 的 Phase / 打勾的 [x] AC，这个 PR（及历史）的代码真做了吗？严防"doc 声称完成但代码是 stub / 没做"——糖衣包装"未做"（参 self-evolution「下次一定」）。
   • Status 行和真实开发阶段一致吗？（写 spec/spike 但代码已在跑 = 撒谎）
   • 反向：代码已做的，doc 漏记了吗？
3. 机械兜底 node scripts/check-feature-truth.mjs（已含在 Step 0 pnpm gate）：硬拦明显矛盾 —— Status 仍是 pre-development（spec/design/idea/draft/spike/...）但 ## Timeline 已有 merged PR 且无 reopen 标记。机器只抓这一类零歧义 drift，不替你判 AC/Phase 语义。
4. 核对不过 → 先修 doc 再 merge：doc 撒谎（过度声称 / 漏记 / Status 虚高）当场修正、commit、重新核对。禁止带着说谎的 doc 合进 main。

7.5b — Post-merge：记录已合入状态（在 Step 7 merge 之后）

⚠️ 切到持有 main 的 worktree 再 commit：gh pr merge --squash --delete-branch 之后你仍在 feature worktree 上。直接 commit 会落到已合并/已删的 feature branch（或留脏工作树让 Step 8 fail-closed abort）。而且 worktree 开发场景下 main 由主仓 worktree 持有——在 feature worktree git checkout main 会被 git 拒绝（ref 已被另一 worktree 占用）。所以切到持有 main 的 worktree（而非 checkout）：

# 找到持有 main 的 worktree（通常是主仓 cat-cafe/），cd 过去做 doc-sync：
MAIN_WT="$(git worktree list --porcelain \
  | awk '/^worktree /{wt=substr($0,10)} /^branch refs\/heads\/main$/{print wt; exit}')"
cd "$MAIN_WT" && git pull origin main   # 取回刚 squash 的 commit，doc-sync 落点切到 main

然后在 main 上把这个 PR 带来的增量写进 feature doc：

1. 更新 feature doc docs/features/F{NNN}-*.md：
   • Phase 状态：本 PR 对应的 Phase 标记从 📋/🚧 → ✅
   • AC 打勾：本 PR 实际完成的 AC 项 [ ] → [x]（只勾代码真做了的 —— 7.5a 已核对）
   • Timeline：加一行 | {YYYY-MM-DD} | Phase {X} merged (PR #{N}) |
   • Status 行：第一个 Phase 完成 spec → in-progress；最后一个 Phase 视情况推进（done 留给 completion 愿景守护）
   • 不做：不动 Dependencies/Risk/Links（kickoff/completion 的事）
2. Commit + push：在 main 上 git commit + git push origin main，message docs(F{NNN}): sync phase progress after PR #{N} merge（文档同步不需走 review）。
3. 复验：再跑一次 node scripts/check-feature-truth.mjs —— 确认 post-merge 写入没引入新 drift（例如加了 merged Timeline 却忘把 spec 推进成 in-progress，lint 会抓）。

落点说明：7.5b 切到持有 main 的 worktree（通常是主仓）做 doc-sync；后续 Step 8 清理本就从主仓发起（git worktree remove ../cat-cafe-{name}），此时已在 main worktree，其 git checkout main 幂等 no-op。单仓无独立 feature worktree 时 git worktree list 只返回主仓，cd 即原地。

检查清单：

• (pre) doc 标 ✅ 的 Phase / 打勾 AC 都有代码支撑（没撒谎）
• (pre) check-feature-truth 绿（无 status↔timeline drift）
• (post) 本 Phase 标 ✅ + 相关 AC 打勾
• (post) Timeline 有 merged 记录 + Status 行与实际进度一致
• (post) 复验 check-feature-truth 仍绿

Quick Reference

Common Mistakes

⚠️⚠️ 反面案例（PR #160）— 必须记住

错误行为：

• PR description 里签名写了 (@句柄)（在 HTML 注释里）
• 后续说明评论又写了 @句柄

后果：

• 触发了 chatgpt-codex-connector 的“Create an environment”自动回复
• remote review 没有实际执行，流程被噪声污染

硬规则（加粗执行）：

• PR body（含 HTML 注释）禁止出现任何 @句柄
• 只允许在专用触发 comment 里使用标准触发模板（见 refs/pr-template.md）

常见 QA（云端 Review 触发）

Q1: 出现 "Create an environment for this repo"，是不是 review 没权限？

不是。

⚠️ THIS IS NOT A REVIEW-PERMISSION ERROR. THIS MESSAGE IS ABOUT CODE-WRITE ENVIRONMENT PERMISSION.

最常见原因：comment body 里带了多行内容（SHA、审查标准、规则描述等），Codex connector 把它解析成了代码修改请求而非 review。即使第一行是 @codex review，附加描述在当前解析规则下仍会触发 code-write intent。

动作：只发 @codex review 一行重新触发（同 SHA 不需要新 commit）。

gh pr comment {PR_NUMBER} --body '@codex review'

教训演进：2026-04-18 曾以为是"后台 bug / 没接单"，2026-04-20 PR #1300 确认根因是详细格式触发 code-write 解析。极简格式是唯一可靠触发方式（PR #1258 + PR #1300 两次实战验证）。

Q2: PR 里看到小眼睛（👀）是什么意思？

小眼睛 = remote reviewer 已接单/已看到触发。

⚠️ EYES ICON MEANS "REQUEST RECEIVED", NOT "FAILED".

它不是失败信号，也不等于环境错误。后续是否通过，以 review comment / findings 为准。

Q3: 触发后多久需要再操作？

默认 不操作。

• 5 分钟后查一次 👀（Step 6.1）：有 👀 = 已接单，PR tracking 会自动通知，猫猫不用管
• 无 👀 = 云端没接到 → 允许 re-trigger
• 有 👀 的情况下严禁重复触发

Q4: remote reviewer 没猫粮了怎么办？

云端 Codex 的"代码审查"额度独立于总额度，可能单独耗尽。此时降级到其他猫做 完整 PR review（不是跳过 review！）：

铁律：降级后仍须校验"reviewer ≠ 作者"——降级表是建议顺序，不能覆盖 self-review 禁令。

⚠️ 共享 API 池陷阱（F238 教训）：同一 provider 的不同 model（Codex/GPT-5.4/GPT-5.5）共享 API 额度。降级必须跨 provider family（OpenAI → Anthropic），不能在同 provider 内换个体。

操作：gh pr comment {PR} --body "..." 用标准触发模板 @ 降级 reviewer（句柄查 cat-config.json）。

和其他 skill 的区别

• quality-gate: 自检（在 review 之前）
• request-review / receive-review: review 循环（在 merge 之前）
• 本 skill: review 通过后的合入全流程

下一步

合入后判断 feature 规模：

最后一个 Phase（或小 Feature） → 直接加载 feat-lifecycle completion（§17）：

1. 自己做愿景三问
2. 自动 @ 非 reviewer、非作者的猫做愿景守护（查 roster 动态选，不能 hardcode）
3. 守护猫放行 → close feat
4. 守护猫踢回 → 修改后重新走 quality-gate

中间 Phase（大 Feature，3+ Phase） → Phase 文档同步（Step 7.5 已做）+ 主动碰头operator：

1. 成果展示（截图 / demo / 关键改动）
2. 愿景进度（哪些 AC ✅ 了）
3. 下个 Phase 方向 + 新发现
4. "方向对吗？" → operator确认 → 继续下一个 Phase

CI Repair Loop (F253 Phase C)

When CI fails after push:

1. Read CI output → classifyCiError(output) (from scripts/classify-ci-error.mjs) → get error class + deterministic flag
2. If non-deterministic → escalate immediately (post to thread, @ author)
3. If deterministic + round < 2 → run autoFixCommand, commit, push
4. If deterministic + round ≥ 2 → escalate (same error class won't auto-fix after 2 tries)
5. Track round count via PR label ci-repair-round:N

Allowlisted auto-fixes: biome format, biome lint (non-suspicious) Never auto-fix: test failures, type errors, lint/suspicious, unknown errors

Use shouldAutoFix(classification, sameClassRound) to check the protocol. State machine: idle → attempt_1 → attempt_2 → escalated (terminal).

Open Source Teardown

明星项目拆解不是“读 README 做竞品分析”，而是宣传 claim → 源码证据 → 能力边界 → 我们的 tradeoff 的审计流程。

When to Use

触发：operator看到 PPT、博客、README、社区讨论后问“这个项目是不是很强？”；需要拆解 agent runtime、skill 系统、memory/RAG、MCP/gateway、RL/eval、插件架构等工程系统；或需要把一次竞品分析沉淀为 lesson / ADR / skill。

排除：只需要查公开资料或论文综述用 deep-research；只需要处理外部 issue/PR/intake 用 opensource-ops；还没有明确目标项目、只是在讨论方向用 collaborative-thinking。

灰例：如果用户同时要求“查社区 issue 情报 + 读源码”，先用本 skill 建代码证据骨架，再按需补 deep-research 或 opensource-ops。

Required Output

默认落盘：feature-discussions/YYYY-MM-DD-{project}-deep-dive/，包含 README、architecture-map、明星特性深挖、comparison、lessons/next steps。

最小合格产物必须包含：

• source repo URL、local path、commit SHA、更新时间。
• 宣传 claims ledger：claim / evidence files / verdict / caveat。
• 架构图或模块地图：entrypoints、state stores、extension points、empty dirs；用 ASCII tree 或 Mermaid，参考 (internal reference removed)。
• 明星特性深挖：每个特性都写到代码路径和运行链路。
• 算法剥皮表：真算法 / LLM judge / 启发式 / 规则 / 外部服务。
• Cat Café 对比：能学、不能学、我们因为 tradeoff 不 follow 的理由。

报告模板见 refs/report-template.md；八审计镜头 + 命令见 refs/teardown-method.md；用户视角第一性原理（第 9 镜头）见 refs/user-mind-evaluation.md。

进度纪律

• 分次推进：每只猫每次只做 1-2 份产物，commit 后传球，不一气呵成。
• 双视角交叉：架构/明星特性/合流/skill draft 至少跨两只猫完成。
• 对口 review：最终报告或 skill draft 必须由非作者猫 review，跨族优先。

Step 0 — 定边界和真相源

1. 记录用户原始问题和最关心的 claims。
2. search_evidence 查我们是否已有同项目/同类系统讨论、lesson、feature anchor；有矛盾就 flag。
3. clone 或 update 到 /home/user/projects/ref/{project}。
4. 记录 git rev-parse HEAD、最新 tag/release、git status --short。
5. 把 README/PPT/官网中的明星特性拆成 claims ledger。

不要先评价。先把“它声称自己有什么”列成可验证对象。

Step 1 — 架构地图

用 git ls-files、find . -type d -empty、rg 建第一版地图：

• entrypoints：CLI/server/worker/daemon/web。
• state stores：DB、files、cache、memory、lockfile、config。
• extension points：plugin/provider/adapter/registry。
• suspicious placeholders：空目录、TODO-only、docs-only 模块。
• community signals：高赞 issue、roadmap、真实 bug/feature 请求，验证宣传和用户痛点是否一致。

Step 2 — 明星特性逐个追链路

每个 claim 单独拆：

claim -> public API/command -> entrypoint -> core module -> state mutation -> future behavior

如果 claim 说“self-improving / learns / evolves”，必须画：

signal -> decision -> state mutation -> future behavior

断一环，就只能写“有 UX/telemetry/CRUD”，不能写“闭环进化”。

Step 3 — 算法剥皮

把被宣传成“算法”的点分栏：真算法 / LLM judge / 启发式 / 规则 / 外部服务。

硬规则：

• LLM prompt judge 不是算法，除非有独立 eval、score、threshold、rollback。
• Hash update 不是知识过期。
• Usage dashboard 不是生命周期治理。
• Reward 只说明 reward 覆盖的任务类型，不自动证明开放任务能力。

Step 4 — 反馈链和评价主体

检查谁在判断“更好”：

如果项目把三层都压给同一个模型自评，要明确写风险：它可能能沉淀步骤，但不能证明质量提升。

Step 5 — 和 Cat Café 对比

不要写“我们有/没有”流水账。每个维度都写价值函数：

• Learn：立刻值得学的工程手法。
• Gap：我们承认缺口，需要立项或排优先级。
• Do Not Follow：我们不做，并写清哲学理由。

Step 6 — 沉淀

1. 把候选 lesson 写进报告，不直接改全局 lesson，等operator确认。
2. 如果形成稳定方法论，更新本 skill 或相关 skill。
3. docs 产物 commit + push；如果是新 skill，还要跑 pnpm check:skills 和 pnpm sync:skills。

Common Mistakes

和其他 Skill 的区别

• deep-research：多源资料调研；本 skill 是源码优先的能力审计。
• opensource-ops：社区 issue/PR/intake；本 skill 是项目架构和宣传真实性拆解。
• expert-panel：多猫观点碰撞；本 skill 是固定产物和检查项。
• writing-skills：写 skill 的质量纪律；本 skill 可产出候选 skill，但写入时仍要加载 writing-skills。

下一步：工程/产品决策 → collaborative-thinking 或 feat-lifecycle；新 skill/修改 skill → writing-skills；外部社区情报 → deep-research 或 opensource-ops。

Organize Threads

用户请求整理未分类 thread 时加载此 skill。分析 thread 标题和元数据，对照可用标签建议分类。

流程

1. 获取数据
   - 用 cat_cafe_list_labels 获取可用标签列表（id + name + color）
   - 用 cat_cafe_list_threads 获取 thread 列表
   - 如果用户触发消息中已附带标签和 thread 数据，优先使用（减少工具调用）
   - 筛选出未分类 thread（labels 为空或不存在的）

2. 分析 thread
   - 逐个分析 thread 标题
   - 语义匹配：标题含义和标签含义的对应（不是简单 substring）
   - 一个 thread 可匹配 0-N 个标签
   - 无法判断的 thread 不强行分类

3. 输出建议
   - 按 thread 逐条列出建议的标签
   - 简要说明匹配理由（一句话）
   - 附带机器可读 JSON 块（供前端 modal 预填充）
   - 不自动应用——等用户在 modal 中确认

输出格式

有标签时（标准格式）

当触发消息列出了可用标签，使用标签 ID：

## 分类建议

| Thread | 建议标签 | 理由 |
|--------|----------|------|
| {title} | {label names} | {一句话说明} |

<!-- SUGGESTIONS_JSON:{"threadId1":["labelId1","labelId2"],"threadId2":["labelId3"]} -->

key = threadId，value = labelId 数组。必须使用 id 而非 name。

无标签时（扩展格式）

当触发消息说明"当前没有任何标签"，先建议标签体系再分类：

## 建议标签体系

| 标签名 | 颜色 | 说明 |
|--------|------|------|
| {name} | {color} | {一句话说明用途} |

## 分类建议

| Thread | 建议标签 | 理由 |
|--------|----------|------|
| {title} | {label names} | {一句话说明} |

<!-- SUGGESTIONS_JSON:{"newLabels":[{"name":"标签名","color":"#hex"}],"assignments":{"threadId1":["标签名"]}} -->

newLabels = 建议创建的标签（名称+颜色），assignments = 每个 thread 建议的标签名数组（用名称不用 ID，因为标签尚未创建）。前端会在用户确认后自动创建标签并应用。

注意事项

• 有标签时只用已有标签，不发明新标签
• 无标签时建议 3-8 个标签，颜色用十六进制，名称简短
• 标题信息不足时，跳过该 thread（宁缺勿滥）
• 最多处理 50 个 thread（避免消息过长）

Pencil Design — .pen 文件设计与代码导出

核心知识

Pencil 是装在 Antigravity IDE 上的设计扩展。 .pen 文件是加密格式，只能通过 Pencil MCP 工具读写，Read/Grep/cat 无法解析。

配置要求：MCP 配置必须加 --app antigravity（不是默认 IDE）。

SOP 位置

feat-lifecycle → Design Gate → **pencil-design** → writing-plans → worktree → tdd

pencil-design 在 spec 确认后、写代码前。先把 UX 做对，再动手写代码。

可观测性 / 状态 / 失败相关 UI 必读：动手画之前先过 Design Gate 的 现场可感知性自检（cat-cafe-skills/refs/in-context-observability-checklist.md）。Cat Café 的可观测性哲学是"明厨亮灶"——in-context 富块 + entity 自带状态点优先于 dashboard。否则容易画成上个世纪的 stats card 被打回（F174 D2b 教训）。

🔴 风格一致性门禁（Style Consistency Gate）

这是最重要的规则。 在创建任何新设计之前，必须完成以下步骤：

Step 1: 分析现有 UI

如果要设计的功能是已有产品的扩展（如给 Mission Hub 加新 Tab）：

1. 截图现有 UI — 用 Read 工具查看产品截图，或在浏览器中截图
2. 提取风格特征 — 记录以下 token：
   • 配色方案（背景色、主色、强调色）
   • 布局模式（列表/卡片/详情面板、Tab 结构）
   • 间距和圆角
   • 字体层级
3. 写入设计约束 — 在 batch_design 前明确："延续 X 风格"

Step 2: 判断设计类型

Step 3: 风格验证

设计完成后，get_screenshot 截图，然后和现有 UI 截图并排对比：

• 配色一致？
• 布局语言一致（Tab/列表/详情面板）？
• 不会让用户觉得"换了个产品"？

踩坑教训 (F076)：给 Mission Hub 做面板时用了深色 command-center 风格，和现有暖色调 Mission Hub 完全不搭，operator experience"不能说一模一样，只能说毫不相关"。被否决后全部重做。

两种模式

Mode A：Design — 创建/编辑 .pen 文件

用 Pencil MCP 工具操作设计画布：

关键限制：

• batch_design 每次最多 25 ops，超出必须分批调用
• Binding（绑定引用）不能跨 batch_design 调用复用
• MCP 配置改动需等下次调用才生效（无头模式）

🔴 .pen 文件管理规则：

• 每个 feat 一个 .pen 文件 — 用 open_document("new") 新建，不要在其他 feat 的 .pen 文件上修改
• 不能修改其他猫/feat 的设计稿 — 只读参考可以（batch_get + get_screenshot），但不要 batch_design/Update/Delete 别人的节点
• 保存需要operator — open_document("new") 创建的文件不落盘，猫猫无法自行保存。设计完成后：
  1. 告诉operator完整保存路径：{项目根目录}/designs/{文件名}.pen
  2. 路径用 git rev-parse --show-toplevel 动态获取项目根目录，不要硬编码绝对路径
  3. 文件命名规范：{feat-id}-{描述}.pen（如 F096-interactive-rich-blocks-ux.pen）
  4. operator保存后，需要 commit + push 到 main（设计稿是共享状态文件）
• 保存后验证 — operator确认保存后，用 open_document("{完整路径}") 打开验证内容完整

Mode B：Code Export — 从 .pen 设计稿生成代码

1. 用 get_editor_state + batch_get 读取设计属性
2. 用 get_style_guide 获取设计 token（颜色、字体、间距）
3. 生成 React + Tailwind 组件代码
4. 截图对比：get_screenshot → 目视验证还原度

工作流

设计任务
  ↓
现有 UI 截图分析（扩展型设计必须！）
  ↓
get_editor_state（了解画布现状）
  ↓
get_style_guide_tags + get_style_guide（仅全新设计）
  ↓
Mode A: batch_design（分批，≤25 ops/次）
Mode B: batch_get → 生成 React/Tailwind
  ↓
get_screenshot（验证）
  ↓
和现有 UI 对比 → 风格一致？
  ├─ 不一致 → 修正配色/布局后重新 batch_design
  └─ 一致 → 请operator保存
       ↓
       告诉operator完整路径（git rev-parse --show-toplevel + /designs/Fxxx-xxx.pen）
       operator Cmd+S 保存 → commit push 到 main
       ↓
       operator/设计负责人 review 设计截图
       ├─ 否决 → 记录反馈 → 回到 batch_design 修正
       └─ 通过 → 如需实现 → worktree → tdd

Common Mistakes

和其他 Skill 的区别

• tdd / worktree：代码实现阶段 — pencil-design 是设计阶段，先于代码
• quality-gate：检查代码合规 — pencil-design 输出的是设计文件或组件代码

下一步

• Mode A 完成设计 → 告知operator完整保存路径 → operator Cmd+S 保存 + commit push → 设计 review → 如需实现 → worktree → tdd
• Mode B 导出代码 → 进入 tdd 编写测试 + 集成

PPT Forge — 低保真 MD → AI 精美图

核心原则

架构猫写蓝图，imagegen 猫出精美图。 不走 HTML/SVG 手工合成。

• 架构猫（当前持球猫）：内容分析 + 分页规划 + 低保真 MD 写作
• imagegen 猫（imagegen 猫/云端 Codex）：逐页生成精美 raster PNG
• operator：审稿 + 确认风格

产出是 AI 原生图片——视觉质量远高于 HTML/CSS 手工画，且速度快。

开局参数（必须声明）

没有开局参数 = 分页和风格无标准。开工前先锁。

场景路由

场景 1-2: 低保真 MD 写作

详细规范：ppt-lofi-authoring.md

写作流程

1. 内容分析：读完全部原始内容，识别：

   • 核心板块（几个大的独立主题）
   • 关键数据点（有冲击力的数字）
   • 可图表化的逻辑链（流程/对比/层级）
   • 信息层级（总→分）

2. 分页规划：确定每页的类型和内容分配

   • 页面类型：封面 / 总览 / 详情 / 方法论 / 路线图 / 总结
   • 先给operator看分页表，确认再动手写

3. 风格锁定：选择风格 preset，配色方案一次锁定

4. 低保真 MD 写作：每页一个 section

   • ASCII art 结构图（用 box drawing 字符画清布局）
   • 视觉指引（给 imagegen 猫的文字描述）
   • 数据高亮方式标注

5. 精美图生成指引：末尾写总体风格规范 + 逐页清单表格

低保真 MD 文件结构

---
title: "PPT 标题 — 低保真稿"
created: YYYY-MM-DD
author: "[签名]"
doc_kind: diagram
status: lofi-draft
---

# 标题

> **受众**：...
> **风格**：...
> **视觉**：一行配色方案
> **页数**：N 页
> **原则**：...

## P1：封面
（ASCII art + 视觉指引）

## P2：总览
（ASCII art + 视觉指引）

...

## 精美图生成指引（给imagegen 猫）
（配色方案 + 字体风格 + 密度原则 + 逐页清单）

场景 4: imagegen 出图交接协议

发给 imagegen 猫时说清：

1. 低保真 MD 文件路径（不贴全文，太长）
2. 逐页生成：每页一张独立图片
3. 输出位置：同目录 assets/ 子目录
4. 技术要求：
   • 原生 imagegen 直出 raster PNG
   • 不用 SVG / HTML 手工合成（出来贼丑）
   • 每页命名：p{N}-{简短描述}.png
5. 内容约束：
   • 严格遵循配色方案，不自由发挥
   • 文字内容以低保真 MD 为准，不删不加

场景 5: 交付

• 图片生成完成后，打包到 assets/ 子目录
• 用 media_gallery rich block 或直接展示给operator
• 说清每页对应关系

风格 Preset

需要新风格时，参照 ppt-style-huawei.md 格式新建 ref。

成功案例

Common Mistakes

和其他 Skill 的关系

• image-generation：通用图片生成 — ppt-forge 是 PPT 专用流程
• expert-panel：多猫分析报告 — ppt-forge 是做 PPT
• tech-writing：写文档 — ppt-forge 做演示文稿（视觉优先）

SOP 位置: 本 skill 是 sop-definitions/development.yaml stage quality_gate 的执行细节。 SOP definition: sop-definitions/development.yaml stage quality_gate。 上一步: impl stage | 下一步: fresh-context-review（可选）→ request-review（review stage）

Quality Gate

开发完成到提 review 之间的双重关卡：对照 spec 自检 + 用真实命令输出证明你的声明。

核心知识

两条铁律合一：

1. Spec alignment（来自 spec-compliance-check）：AC 可能写偏，先回读原始需求，再逐项验收
2. Evidence before claims（来自 verification-before-completion）：没有运行命令、没看到输出，就不能说"通过了"

铁律：NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

自问："我是这次真的运行了命令并看到输出，还是我只是相信它能工作？"

为什么 AC 可能不够：AC 是人写的，可能遗漏 UX 要求或场景覆盖。F041 教训：AC 全打勾，但operator的原始需求（能力显示描述、多项目管理）根本没进 AC——spec compliance check 检查了 AC，但 AC 本身就是错的。

流程

BEFORE 声称完成 / 提 review:

Step 0: VISION CHECK（愿景核对）
  ① 找原始 Discussion/Interview 文档（operator experience在里面）
  ② 读核心痛点："我要..."、"我不想..."
  ③ 问自己：operator坐在 Hub 前用这个功能，体验是什么样的？
  ④ AC 是否完整覆盖了operator的原始需求？
     → 如有遗漏，先补 AC 再继续

Step 0.5: DELIVERY COMPLETENESS CHECK
  ① 这次交付的是完整 feat 还是 feat 的一部分？
     → 完整 feat：继续
     → 部分：有operator明确同意分批交付的记录吗？没有就继续做完
  ② 本次产出后续需要"重写"还是"扩展"？
     → 扩展：通过
     → 重写：如果是已标注 Spike 且有结论，通过；否则不通过，回去重做

Step 1: FIND — 找 spec/plan 文档
  - the active feature spec or implementation plan
  - 同时找 Discussion/Interview（operator experience所在）

Step 2: CREATE — 建检查清单
  - 列出每一个 AC / 功能点 / 边界条件
  - 列出 Discussion 里的 UX 描述和场景

Step 2.5: CLOSE GATE MATRIX + FOLLOW-UP TAIL SCAN（F177 Phase A）🔴
  - 检查 CloseGateReport 是否已生成（schema: `cat-cafe-skills/refs/close-gate.md`）
  - 每个 unmet AC 是否三选一处置（immediate / delete / cvo_signoff）
  - **Follow-up tail scan**：扫以下文本来源，命中阻塞关键词 = BLOCKED：
    - 来源：close report、PR body、commit messages、spec 中 AC 注释、review 反馈回复
    - 阻塞关键词（不区分大小写）：
      `follow-up` `followup` `deferred` `next phase` `next PR` `P2` `stub` `TD`
      `后续` `留个尾巴` `先这样` `下次一定` `回头` `以后再` `will address later`
      `out of scope`（作为 close 借口时）`MVP 先上`（作为 close 借口时）
    - 豁免：spec 的 Why/Risk/History 章节中引用历史上下文时使用这些词不触发
  - cvo_signoff 四件套完整性验证（proposal + cvo message + quote + scope）
  - 🔴 **47 盲审规则**（F177 Phase B）：若 PR 作者是 opus-47，quality-gate 必须由对家猫执行（Maine Coon优先，46 兜底）。审核者由 reviewer/系统指定，47 无选择权，47 的自评不计入放行判据
  - 🔴 **hotfix 自检禁止**（F177 Phase E）：执行 `node scripts/check-hotfix-pattern.mjs`，若检测到 hotfix 模式，作者不得自行通过 quality-gate——必须由另一只猫执行 quality-gate。原因：hotfix 心态容易自我说服"够用了"，跨猫审视打破惯性
  - 🔴 **Ragdoll search→Read 检查**（F177 Phase F）：若执行者是Ragdoll家族（46 / 47 / 4.5 / Sonnet），检查本次 session 的 search 行为：
    1. 有 `search_evidence` 调用命中 doc anchor（高/中置信度）吗？
    2. 命中后有对应的 `Read` 调用去读源文件吗？
    3. 输出中包含精确数字/版本号/日期但没有 Read 证据吗？
    → 三条件同时满足 = **BLOCKED**："这个精确结论你 Read 源文件了吗？摘要是索引不是答案。"
    → 豁免：架构方案/假设性讨论（不含精确数字的推理不触发）；通过 Grep/LSP 获取的精确信息不触发
  - 🔴 **Siamese edit scope 检查**（F177 Phase C）：若 PR 作者是Siamese，检查改动文件是否超出白名单（designs/ docs/ assets/ 根目录.md）。碰 packages/ src/ 的改动必须有对应 handoff 记录或 Dry Run Gate 通过证据（build + test pass）

Step 2.6: FALLBACK LAYER CHECK（F177 Phase D）🔴
  - 执行：`node scripts/check-fallback-layers.mjs` 扫描 PR diff
  - 同一文件新增 ≥3 层 fallback 或累计 ≥5 层 → 触发坐标系自检
  - 自检三问：①修坐标系还是补错误坐标系？②坐标变换能否消除？③每层为什么不能去掉？
  - 层数合理时在报告中说明理由；不合理时重构后再过 gate

Step 2.7: ARCHITECTURE OWNERSHIP REPORT（F191，warning-only）🔴
  - 执行：`pnpm check:architecture-ownership`
  - 从 spec / plan 抄入：
    `Architecture cell` / `Map delta` / `Why`
  - 若缺失，报告 `⚠️ missing` 并列为 review focus；不在 quality-gate 做 semantic hard block
  - 若 `Map delta: none` 但 diff 明显新增 `Store|Queue|Router|Adapter|Dispatcher|Binding` 等架构名词，报告 mismatch 给 reviewer
  - 若 `Map delta: update required|new cell required`，报告对应 ownership cell / new cell 文件是否随 PR 更新
  - 注意：quality-gate 只报告机械可见事实；架构语义正确性由 Design Gate + reviewer 判断

Step 3: VERIFY — 逐项检查
  - 代码在哪？有测试覆盖？边界处理了？
  - 🔴 F244 Tips Contribution：若本 PR 新增/修改 user-visible feature / capability / guide / harness behavior，
    必须满足其一：
    ① `packages/web/src/lib/capability-tips.seed.json` 有对应 `sourceRef` tip
    ② 相关 feature/guide/skill 文件写明 `tips_exempt: {reason}`
    并执行 `pnpm check:capability-tips`。
    注意：CI 只证明结构/anchor/action；reviewer 仍要退回只复述标题、没有动作或时机的废话 tip。
  - 🔴 交付物必须核实 commit/PR 状态（git log --grep + gh pr list）
    spec checkbox 是记录工具，不是真相源（LL-029）
  - 🔴 新增 MCP 工具 → 认知入口更新了吗？优先级：MCP tool description → 相关 skill refs → capability wakeup / L0 quick index；只有 legacy/fallback surface 仍依赖时才补 `MCP_TOOLS_SECTION`（F086 教训：造了工具猫不知道；F203 后不再默认塞 SystemPromptBuilder）
  - 🔴 新增行为规则 → governance digest / shared-rules 注入更新了吗？
  - 🔴 产出了 SKILL.md 或改了 MCP tool description → 加载 `writing-skills`，用 T0 六要素审查质量（软硬同检）

Step 4: RUNTIME GUARD — 前端证据采集前先做运行态保护
  - 若会话在 `cat-cafe-runtime`，先探活：`curl -sf http://localhost:3004/health`
  - 服务已在线时直接复用，禁止在该会话执行 `pnpm start` / `pnpm runtime:start` / `./scripts/start-dev.sh`
  - `localhost:3003/3004` 默认按 runtime 处理；如果你要验证未合入改动，不能把这两个端口的页面/接口响应当成当前分支的证据
  - 证明“这是我当前 worktree 的验证证据”时，必须同时说清：`worktree/cwd` + 目标 URL。两者对不上 = 证据无效
  - 确需重启时，先获operator明确授权，再用 `CAT_CAFE_RUNTIME_RESTART_OK=1` 执行
  - **Alpha 优先**：验证已合入 main 的改动时，优先用 `pnpm alpha:start`（3011/3012/4111/6398）取证，而非 runtime。Alpha 环境每次启动自动同步 origin/main

Step 4.5: DOGFOOD-YOUR-SLICE — 用一次自己刚做的功能（F209 教训 2026-05-23）🔴
  对 user-visible / runtime feature，author 必须在请求 review 前：
    ① 跑一条**真实端到端 query / 路径**，涵盖该 slice 的核心交付能力
    ② 把命令 + 输出 / 截图证据写进 Quality Gate Report 的 "Dogfood" 块
    ③ 抓到的任何 dogfood bug 必须当轮修，不允许"post-merge 再说"

  Scope（必做 vs 可豁免）：
    - **必做**：任何对最终用户 / 猫体感有变化的 feature 或 bugfix。包括但不限于：
      search / recall / UI / routing / drillDown / typed reader / 任何新 MCP tool / 任何新 REST 端点 /
      **任何修复用户或猫可感知路径的 bugfix（即使已有回归测试覆盖）**
      → 反例 PR #1854 dogfood hotfix：file-slice drillDown 路径口径不一致，已有回归测试也不够——
        必须 author 自己跑一遍 `search_evidence → drillDown → read_file_slice` 才能抓到
    - **可豁免**：docs-only / 纯重构 / 纯测试 / 内部基础设施 / **纯内部 bugfix（非 user/cat 可感知路径，如内部 DB 一致性、log format、纯算法常量调整等）**
      → 豁免必须**显式在 review packet 里写出理由**（"docs-only" / "纯重构 + 既有测试覆盖" / "纯内部 bugfix，不影响 user/cat 可感知路径"等），不能省略

  Why（F209 反思 2026-05-23）:
    "AC pass 但用户感受不到" + "dogfood bug post-merge 才暴露" 是同型走偏。
    - Phase B alias registry: AC-B1~B5 全 ✅、跨族 review APPROVE、merge 闭环 — 但生产 `entity_registry` 是空的，真实用户搜 `operator` 找不到 `operator`。
    - Phase C drillDown: 测试 / cloud review / merge 都过 — 但 author 自己 post-merge 用一次刚发现 file-slice 路径口径不一致。
    根因是没人 pre-review 真用一次自己刚做的东西。pre-merge dogfood 把这一类 bug 提前到 author 自检阶段。

  报告写法（在 Quality Gate Report 里加 "### Dogfood" 块）：
    ```markdown
    ### Dogfood-Your-Slice
    Scope verdict: ✅ 必做 / 🆗 可豁免（理由：xxx）

    （必做时）
    端到端路径: search_evidence("operator") → drillDown → cat_cafe_get_thread_context
    实际命令 / 输出（粘贴）: ...
    发现的 bug: 无 / 列表（含修复 commit SHA）
    ```

Step 5: PEN CHECK — 自动化设计稿对照（不可跳过！）
  ① glob designs/**/*.pen，匹配当前 feat 编号或关键词
  ② 若匹配到 .pen 文件 → 强制进入设计稿对照流程（见下方"有 .pen 设计稿的功能额外要求"）
  ③ 若无匹配 → 检查 feat 是否有前端 UI 改动（改了 packages/web/src/components/）
     → 有 UI 改动但无 .pen → 在报告中标注"⚠️ 无设计稿，跳过对照"
  ④ 此步骤不依赖猫猫"记得"——必须执行 glob 命令，用输出决定是否进入对照

Step 6: RUN — 运行验证命令（必须这次真实运行）
  pnpm test                              # 必须全部通过
  pnpm lint                              # 0 errors
  pnpm check                             # 0 errors（biome 格式 + lint）
  pnpm -r --if-present run build         # exit 0
  # Redis 相关改动额外跑：
  pnpm --filter @cat-cafe/api test:redis
  # ⚠️ pnpm check 包含 biome format + lint 规则。
  # 如果有 format 问题，先跑 pnpm check:fix 自动修复。
  # 不能带着 biome errors 提 review！（2026-03-12 operator定调）

Step 7: READ — 完整读输出，看 exit code，数失败数

Step 7.5: ARTIFACT HYGIENE CHECK — 根目录媒体垃圾闸门
  - 执行（工作树）：
    `git status --short | rg '^.. [^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`
  - 执行（已提交差异）：
    `git diff --name-only origin/main...HEAD | rg '^[^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`
  - 任一命中 → BLOCK：说明仓库根目录出现了媒体/设计工件（含已跟踪和未跟踪）
  - 处理方式：移到 `${TMPDIR}/cat-cafe-evidence/...` 或显式归档到正式目录后再继续
  - 规则真相源：`cat-cafe-skills/refs/evidence-output-contract.md`

Step 8: REPORT — 输出合规报告 + 证据

前端功能额外要求：≤3 张截图 + 1 段 15s 录屏，附"需求 → 截图"映射表。 执行细则：cat-cafe-skills/refs/vision-evidence-workflow.md。

有 .pen 设计稿的功能额外要求 🔴（Step 5 匹配到 .pen 时强制执行）：

1. 打开 .pen 文件 → get_screenshot 截取设计稿
2. Playwright/Chrome 打开实际页面 → 截取实现截图
3. 逐区域对比：布局、颜色、间距、交互状态
4. 不一致处必须标注并修复（或记录为"有意偏差 + 原因"）
5. 报告附 设计稿截图 vs 实现截图 对照表
6. 🔴 此流程由 Step 5 自动触发，不依赖猫猫主动想起来

教训（2026-03-11）：三只Ragdoll同时跳过了 .pen 对照，根因是没有自动化检查点。 Step 5 的 glob 就是解决这个问题——用命令输出驱动，不靠记忆。

Quick Reference

合规报告模板：

## Quality Gate Report

Spec: feature spec or implementation note
原始需求: feature-discussions/YYYY-MM-DD-xxx/README.md
检查时间: YYYY-MM-DD HH:MM

### 愿景覆盖（Step 0）
| # | operator原始需求 | AC 覆盖？ | 实现？ |
|---|---------------|-----------|--------|
| 1 | "我要 XXX"    | AC#3      | ✅     |

### 功能验收
| # | 要求 | 状态 | 代码位置 | 测试覆盖 |
|---|------|------|----------|----------|
| 1 | XXX  | ✅   | file.ts:L10 | test.spec.ts |

### 设计稿对照（Step 5）
glob designs/**/*.pen 匹配结果: [列出匹配文件或"无匹配"]
对照状态: ✅ 已对照 / ⚠️ 无设计稿（有 UI 改动）/ ➖ 无 UI 改动

### Artifact Hygiene（Step 7.5）
仓库根目录媒体/设计工件（工作树 + 已提交差异）: 无 ✅

### Architecture Ownership（Step 2.7）
Architecture cell: dispatch
Map delta: none
Why: 只扩展现有 InvocationQueue 行为，不改变 dispatch cell 边界
Diff mismatch scan: 无新增并行 Store/Queue/Router/Adapter ✅

### Dogfood-Your-Slice（Step 4.5）
Scope verdict: ✅ 必做 / 🆗 可豁免（理由）
（必做时）端到端路径: search_evidence("...") → drillDown → reader(...)
实际命令 / 输出 / 截图: ...
发现的 bug: 无 / 列表（含修复 commit SHA）

### 验证命令输出（必须是这次真实运行）
pnpm test → 34/34 pass ✅
pnpm lint → 0 errors ✅
pnpm check → 0 errors ✅ (biome format + lint)
pnpm -r --if-present run build → exit 0 ✅

Common Mistakes

Red flags — 立刻 STOP：

• 用 "should"、"probably"、"seems to"
• 表达满足感（"好了！"、"完成！"）时还没运行命令
• 信任 subagent 的 "success" 报告而没独立验证

和其他 skill 的区别

一句话：quality-gate 是"你自己检查自己"，merge-gate 是"reviewer 放行你"，receive-review 是"你处理 reviewer 的意见"。

下一步

Quality Gate 通过后：

1. （可选）加载 fresh-context-review — 非 trivial PR（≥3 files, ≥50 行 diff）推荐；trivial 跳过。Author 自判。详见 fresh-context-review skill 触发决策表。
2. 加载 request-review skill 请求正式 review（SOP stage review）。

不要停下来问operator"要不要继续"（§17）。

Gate 未通过时：

• P1 遗漏 → 补完再过 gate
• P2 遗漏 → 必须当轮补完再提 review
• 测试 / lint / build 失败 → 修到绿灯再提

SOP 位置: 本 skill 是 sop-definitions/development.yaml stage review 的反馈处理执行细节。 上一步: request-review | 下一步: merge-gate

Receive Review

处理 reviewer 反馈的完整流程。核心原则：技术正确性 > 社交舒适，验证后再实现，禁止表演性同意。

触发入口

收到 github-review-feedback 通知时，按下面的核心知识处理——不区分来源，只区分反馈类型。

自动触发处理（F140 Phase B）

当 github-review-feedback connector 唤醒你时：

1. 读取通知内容，识别 review decision 类型
2. CHANGES_REQUESTED → 直接进入下方 Red→Green 流程
3. APPROVED → 不需要 receive-review，检查是否可以走 merge-gate
4. COMMENTED → 判断是否需要代码修改，需要则进入 Red→Green 流程
5. 处理完成后通知operator结果（KD-13: 事后通知）

详见 refs/pr-signals.md Phase B 自动响应行为。

核心知识

两类反馈，处理方式不同

愿景级反馈不能用代码 patch 修补设计问题。 先对照operator experience验证 reviewer 说得对吗；如确实偏离，升级operator确认偏差范围，再重新设计。

Reviewer Delta Annotation（F253 AC-B2）

当 review request 附有 Fresh-Context Findings 节时，reviewer 在自己的 findings 中标注 delta tag，量化 cross-model review 增值：

Annotation 格式：在 finding 行末加 tag

P2-1: 边界条件未处理 — src/foo.ts:42 [FC:covered]
P1-1: Race condition in concurrent writes — src/bar.ts:18 [FC:new]
P3-1: 建议重新考虑整体架构方向 [FC:N/A]

注意：

• 标注是 lightweight annotation，不增加 review 流程摩擦
• Review request 无 Fresh-Context Findings 节时（未触发 fresh-context），不标注
• Delta 数据自然累积在 review 记录中，Phase C eval:qc 聚合分析
• 标注不影响 finding 的 severity 判定或处理流程

禁止的响应（表演性同意）

❌ "You're absolutely right!"    ❌ "Great point!"
❌ "Excellent feedback!"         ❌ "Thanks for catching that!"
❌ "让我现在就改"（验证之前）

行动说明一切——直接修复，代码本身证明你听到了反馈。

Push Back 标准

当以下情况时必须 push back，用技术论证，不是防御性反应：

• 建议会破坏现有功能
• Reviewer 缺少完整上下文
• 违反 YAGNI（过度设计）
• 与架构决策/operator要求冲突
• 建议会让实现更偏离operator原始需求

如果你 push back 了但你错了：陈述事实然后继续，不要长篇道歉。

Fallback 层数检测（F177 Phase D）🔴

Review 代码时，自动执行 node scripts/check-fallback-layers.mjs 检测 fallback 模式增长。 同一文件新增 ≥3 层 fallback → 触发坐标系自检（三问）：

1. 这个 fix 是在修坐标系，还是在给错误坐标系打补丁？
2. 能否用坐标变换（换一个问题分解方式）消除这些 fallback 层？
3. 每一层 fallback 为什么不能去掉？

review 报告中必须包含 fallback 层数分析结果。

Review 有零分歧 = 走过场（反顺从规则）。真正的 review 需要技术争论。

流程

WHEN 收到 review 反馈:

1. READ  — 完整读完，不要边读边反应。**R2+ 时额外动作**：回看上轮 finding 列表，标注每个 finding 的 failure-mode 类型，用于 AUDIT 步骤的同型判别
2. CLASSIFY — 区分愿景级 vs 代码级；按 P1/P2/P3 分优先级
3. CLARIFY — 有不清晰的问题先全部问清，再动手
4. VERIFY — reviewer 说的问题真的存在吗？（见下方三道门）
5. AUDIT — failure-mode sweep（见下方 §16e 判别）
6. FIX — 通过验证的问题 + audit 发现的同类问题 Red→Green 修复
7. CONFIRM — 修完回给 reviewer 确认，不能自判"改对了"

VERIFY 三道门（少一道不准照改）

对每条 review 意见，改代码之前必须过三道门：

1. Spec Gate — 这条意见和现有 AC/需求冲突吗？
   • 冲突 → pushback，附 AC 原文
   • 不冲突 → 进下一道
2. Mechanism Gate — reviewer 说"这不行"的证据是什么？
   • 有失败用例 / 真实平台限制 → 进下一道
   • 只是"不优雅"/"理论上不安全"但拿不出失败路径 → 当假设处理，pushback 要求证据
3. Feature Gate — 按建议改完后，核心用户路径还活着吗？
   • 改完跑一遍最关键的用户路径（不是只跑测试）
   • 功能死了 → 回滚，review 建议作废，不管它理论上多优雅

特别注意：remote reviewer（Codex cloud）没有运行环境，判断基于静态分析和理论推理。你有本地环境 → 你的实测证据 > 他的理论推理。

修复顺序：P1（blocking）→ P2（必须修）→ P3（讨论后当场修或放下，不记 BACKLOG）

澄清原则：有任何问题不清晰，先 STOP，全部问清再动手。部分理解 = 错误实现。

AUDIT — Failure-Mode Sweep（shared-rules §16e）

VERIFY 完所有 findings 之后、动手修之前，做一次 failure-mode 判别：

判别问：这些通过验证的 P1/P2 里，有没有 ≥2 个属于同一类 failure mode？（边界遗漏、null 不安全、错误处理不一致、状态转换缺路径、类型假设不安全……）

• 有 → 做 failure-mode audit 再修：
  1. 抽象：一句话说清它们违反了什么不变量
  2. 扫描：带着这个不变量 grep 本 PR diff 里所有同类位置（sibling call sites、同性质边界群）
  3. 防护：能否加类型/封装/测试让它不可能再违反
  4. 自报告：audit 结果写进修复确认信，让 reviewer 不用下轮再 grep 同型
• 没有（全是独立、不同类的点问题）→ 跳过 audit，直接进 FIX

R2+ 额外检查：如果本轮的 finding 和上轮是同型——不管数量多少，强制 audit。同型第二次出现 = author 上轮没泛化，这次必须补上。

≥3 轮升级规则（F229 PR-A1 20 轮教训）🔴：同一状态对象的 finding 连续 ≥3 轮出现（哪怕每轮都"修好了"）= 不是你修得不对，是 plan/spec 层欠状态机的边——代码层 audit 扫不出"spec 没定义 restore boundary"这种上游缺失。停手，@ plan/spec 作者按 writing-plans「Stateful Object Gate」补状态转移表 + 不变量，补完再继续修。别一个人打到 R20（PR #2202：实现猫每轮诚实修好当轮 finding，但缺这个升级出口，20 轮才合入）。

为什么在 FIX 之前：先 audit 再修 = 一次修完所有同类；先修再 audit = 改了一个又发现三个，反复 rebase。

Red→Green 修复流程

对每个 P1/P2 问题：

Step 0: 创建修复任务（F160 Phase C — 在动手修之前） 调用 cat_cafe_create_task 为每个 P1/P2 创建独立跟踪任务：

• title: [P{N}] {问题摘要}（如 [P2] TaskComposer HTTP 错误时丢失输入）
• why: reviewer 的原始描述（≤120 字）
• 修复完成后 cat_cafe_update_task 状态改为 done

Gotcha: 不要为 P3 创建任务——P3 当场修或放下，不记 BACKLOG 也不记毛线球。

1. 理解问题
2. 写失败测试（Red）
3. 运行测试，确认红灯
4. 修复代码
5. 运行测试，确认绿灯（Green）
6. 运行完整测试套件，确认无 regression

例外：如果无法稳定自动化复现，提供最小手工复现步骤 + 说明原因，但不能跳过验证结论。

修复后确认（硬规则）