fable-discover

Fable Discover

在任何人提交设计或编辑之前，为陌生的代码路径建立尽可能精简且可靠的心智模型。

使命

探索不是“阅读大量文件”，而是降低不确定性。

本 Skill 应为下一位专家提供足够的证据，使其无需重新摸索代码库就能做出决策，同时避免探索演变成考古。

适用场景

• 尚不清楚入口点、代码归属或执行流程；
• 请求涉及不熟悉的包或子系统；
• 生成代码、插件、运行时配置、队列、作业或依赖注入可能改变实际执行路径；
• 用户描述了行为，但没有说明行为的实现位置；
• 之前对代码库的某项假设已被推翻。

不适用场景

• 已知具体且范围明确的编辑内容和目标文件；
• 任务纯粹是外部 API／版本研究（fable-research）；
• 任务只是运行现有检查（fable-verify）。

情况分类

搜索前，先对未知内容进行分类。

未知项	优先查找的证据	常见陷阱
拓扑结构	清单、工作区配置、包边界	假定根包拥有运行时
入口点	CLI／服务端／作业／插件引导程序	从名称相似的辅助程序开始
执行路径	调用、处理程序、事件、数据转换	只追踪导入，却未证明运行时可达性
配置	环境变量／架构／默认值／功能标志	只看默认值，却忽略生产环境的覆盖项
生成的行为	构建脚本、代码生成输出、生成的清单	修改生成的输出，而不是源文件
插件／扩展路径	注册、发现、加载器契约	因 grep 找不到直接导入而遗漏动态加载
持久化／数据路径	存储库、架构、事务、队列	停留在服务层，未追踪副作用
测试架构	测试框架、固定数据、测试入口点	假定测试运行的产物与用户运行的相同

探索流程

阶段 1 — 梳理未知项

提出 2-7 个答案会实质影响计划的问题。将每个问题标记为 load-bearing 或 nice-to-know。

示例：

• 哪个进程接收此请求？
• 该包是直接执行源代码，还是从 dist/ 执行？
• 此插件在哪里注册？
• 哪个存储边界会提交状态？

问题尚未明确前，不要开始广泛搜索。

阶段 2 — 确定代码库拓扑

先阅读项目说明和清单。确定：

• 工作区／包根目录；
• 构建／测试命令；
• 生成目录；
• 宿主／插件清单；
• 源代码与分发版入口点；
• 配置来源；
• 相关代码归属边界。

阶段 3 — 追踪一条真实路径

从可观察的入口点出发，沿着具体符号／事件追踪至目标行为。

每一步都记录：

• 文件／符号；
• 此步骤为何可达；
• 输入／输出契约；
• 副作用或状态转换；
• 确定性：[measured]、[inferred] 或 [unresolved]。

仅有导入链并不能证明代码会执行。

阶段 4 — 仅在静态证据不足时探测运行时

使用安全的只读运行时观察来回答一个明确的问题：日志、帮助输出、路由列表、测试发现结果、构建元数据或范围有限的复现。

不要仅为满足好奇心而修改生产状态。

阶段 5 — 解决矛盾

当测得的证据与当前模型矛盾时，立即更新模型。不要因为旧理论能让先前的搜索显得连贯，就继续保留它。

阶段 6 — 有意识地停止

当每个 load-bearing 问题都满足以下任一条件时，即可停止：

• 已有证据支持答案；或
• 明确标记为未解决，并说明其影响和后续 Skill。

nice-to-know 问题不会阻碍交接。

决策规则

• 如果未知信息涉及外部且会随时间变化的问题，请将该问题交给 fable-research，不要根据模型记忆推断。
• 如果确切的编辑范围已经明确，且不再需要设计决策，请交由 fable-execute 处理。
• 如果必须协调多个组件或风险，请交由 fable-plan 处理。
• 如果搜索结果表明代码是生成的，请先找到生成器／唯一可信来源，再建议编辑。
• 如果直接导入在某个边界处消失，请检查注册表、事件总线、依赖注入、插件发现、反射、代码生成和运行时配置。
• 如果测试与运行时似乎不一致，请记录两条路径；不要假定测试框架具有权威性。

不变量

• 除非用户明确更改任务，否则发现过程只读。
• 每个关键结论都必须有具体的仓库／运行时证据。
• 推断必须标注为推断。
• 搜索范围必须有尚未解决的问题作为依据。
• 未证明生成输出由人工维护前，不得将其视为规范源。

故障分类

搜索未命中

无法找到某个符号。请检查别名、生成的名称、动态加载、注册表、事件分发、反射、编译输出和包边界。

错误路径

文件看似相关，但无法从实际入口访问。请返回已证实的运行时／引导边界。

环境不明确

行为取决于环境变量／标志／配置。请确定优先级和当前生效的配置；不要将默认值报告为运行时事实。

源码／构建产物不匹配

测试或命令执行的是已构建／过时的产物，而非已编辑的源码。请记录两条路径；如果这导致了反复失败，请转交 fable-recover 处理。

未知因素仍是关键

不要掩盖它。请转交研究，或明确报告尚未解决的决策。

反模式

• 为了“了解背景”而阅读包中的每个文件；
• 根据文件名判断架构；
• 将 grep 出现频率视为重要性；
• 未证明运行时可达性就跟进导入关系；
• 忽略构建／代码生成／插件注册；
• 报告假设却不使用 [inferred] 标签；
• 规划决策已足够稳妥后仍继续探索。

证据包／交接

生成一份精简材料包：

Target:
Load-bearing questions:
Measured facts: file:symbol → fact
Execution path: entry → ... → side effect
Configuration/runtime notes:
Generated/plugin boundaries:
Unresolved questions + consequence:
Recommended next Skill:

完成标准

当下一位专家能够说明以下内容时，发现工作即告完成：

• 执行从何处开始；
• 哪条路径会触达相关行为；
• 哪些契约／状态边界至关重要；
• 哪些事实是实测的，哪些是推断的；
• 还有哪些未知信息；
• 为什么剩余的未知信息会或不会阻碍下一步行动。

渐进式资源

• 深入手册：references/repository-investigation-playbook.md
• 现有证据协议：references/evidence-gathering-protocol.md
• 示例：examples/codebase-inspection.md