anti-hallucination

name	anti_hallucination
description	日常编码的防幻觉安全网。当用户要改代码/修 bug/加小功能/重构/理解代码，且任务规模为小修小补（不走完整 SDD 规约链）时使用。6 步流程：定位起点→建立上下文→压缩→对齐确认→可选 log 调试→提方案。核心：索引先于动手，读到再用，禁止编造，方案先确认。触发场景与完整关键词见正文。
task_type	dev.anti_hallucination

反幻觉工作流（anti_hallucination）

核心原则：索引先于动手，读到再用，禁止编造，方案先确认。

适用于日常小修改任务。中大型功能仍走 task_closure 的 SDD 规约链（grill-me→spec→plan→tasks→implement）。

任务类型识别

• Bug 模式：用户描述异常/报错/行为不符预期
• 需求模式：用户要求新增小功能/修改行为
• 重构模式：用户要求重命名/拆分/合并/抽取/迁移
• 理解模式：用户只想知道某段代码做什么/为什么

工作流

Step 1 — 定位工作起点

按以下规则确定要读哪些文件：

• 模块/功能名已知 → 通过 _index.md 或 agent_guide(task='...') 定位入口
• 功能名未知 → 读项目文档索引按关键词匹配
• 有 stack trace → 提取最顶层业务帧（跳过框架层/第三方库帧）
• 描述行为或界面 → grep 关键词定位文件
• 重构任务 → 先 grep 待改符号在整个仓库中的所有出现位置

禁止在未读文件的情况下假设任何函数、字段名称。

Step 2 — 建立上下文

定位起点文件后，按顺序执行（不得跳过）：

1. Read 起点文件全文
2. Grep 文件中所有 import/依赖，逐一 Read 关键依赖
3. Grep 全局搜索起点类名/函数名，找到所有调用方
4. 涉及网络/RPC → Read 协议或接口定义，确认请求/响应签名
5. 涉及配置/数据表 → Grep 配置访问代码，确认表名和字段
6. 涉及自动生成产物 → 以"权威产物"为准建立 API 白名单（见下方）

每个方法名、字段名必须有对应的 Read/Grep 证据，无证据禁止使用。

生成代码/自动产物白名单流程

当代码依赖自动生成的产物（Protobuf、ORM 实体、Pydantic 模型等）时：

1. 找到原始权威来源（Schema/proto/配置文件）
2. Read 生成产物，确认实际导出的字段/方法列表
3. 类型声明仅作辅助，可能滞后
4. 权威产物有 → 可用；类型声明有但权威产物无 → 禁止使用

Step 3 — 压缩上下文（超限时执行）

已读文件总行数 > 1000 行，或上下文超过约 50% 时，输出摘要后继续：

[上下文摘要]
- 起点：path/to/EntryFile.ext
- 关键方法：methodA(L46)、methodB(L102)
- 依赖：DependencyA(已读)
- API 白名单：fieldA、methodB（来自权威产物）
- 待处理：...

Step 4 — 任务理解对齐（等待用户确认）

基于已读证据，按任务类型选用模板：

Bug 模式：输出 Bug 初步分析（现象/嫌疑路径/推断根因/证据强度✅⚠️🚫），请用户确认方向。

需求模式：输出需求理解（目标/涉及文件/复用项/澄清问题/不在范围），请用户确认。

重构模式：输出重构影响面（目标/引用清单/风险点/替换计划），请用户确认清单完整性。

理解模式：直接输出代码解释（做什么/关键路径/数据流/陷阱），不进 Step 5/6。

用户回复方向不对 → 收集新线索，回到 Step 1。

禁止在用户未确认方向前，直接跳到 Step 6 列实施方案。

Step 5 — Log 辅助调试（仅 Bug 模式，可选）

触发条件：Step 4 证据强度 ⚠️ 或 🚫，或用户主动要求。

1. 询问用户确认是否插桩 log
2. 在关键位置加 log，通过 exec_python 执行
3. 引导用户复现，读取 log 文件
4. 回到 Step 4 重新分析
5. 修复完成后清理插桩 log

何时升级为 diagnosing-bugs：本 step 是轻量 log 调试，适合"读代码就能看出嫌疑"的简单 bug。当满足以下任一条件时，转 diagnosing-bugs 6 阶段流程：

• bug 涉及并发/异步/竞态/非确定性复现
• 已加 log 但 3 轮仍未定位根因（证据强度持续 🚫）
• 用户描述 "性能回退"、"slow"、"sometimes wrong" 等需要 feedback loop 的场景
• 怀疑是多模块联动 bug，单点 log 无法覆盖

diagnosing-bugs 的核心是 先构建 tight feedback loop，再 hypothesise，避免凭空猜根因。

Step 6 — 提出实施方案（等待确认）

列出方案，等待用户确认后再修改代码：

[方案列表]
方案 A：...（适用场景，代价/影响）
方案 B：...
推荐：方案 X

收到确认后执行，遵守：

• 只修改已读、已验证存在的代码路径
• 新增调用先 grep 确认方法存在
• 遵守 coding_principles（Surgical / 7 级阶梯 / 不偷懒区域）
• Step 5 加过 log 的，完成后清理

坑点清单

• 跳过 Step 2 直接动手：没读文件就改 = 凭想象写，幻觉高发区
• 编造方法名/字段名：没 grep 确认就用的，十有八九是编的
• 跳过 Step 4 直接出方案：用户还没确认方向就动手，大概率返工
• Bug 证据不足硬猜根因：应该走 Step 5 加 log；仍不够则升级 diagnosing-bugs
• 重构靠记忆替换：必须 grep 全仓引用清单

与现有 Skill 的关系

Skill	关系
diagnosing-bugs	本 skill Step 5 是轻量 log；复杂 bug（并发/非确定性/性能回退/3 轮未定位）转 diagnosing-bugs 6 阶段（Phase 1 构建 tight feedback loop → 2 复现+最小化 → 3 假设 → 4 插桩 → 5 修复+回归测试 → 6 清理+复盘）
task_closure	大任务走 task_closure 的 SDD 链，小任务走本 skill
neat-freak	本 skill 完成后若涉及文档变更，触发 neat-freak