SuperAPI AI 工具集

walden-history

写作与研究

查看项目

更新于 10-15 16:49

技能介绍

Walden History 用于回顾 Walden 仓库的过去:某个功能如何演变、作品集讲述了什么故事、每次批准之后有多少返工,以及如何恰当地退役被取代的规格。walden 技能负责起草和执行当下,本技能则读取时间。在条件允许时应使用用户偏好的语言回复。

适用场景:用户询问某功能的演进(时间线、编年史或契约历史);用户想了解产品故事(时代、取代关系、存活与退役的工作);用户询问某次批准后有多少返工,或需要变更分析;用户决定退役被取代的规格。

前提条件:git 仓库历史中包含已提交的 .walden/ 文档。walden CLI 为可选项,仅用于交叉核对当前状态;以下所有重建均只靠 git 即可完成。若仓库将 .walden/ 加入 gitignore,则没有可编年的规格历史,应如实说明,不要臆造。

依据规则:每条历史陈述必须且只能携带一个标签,该标签是陈述的证据等级。[sealed] 表示对指定提交处已记录值做字符串比较;当某提交上 design.source_requirements_fingerprint 等于 requirements.approved_fingerprint、tasks.source_design_fingerprint 等于 design.approved_fingerprint,且 evidence 记录的链字段等于其所指文档的封印时,链是一致的;某提交上封印不一致属于发现,应明确报告,不得抹平。[inferred] 表示提交信息、作者身份、时间因果以及所有“因为”式推断;推断是合理的叙述,未标注的推断则是虚构。

四条硬规则:用 git show <sha>:<path> 取回历史内容,绝不凭记忆;每条历史论断必须锚定其来源提交标识,没有 sha 的论断只是印象;内容验证属于核心领域,比较已记录的指纹彼此是否一致是本技能职责,而由正文重算指纹需要 walden CLI 的规范化规则,被要求对照封印验证内容时应如实说明并建议检出该提交运行 walden validate;git 作者身份只是归属代理,应写“committed by”而非“approved by”,Walden 尚未记录批准者身份,编年史不得虚构。

输出标准:时间线以表格呈现,每行一个提交锚点,标签内联;叙述置于表格之后并引用其行;正文中用短 sha,命令中用完整路径;当历史缺失(压缩合并、浅克隆、.walden/ 被 gitignore)时,说明丢失了什么,只叙述 git 保留的内容,绝不插值;每份返工报告都要数字先于叙述。

主要配方包括功能编年史(按文档从旧到新重建时间线,依据 frontmatter 转换推导事件:draft→in-review 为评审开启,in-review→approved 且设置 approved_at 为批准,approved→draft 且指纹清空为重整,approved_fingerprint 出现且状态仍为 approved 为封印/回填采纳,source_*_fingerprint 出现或变化为链修复,正文变化且出现新 approved_fingerprint 与 approved_at 为再批准周期,walden_schema_version 出现为格式迁移标记)、产品故事(按创建日期将功能聚为代际,用 RETIRED.md 条目以显式取代关系收束;全作品集遍历只读退役索引与 git log 元数据,深度重建仅按指定功能进行)、返工报告(提取各文档批准事件,切分批准间隔,用 git diff <approvalShaA>..<approvalShaB> -- .walden/specs/<feature>/<doc> 对比,单独报告重整事件;以指标块结尾:re-approval cycles、reconciliations、first approval → last recorded change 天数)。

退役仪式:这是本技能唯一的写入路径。被取代的规格被删除(历史留在 git 中)并记入退役索引,使门禁只评判存活作品集。前置条件:用户已在当前对话中指明要退役的功能及其取代关系;须将确切清单与后继者向用户确认并等待明确批准,绝不能把沉默或早前的设想当作同意。步骤在单次提交中完成:git rm -r .walden/specs/<feature>(每个退役功能);向 .walden/RETIRED.md 追加每功能一行索引条目(首次使用时创建);git add .walden/RETIRED.md;git commit -m "chore: retire <scope> (superseded by <successor>)"。绝不推送。提交后建议运行 walden validate。

退役索引约定:.walden/RETIRED.md 位于 constitution.md 与 lessons.md 旁、specs/ 之外,因此没有任何 walden 命令会评判它。每个退役功能一行,可用单一模式解析,也可不用模式阅读:- <feature-name> — retired <short-sha> — superseded by <feature-or-era> — <reason>。

完整性检查:索引与 git 历史必须一致,报告每处不匹配:索引条目对应的规格目录仍存在(记录但未执行退役);已删除功能(来自 --diff-filter=D 列表)却无索引条目(未记录的退役,可提供用删除提交回填索引行);格式错误的索引行(指出行号)。