| name | anti_hallucination |
| description | 日常编码的防幻觉安全网。当用户要改代码/修 bug/加小功能/重构/理解代码，且任务规模为小修小补（不走完整 SDD 规约链）时使用。6 步防幻觉流程：定位起点→建立上下文→压缩→对齐确认→可选 log 调试→提方案。核心：索引先于动手，读到再用，禁止编造，方案先确认。
触发场景：
- Bug 类："不显示"、"报错"、"数据不对"、"帮我看看"、"排查"、stack trace、"帮我 debug"
- 需求类（小）："加一个小功能"、"在这加个 XX"、"支持一下 YY"
- 重构类："重命名"、"抽取"、"拆分"、"挪到"
- 理解类："这段代码做什么"、"XX 是怎么工作的"
关键词：改、修、bug、报错、排查、定位、加功能、重构、这段代码、怎么工作
|
反幻觉工作流（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 — 建立上下文
定位起点文件后，按顺序执行（不得跳过）：
- Read 起点文件全文
- Grep 文件中所有 import/依赖，逐一 Read 关键依赖
- Grep 全局搜索起点类名/函数名，找到所有调用方
- 涉及网络/RPC → Read 协议或接口定义，确认请求/响应签名
- 涉及配置/数据表 → Grep 配置访问代码，确认表名和字段
- 涉及自动生成产物 → 以"权威产物"为准建立 API 白名单（见下方）
每个方法名、字段名必须有对应的 Read/Grep 证据，无证据禁止使用。
生成代码/自动产物白名单流程
当代码依赖自动生成的产物（Protobuf、ORM 实体、Pydantic 模型等）时：
- 找到原始权威来源（Schema/proto/配置文件）
- Read 生成产物，确认实际导出的字段/方法列表
- 类型声明仅作辅助，可能滞后
- 权威产物有 → 可用；类型声明有但权威产物无 → 禁止使用
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 证据强度 ⚠️ 或 🚫，或用户主动要求。
- 询问用户确认是否插桩 log
- 在关键位置加 log，通过
exec_python 执行
- 引导用户复现，读取 log 文件
- 回到 Step 4 重新分析
- 修复完成后清理插桩 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 |
