#agent-skills #research #verification #methodology

research-first

Do research with stopping criteria instead of vibes — five machine-checkable criteria (S1–S5) for when to stop, six breadth axes, nine associative-expansion directions (D1–D9), a journal template, and two CLI checkers that machine-verify a research journal and flag false confidence. Use when you are about to write a spec, design doc, or prompt that depends on facts you have not verified; when asked to research/investigate/look something up before starting; when reviewing whether an existing conclusion has traceable sources; or when you catch yourself citing a single secondary summary as if it were first-hand.

LunaPet@catsmansion

Install

openclaw skills install @catsmansion/research-first

动手前先 research（停止判据 + 覆盖轴 + 纪要）

核心问题不是"要不要查"，是"什么时候停"。 凭感觉停 ⇒ 一次 research 白做。本 skill 只提供判据与纪律，不提供检索教程（那是模型本来就会的）。

何时用

要写方案 / 派单 / 规格 / prompt 之前（这些一旦落盘就会约束别人，错的代价最大）
要回答「X 是不是这样 / 该怎么做」这类可被证伪的问题
要复核已写好的结论（尤其当结论来源只有一份文档时）
⛔ 不适用：纯代码实现、内部重构、查本机文件既有内容（那是读盘不是 research）

⛔⛔ 五条停止判据 —— 全满足才允许停

⚠️ 跑 scripts/check_journal.py <纪要.md> 机检 S1/S2/S4；S3/S5 需人工判定。

#	判据	达标线	机检
S1	独立来源 ≥3（不同作者/站点/语言）。⛔ 同一文档的转载、摘要、二次转述不算独立来源。⭐「独立」指独立集群而非单纯计数 —— 3 个都转自同一篇 = 1 源	≥3 个不同域名	✅
S2	每条结论能指到出处（URL + 章节/行号）。指不出的必须标「未验证」	未标出处的条数 = 0	✅
S3	边际收敛：连续 2 次检索零新增事实才算触顶	记录轮次数	❌ 人工
S4	⛔ 搜过反面样本（「为什么失败 / 最廉价 / 怎么翻车 / common mistakes」）	有该小节且非空、未写"未做"	✅
S5	量化优先：能变成数字的必须给数值 + 出处。⛔ 不许只写形容词	无出处数字 = 0	❌ 人工

⭐⭐ S6 · 探索产出率 —— research 的默认方向是进攻型

「research 该干的事是找出我还不知道能做什么。」（Ronny 2026-10-18 原话） ⚠️ 下面的指标是我推导的；若有冲突以原话为准。

⚔️ 为什么要有这条：本 skill 诞生当天，author 连做三轮 research 全是防守型 （去证明「静图动不了」「预算不够」「通道只吃 1 张图」）—— 三轮下来一次都没发现新能力，而同期只要拉一次工具清单就能发现 27 个工具 + 3 项工业级能力。

⇒ 防守型 research 会自我合理化：查得越多，越能证明"这事不行"，而查得很深的感觉会掩盖这一点。

计数器（每轮必填，落进纪要）

指标	定义	判红线
U	本轮找出「我原本不知道它存在」的条目数	U < 3 ⇒ 红
C	其中类别为 `能力` 的条数（⛔ 不含"我理解错了"这类认知修正）	C < 1 ⇒ 红
N	找「为什么不行」的理由数	记录；N 远大于 U ⇒ 防守型，红

一句话判据

⛔ 说不出一个「我之前不知道它存在」的东西，这轮 research 就是白做的。

「原本不知道」的判定口径（可机检）

在纪要里写成对：我原本以为 X → 实际是 Y。只有改变了可选集的（原来"做不到/不知道有" → 现在有具体工具或做法）才算 U；单纯"我把 A 理解反了"记进撤回表，⛔ 不计入 U。

⚠️ 每轮 research 收尾自查一句：

这一轮我新发现了什么存在的东西？若答案是"没有，只是更确定做不到" ⇒ 立刻换方向重查。

⛔ 四个反模式（作者亲犯，不是假想）

反模式	表现
先发能力许可证再 research	还没动手就说「通道只吃 1 张图」「预算不够」
拿局部证据否定用户	查了一个 key 的余额就说「你的预算前提是错的」（用户有 6 个账号）
用理论推导代替试做	推导三天说不行 ⇢ 花 270 分试 5 秒，信息量大得多
research 变防守	每轮都在找"为什么不行"，U=0 却仍觉得"查得很深"

六个覆盖轴 —— 范围靠换轴变大，不靠搜更多次

轴	自查	换法
A1 来源数	结论是不是只有一份文档在支撑？	换独立站点/作者，不换同一份的转载
A2 语言	是不是只在一个语言圈搜？	⛔ 换目标领域的母语关键词（日本动画→日文；美术→英文/日文）——本次实战：补日文词才捞到真东西
A3 时间跨度	只看当下流行？	查这项技术的传统来源与历史演变
A4 ⛔ 反面样本	找过失败案例吗？	单独跑一轮"为什么失败"检索
A5 量化	形容词能否换成数字？	「闪 3–6 帧」「12fps」比「短一点」「快一点」有用得多
A6 ⛔ 本地实证	对真实样本量过吗？	有样本就量；⛔ 没有就明写"未做"，不许用文献结论冒充实测

⛔ 联想扩散（D1–D9）：查「有没有别的东西可查」

⚠️ 只换检索词不算换方向。CHI 2011 明说：以关键词搜索为中心的界面本身就是意外发现的威胁。 ⭐ 理论依据：Serendipity = 幸运 + 识别力 ⇒ 光"多搜"没用，得有一张"什么算异常"的清单。

#	方向	提问模板	今天的实例（2026-10-18）
D1	术语邻居	X 和哪些易混术语会被当成一回事？	`smear frame` 被我当 motion blur 一起禁
D2	权威源头	谁是第一手来源？我读的是几手？	读的是二手 SKILL.md
D3	⭐ 利益相关	说这话的人有没有商业动机？	⛔ 那 skill 属商业项目，我完全没意识到
D4	前置依赖	做到 X 之前必须先知道什么？	「抽帧+横摇」组合才有的频闪陷阱
D5	反面/失败	X 什么情况下适得其反？（= S4）	⛔ 未做
D6	量化参数	描述 X 的具体数值标准？	1–3 帧 / 12fps
D7	同类替代	除 X 还有什么？各自适用条件？	预算制 vs 收敛制
D8	⭐ 跨域差异	别的时期/地区/媒介还成立吗？	⛔ 隐含假设「MV 演出 = 动画演出」
D9	原始材料	有没有原始论文/规范，而非二手总结？	PARC 论文（理论侧✅）

详细依据（信息觅食理论 / Information Encountering / 邻接可能）与今日实例 → references/联想扩散清单.md

两个机检器分工

脚本	判什么	红项含义
`check_journal.py`	结论站不站得住（S1–S5）	你在拿不可信的结论下判断
`check_expansion.py`	方向有没有漏（D1–D9）	你只查了一个斑块就以为够了

⚠️ 标 ❌未查 会报红但是合法的 —— 漏的是"不声明"。 ⚠️ 标 ⚠️部分/被动撞见 单独统计：合法，但说明不是主动联想出来的。

⛔ Gotchas（最高信号 · 全部来自真实翻车）

#	翻车	后果	修法
G1	只读一份二手整理就当铁律	把该领域的标准做法写反了，并写进派单去约束执行端	S1：单一来源只能当线索，⛔ 不能当结论
G2	只搜"正确做法"，不搜失败案例	搜到的必然全是对的 ⇒ 无法证伪	S4 强制单独跑一轮反面检索
G3	编造数字（如"只闪 3–6 帧"实则无出处）	数字最像证据 ⇒ 最能掩盖"其实没查"	无出处的一律标「未验证」，⛔ 不许进规格
G4	用形容词代替数值（"快一点""淡一点"）	执行端只能猜 ⇒ 返工	S5
G5	research 完不落盘	下次同一错误重犯；结论无法被复核	落纪要；进派单的结论必须带出处
G6	⛔ 把"记忆里的规格"当 research	沿用过时前提（记忆里就有过被推翻的值）	动手前重新核代码/盘上实际值，不依赖记忆
G7	单一来源的关键结论不标风险等级	下游当成铁律	单源结论写「⚠️ 单源，待二次验证」
G8	不同领域的同名术语混用	约束写反（如把 `smear frame` 当 `motion blur` 一起禁掉）	术语表分开列；每个术语写"我们的做法"一栏
G9	⛔ 判据连修三次不对还在读代码猜	修了三版仍然假阴性，浪费三轮	第三次不对就打印中间值（`repr()` 抓到的文本、匹配到的行号）。2026-10-18 实测：真根因是把"原文件行号"当成"列表索引"切片，读代码永远看不出来，打印一次就定位
G10	⛔ 判据对自己报绿时先怀疑判据，不是先庆祝	假阴性比假阳性严重：假阳性只费时间，假阴性是骗自己	判据必须对自己的真实文件跑一遍，看它敢不敢报红
G11	⛔ 判「类别/状态」时用子串匹配	`any(t in status)` 让「⚠️ 被动」既不命中"已查"也不命中"未查" ⇒ 被误判成空白	只认开头的标记符（`✅`/`⚠️`/`❌`）。与 check_journal 那次 `'结论' in line` 是同一个病：判类别要匹配标记符本身，不要用子串
G12	⛔ 静默降级（`except: pass` 吞掉加载失败）	降级到等价实现还以为在复用	降级路径必须 `print` 告警，让"没复用到"可见
G13	⛔ 判据问错了问题：「含否定词 ⇒ 没做」	我把「未做」改写成真内容后，句尾仍带一句免责说明 ⇒ 判据照样报红。"提到未做"不等于"没做"	判内容量就量净内容（剔除否定句后的字数），别用关键词命中代替内容量判定
G14	⛔ 正则要求"纯数字"，人偏要写"6+（说明）"	明明有数据，判据报"不可解析"	判数据就取前缀数字，别要求整格干净

落盘与引用纪律

纪要路径：项目根 Research纪要-<主题>-<YYYYMMDD>.md（跨项目通用纪律 → 落在项目里，不放记忆）
进派单/方案的结论必须带 [来源: URL §章节]；带不了的标 ⚠️ 未验证出处
⛔ 撤回旧结论要留痕：写进纪要的「撤回」表（错在哪 / 现在怎么说 / 影响面），⛔ 悄悄改掉不留痕

模板 → references/纪要模板.md 判据展开 + 阳性/阴性对照 → references/判据详解.md 机检 → scripts/check_journal.py <纪要.md>

常用命令

bash

python scripts/run_all.py <纪要.md>            # ⭐ 一条命令跑全部判据（结论 + 联想）
python scripts/check_journal.py <纪要.md>       # 只判 S1–S5：结论站不站得住
python scripts/check_expansion.py <纪要.md>     # 只判 D1–D9：方向有没有漏

⚠️ 退出码 0 ≠ 完美：WARN/⚠️ 不算红项，但含义不同 —— S3 WARN = 还没触顶（别当成"已查完"）｜S4 WARN = 有实质内容但仍欠着未完成项｜ D1–D9 的 ⚠️ = 被动撞见，不是主动联想出来的。输出里逐条看，别只看 exit code。