BMAD Deep Recon 研究生命周期：Refresh 与 Deepen 机制实战指南

BMAD Deep Recon 研究生命周期：Refresh 与 Deepen 机制实战指南

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD

导读

本指南围绕 BMAD-METHOD 项目中bmad-deep-recon技能（位于 skills/bmad-deep-recon）的研究生命周期管理展开：当一个研究 run folder 已经存在时，如何通过Refresh（刷新）让既有研究结论保持新鲜、通过Deepen（深化）定向加深某一条研究维度，而无需从零重跑。读完本文，你将掌握recon_kit.py staleness的失效检测机制、claims ledger（memlog）的读写约定、delta report 的交付形态，以及将生命周期操作接入「Draft → Run → Process」主循环的完整做法。

一、生命周期问题的来源：研究结论会过期

bmad-deep-recon是一个服务于决策的研究指挥技能：进入市场、选择技术栈、界定产品范围、投入某个领域，每一项决策都建立在若干研究主张（claim）之上。技能的一条铁律是：

"Report what is real."数据薄就是薄，证据缺失本身就是发现，而新鲜度是事实的一部分（freshness is part of truth）——三年前的市场规模是历史，不是事实。

这意味着：今天验证过的结论，三个月后可能已经过期。市场规模的数字、竞品的定价、监管口径、技术栈兼容性都在变化。lifecycle.md（skills/bmad-deep-recon/references/lifecycle.md）定义的就是针对已存在 run folder的两类生命周期意图（lifecycle intents）：Refresh与Deepen。二者共同的原则是：绝不重头再来——磁盘上已有的research.md与.memlog.md是唯一可信的现场，所有生命周期操作都从读取它们开始。

二、Run folder：生命周期操作的作用域

在进入 Refresh / Deepen 之前，需要理解两者的操作对象。bmad-deep-recon的所有模式（Draft、Process、Run）共享同一套 run folder 工作区形态（见 SKILL.md 的 Intents 表）：

{research_output_path}/{research_type}-{topic_slug}-{date}/ ├── brief.md # Draft 模式产出的可粘贴研究提示词 ├── imports/ # 导入的原始报告（完整保真） ├── digests/ # 抽取出的 claims 摘要（每助手每轮一个文件） ├── research.md # 规范化的决策摘要/报告（canonical artifact） └── .memlog.md # 过程记忆（append-only 日志）

• research.md：下游技能直接消费的产物，含 frontmatter（type、topic、decision、source、status、created、updated），种子模板见 assets/research.template.md。
• .memlog.md：append-only 的过程记忆，记录每次决策、每批来源、每个 load-bearing claim、每次计划变更与假设。

run folder 的命名由{workflow.run_folder_pattern}决定（默认{research_type}-{topic_slug}-{date}），通过recon_kit.py slug确定性展开，保证同一个主题在任何模式下都落到同一个文件夹——这正是 Refresh / Deepen 能"找回"既有现场的前提（见 customize.toml）。

因此，当用户在激活时提到"resume / extend / 刷新 / 加深"某个已有主题，技能优先沿用已有 run folder，而不是新建重复研究（见 SKILL.md 激活步骤 5）。

三、Refresh：让既有研究保持新鲜

Refresh 的定位是增量保鲜：只重验证过期的 claims，其余原样保留，最后交付一份delta report（增量报告）。完整流程如下。

3.1 第一步：从磁盘恢复现场，绝不重头研究

首先完整读取{doc_workspace}/research.md与{doc_workspace}/.memlog.md。memlog 就是研究的过程记忆——"Nothing exists until it is a file"，对话只是控制通道，磁盘才是存储。一次中途崩溃的 run 也要能从磁盘恢复。

3.2 第二步：机械构建 refresh set（候选集合）

Refresh 的核心是把"哪些 claim 过期了"这个判断变成确定性计算，而不是凭 LLM 感觉：

1. 从 ledger 组装 claims：从.memlog.md中收集每条 claim 记录的三要素——claim（主张文本）、class（主张类别）、pub_date（发表日期），形成一个claims.json。

2. 将 pack 的 freshness bars 映射为 months-per-class JSON：每种研究类型（pack）都有自己的新鲜度阈值。以market类型的 types/market.md 为例：

   Freshness:size/growth ≤ 18 mo · pricing & feature claims ≤ 3 mo · behavior data ≤ 2 yr · GTM benchmarks ≤ 12 mo

   对应的 windows 映射即为{"size/growth": 18, "pricing": 3, "behavior": 24, "gtm": 12}（单位为月）。

3. 运行 staleness 计算：

   uv run scripts/recon_kit.py staleness claims.json --windows '{"size/growth": 18, "pricing": 3}'

   （脚本位于 skills/bmad-deep-recon/scripts/recon_kit.py，带# /// script头部，可由uv run直接执行；路径相对技能安装目录。）

   返回的 stale 标志集合就是 refresh set（候选集合）——只有被标记为过期的 claims 才需要重验证。

3.3 staleness 的源码级原理

cmd_staleness的实现逻辑（recon_kit.py L182-L219）值得拆解，因为它定义了 refresh set 的语义：

• 日期解析parse_date：支持YYYY-MM-DD、YYYY-MM、YYYY三种粒度（L166-L173），所以pub_date写2026-01也能参与计算。
• 窗口映射：--windows参数按 claim 的class（转为小写）查表；未命中的类别进入no_window_classes，该 claim 不判 stale（L200-L204）。
• recheck 日期：recheck = add_months(pub_date, months)。add_months正确处理跨年与月末截断——测试用例add_months(date(2026, 1, 31), 1) == date(2026, 2, 28)（见 tests/test_recon_kit.py L91）保证 1 月 31 日加一个月落到 2 月 28 日。
• stale 判定：stale = recheck <= today——即"最晚复核日期"已经到达或越过今天（L206）。
• 输出：每个 claim 附带recheck与stale字段，汇总给出stale_count、earliest_recheck（全组最早应复核日期）与no_window_classes。
• 退出码：stale_count > 0返回 1（有发现需关注），0 表示全新鲜，2 为参数/解析错误。命令对--today的支持也便于测试与离线演练（测试用例test_windows用--today 2026-07-22固定"今天"，见 L88-L117）。

这正是"确定性辅助"的设计哲学：recon_kit是研究流程中机械的一半（the mechanical half），一切可精确、可重复的计算都不该由 LLM 手工推导。

3.4 第三步：一次交换确认，仅重验证候选 claims

得到 refresh set 后：

• 一次交换确认（confirm it in one exchange）：将候选集合展示给用户确认，不做多余往返。
• 只重验证集合内的 claims：验证遵循 references/verification.md 的信任层规则——验证发生在材料落盘时，由 fresh-context 的验证子代理读取 digest 文件执行，且按解析出的validation级别（normal/high/max）进行。范围外的 claims保持其原有状态（"Claims outside the set keep their status"）——这正是增量设计的核心：不触碰未过期结论。

3.5 第四步：交付 delta report

重验证结束后，交付一份delta report（增量报告），追加到research.md末尾，结构包含：

• confirmed（仍成立）：重验证后依旧成立的主张；
• changed（已变化）：内容发生变化的 claim，更新为最新事实；
• overturned（被推翻）：证据权重指向相反的 claim，正文中修正、并保留原说法的标注（对应 verification.md 的四种结果之一：verified/disputed/unverified/overturned）；
• new sources（新来源）：本次刷新引入的新证据。

同时更新 frontmatter 的updated字段——research.md的 frontmatter 元数据（type、topic、decision、source、status、日期）是下游消费者"无需重处理即可信任"的依据（见 references/finalize.md 第 1 步）。

3.6 被推翻的 load-bearing claim：必须显式警告

lifecycle.md中有一条强约束：

An overturned load-bearing claim triggers an explicit warning naming the downstream artifacts that consumed it.

如果一个承重主张（load-bearing claim）——即研究推荐所依赖的那几个关键 claim——被推翻，Refresh 必须发出显式警告，并点名消费了它的下游制品。这一点与各 pack 的Feeds绑定相呼应：例如marketpack 声明其结论会喂给 brief（机会、问题、用户）、PRD（画像、差异化）、定价与 GTM 决策（见 types/market.md 的 Feeds 段）。换言之，刷新不只是"改一个数字"，而是要顺着消费链提醒所有基于该结论的后续决策制品。

在 headless 模式下，Refresh 的收尾 JSON 将claims计数替换为 refresh set 的范围，并附加一个deltas数组（见 SKILL.md Headless Mode 段）。

四、Deepen：定向加深单一维度

Deepen 的定位是切片式加深：深入某一条既有维度、或新增一条维度，而不触碰其余内容。它的操作单元比 Refresh 更小、更聚焦。

4.1 三步流程

1. Mini plan gate（迷你计划门禁）：这是全流程唯一硬停点（one hard stop）的缩略版。参考 references/run.md 的计划门禁要素——决策、类型、按决策裁剪的 pack 维度、分解拓扑、生效旋钮及其来源——但只针对本次要加深的那一个切片，保持轻量，不做多余仪式。
2. Acquire → verify（获取 → 验证）只针对该切片：
   • 执行研究获取循环（同 Run 的 rounds 机制：宽查询起步、harvest leads、按 coverage / novelty exhaustion 提前收敛）；
   • 或者，当"用户的工具更擅长此切片"时（例如用户订阅了某外部研究工具），改由技能起草一份跟进提示词（drafted follow-up prompt）交给用户在自己的工具中运行，再走 Process 流程回收——这正是 Draft 与 Run 两种模式的组合用法；
   • 验证按 references/verification.md 执行，且只针对该切片（"verify for that slice only"）。
3. Merge（合并）：把新结论合并进research.md，但只更新新素材所影响的 synthesis 小节——执行摘要之外的维度章节、跨维度洞察、推荐、附录等部分，不受影响的保持原样。

4.2 一条值得注意的约定

a deepening that changes no conclusion says so.

如果一次 Deepen 跑完后没有改变任何结论，那么必须在报告中明确说明这一点。这与技能的"诚实报告"原则一致：absence of evidence 是发现，零变化也是结果——它不是一次失败的 Deepen，而是一个值得记录的"该维度已被充分验证"的信号。

4.3 Deepen 与 Refresh 的边界

两者都严格遵守"append-only、从磁盘恢复、不重头研究"的共同前提。

五、底层机制：memlog 就是 claims ledger

Refresh 之所以能"机械地"找出过期 claims，是因为.memlog.md被设计为可计算的 ledger。其读写契约在 skills/bmad/scripts/memlog.py 中有完整实现，核心约定包括：

1. Append-only、chronological：条目只追加在末尾，没有编辑/删除子命令，历史永不重写；写入采用临时文件 + fsync + 原子重命名，崩溃不会留下半截条目。

2. claim 条目的机器可读形态：在 Run 的合成阶段（run.md 第 3 步）约定，每条 load-bearing claim 按如下格式记录：

   - (claim) ref=[1] status=verified class=size/growth pub=2026-01 — market growing 12% CAGR

   其中ref=[n]对应 research.md 来源附录中的编号，status取verified | unverified | disputed | overturned，class对应 pack 定义的类别，pub为YYYY-MM粒度。状态变更 = 追加一条同ref=的新 claim 行，last status wins（最后状态生效）——这是tally子命令读取账本的依据（见测试test_last_status_wins_per_ref：ref=[2] 先 unverified 后 verified，最终只计为 verified 一次）。

3. tally 与 headless 计数：uv run scripts/recon_kit.py tally {doc_workspace}/.memlog.md按条目类型（decision/source/claim/assumption/question/event…）与 claim 状态统计，绝不允许手数。headless 收尾 JSON 中的claims: {verified, unverified, overturned}计数即来自此处（SKILL.md）。

这条 ledger 与 Refresh 形成闭环：合成阶段写入 claim 行 → 刷新阶段读取 claim 行计算 stale → 重验证后追加新的状态行。研究的新鲜度因此成为可审计、可追踪、可持续维护的工程资产。

六、Refresh / Deepen 在整体工作流中的位置

6.1 意图路由

SKILL.md 的 Intents 表将Refresh / Deepen列为独立意图，与 Draft、Process、Run 并列。路由规则：当用户对某个已存在的 run folder提出更新或扩展诉求时（例如"这份报告还能用吗""帮我把技术维度挖深一点"），加载references/lifecycle.md执行。激活步骤 5 也提示：若该主题的 run folder 已存在（一份等待报告的 brief、或一份等待刷新的报告），应提议续用/扩展，而不是另起炉灶。

6.2 staleness map：Refresh 的预约工单

research.md的组装清单（references/synthesis.md 第 8 步）包含一个staleness map（失效地图）：从 ledger 构建 claims 列表、把 pack 的 freshness bars 映射为 months-per-class、运行staleness命令、渲染每个 claim 的 re-check 日期并标注最早者。该地图"就是 Refresh 的工作清单（This is Refresh's work order）"——一次 run 结束时已经为未来的刷新预埋了精确的调度信息。Finalize 阶段（finalize.md 第 6 步）也会向用户明确提示"staleness map 要求何时复检什么"，并说明 Refresh/Deepen 会接手处理。

6.3 验证级别与红队对抗

Refresh 中重验证的强度由{workflow.validation}控制（见 customize.toml 与 verification.md）：

• normal（默认）：仅抽查 load-bearing claims，每个做一次独立来源核对——快是设计目标；
• high：交叉核对 pack 两源类别（two-source classes）内的所有 claim，并对主要结论运行红队对抗；
• max：核对账本内全部 claim + 红队全广度 + 一手来源优先排序（存在一手资料时，二手报道单独不足以验证）。

"独立来源"指不同出版商、不同底层数据，而非转载或复述；冲突按"最近、与相邻既定事实一致、出版商质量"解决，绝不取平均。红队对抗是唯一的对抗机制：fresh-context 的怀疑者子代理专门寻找反证——被推翻的承重主张正是 Refresh delta report 中"overturned"项与下游警告的来源。

七、实践要点：把生命周期跑起来

1. 先找现场，再谈刷新：任何 Refresh / Deepen 都以{doc_workspace}下的research.md+.memlog.md为起点；主题对应的 run folder 由slug命令确定性定位（uv run scripts/recon_kit.py slug "<topic>" --type <type> --pattern "{workflow.run_folder_pattern}"）。
2. refresh set 靠计算，不靠感觉：uv run scripts/recon_kit.py staleness <claims.json> --windows '<map>'的stale: true集合即候选集；--today参数可在离线/演示场景固定日期。
3. 只动该动的：Refresh 只重验证 stale claims，其余状态保持；Deepen 只更新受影响小节，无结论变化必须明说。
4. 账本永远 append：所有状态变更走memlog.py append --type claim，同ref=追加新行，tally负责统计；headless 场景的计数一律来自tally，禁止手数。
5. 推翻承重要警告：delta report 中若出现 overturned 的 load-bearing claim，必须显式点名其消费方（如 market pack 的 brief / PRD / 定价与 GTM 决策）。
6. 用 staleness map 做预约：每次 run 收尾时保留失效地图，它定义了未来 Refresh 的精确范围与时间点，让研究资产进入"保鲜—复核—更新"的可持续循环。

八、小结

Refresh 与 Deepen 把"研究"从一次性动作升级为可维护的生命周期资产：Refresh 用staleness的确定性计算识别过期主张、以 delta report 完成增量保鲜；Deepen 用 mini plan gate 与切片式获取实现单维度定向加深。二者共享同一套 append-only memlog ledger、同一套验证信任层与诚实报告纪律，共同确保研究结论始终"新鲜、可追溯、服务于决策"——这正是 BMAD Deep Recon 作为研究指挥（research director）而非搜索引擎的价值所在：不仅产出决策级研究，还负责让研究在时间推移中持续可信。

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD