Skip to content

xinetzone/SpecWeave / .agents/skills/knowledge-bundle-naming-audit

knowledge-bundle-naming-audit

Verified

当用户认为知识包目录名、标题或副标题与内容不符,担心名称承诺过宽、中英不一致或暗含开发/代写/部署等未覆盖能力时,必须使用此技能。只读流程:盘点并全文读取 bundle → 映射实际主题与读者任务 → 对候选名做范围承诺、中英一致与误导含义检查 → 独立反向审查 → 输出中文标题、英文目录名与范围或日期限定;结论固定标记待确认,重命名与提交需另行授权。不用于生成知识包、交付门禁、方法论编排或通用研究报告。

知识包命名审计 Skill

用户说"这个名字不太准确"时,先把内容读全,再谈名字。

1. 这个技能解决什么

知识包(bundle)的目录名、标题与副标题,是读者和检索系统看到的第一句承诺。名字比内容宽,读者会按名字预期并不存在的能力;名字比内容窄,真实价值又检索不到;中英文名各说各话,同一份包在两个入口被描述成两件事。

本技能只做一件事:在不修改任何文件的前提下,用读到的内容判断一个名字是否准确,并给出可复核的替代建议。

适用信号:

  • "这个 bundle 名字不太准确 / 范围不对 / 太宽 / 太窄"
  • "目录名和内容对不上" "标题像在承诺开发、代写或部署,但包里没有"
  • "中文名和英文目录名不一致" "研究快照该不该在标题里写日期"

不适用(换轨):

任务交给
从文章生成新 bundlewechat-public-okf
交付前跑 toctree、UTF-8、索引门禁,写 log.mdokf-bundle-delivery-review
方法论编排(复盘、洞察、萃取、提交)seven-concepts-cmd
通用研究报告与竞品分析research-guide
真正执行重命名或提交本技能不执行;需用户单独授权后按仓库提交规范处理

为什么? 命名审计最容易越界成"顺手把名字改了"。一旦改动文件,审计结论就与工作树状态绑在一起,别人无法判断是"名字变准了"还是"内容被改得迎合名字"。只读把判断与变更分开。

为什么? 名字的准确性只能由内容证明,不能由推荐 JSON、bundle 自述或历史结论证明。上游材料常把"看起来覆盖"写成"已经覆盖",所以必须回到文件本身建立证据。

2. 输入与前置

输入必填缺失时
bundle 目录绝对路径是停止,请用户给出路径;不按名字猜目录
候选标题或目录名否从 S1 的主题映射结果提名
是否已有"已定名"结论否默认没有;把任何既有结论视为待验证候选

预检(只读):

  1. ls bundle 目录,确认含 index.md;不存在则停止。
  2. 列出全部 .md 文件(含子目录),得到总数 N。
  3. 记录 git status --short -- <bundle>,作为"本轮未改文件"的基线。
  4. 若用户提到其他会话或推荐给出的结论,只当线索,不当证据。

为什么? 先固定文件清单和 git 基线,后面才能证明审计没有改动内容,也才能在文件被并行修改时发现结论已过期。

3. 决策树

收到命名疑问
├─ 目录不存在或没有 index.md? → 停止:先确认路径,不猜内容
├─ 关键文件未读全? → 降级:结论限定为"基于已读 N/M 个文件",列出未读清单
├─ 用户给了候选名? → 直接进入 S2 逐项审查
└─ 没有候选名? → 先做 S1 主题映射,再从实际主题提名(S4)

4. 工作流(S0–S5,全程只读)

S0 盘点与覆盖台账

  • 列出全部 Markdown 文件,逐个记录"已读/未读"和用途(索引、概念、参考、日志、示例)。
  • 优先读 index.md、概念目录、事实台账与核验记录;这些决定"包实际承诺了什么"。
  • 输出覆盖台账:已读 X / 总数 N;未读文件逐条列出并说明是否影响结论。

S1 映射实际主题与读者任务

  • 每个概念文档提炼一句"它实际讲什么",不抄标题。
  • 汇总读者能完成的任务(读完能做什么),与文档实际提供的步骤一一对应。
  • 单列"包明确不提供的能力":没有代码、没有部署步骤、没有代写服务、没有跨平台投稿流程等,按实际内容写。
  • 核对内部口径:若文中已声明某类对象不宜合并称呼,后续命名不得把它们并成一个总称。

S2 候选名三项检查

对每个候选名逐项判定并留证:

检查问题不通过的表现
范围承诺名字承诺的能力,内容是否真的覆盖?名字含"开发、代写、部署、多平台发布",正文只有选题、素材与提交流程
中英一致中文标题与英文目录名是否表达同一范围?中文"参赛准备",英文 publishing;或中文很窄、英文很宽
误导含义是否有歧义、同音、行业黑话或过度营销?把"提交材料"读成"代提交";把"研究快照"读成"官方指南"

同时检查时效性:内容若是某一日期的研究快照,名字或副标题应注明范围与日期,避免读者把它当长期有效的权威结论。

S3 独立反向审查

  • 用四个视角攻击入围候选:陌生人(只看名字会以为什么)、检索者(会用什么词找它)、内容维护者(名字是否逼着以后写不属于包的内容)、范围审查者(名字是否超出证据)。
  • 每个被否掉的候选保留否决理由;只留最终答案会让下一轮无法复核。
  • 若所有候选都不成立,允许结论是"证据不足,暂不改名"。

S4 产出命名建议

输出三件套,范围必须一致:

  1. 中文标题:面向读者,直接说明内容与读者任务。
  2. 英文目录名:kebab-case,与中文标题同范围,不用宽泛总称。
  3. 副标题或限定(按需):平台范围、内容边界、研究快照日期。

状态固定写"待确认";不得写成"最终名称"或"已批准"。

S5 只读收尾

  • 不重命名目录、不改 index.md、不写 log.md、不提交。
  • 若用户要求执行改名:先给出改动面预览(旧路径到新路径、受影响的 toctree、索引与链接),等待单独授权;执行与门禁交给交付流程,不在本技能内完成。
  • 复跑 git status --short -- <bundle>,确认与基线一致。

为什么? 把建议与执行分开,才能让用户在不承担改动风险的情况下比较多个名字;确认后再改,也只改一次。

5. 输出模板

结论:建议改名 / 保留原名 / 证据不足
覆盖:已读 X / 共 N 个文件;未读:...
实际主题:...
读者任务:...
明确不提供:...
候选名判定:
| 候选 | 承诺范围 | 内容覆盖 | 中英对齐 | 判定 | 理由 |
推荐:中文标题「...」|英文目录名 `...`|副标题「...」
状态:待确认(未获用户批准;未重命名、未改文件、未提交)
缺口:...
下一步:需单独授权的动作

6. 命名判定矩阵

观察合理判定错误判定
名字含"发布",正文只讲提交材料准备范围过宽,收窄到实际覆盖的任务名字没问题,反正读者会看正文
中文标题与英文目录名范围不同中英不一致,必须统一英文只是技术标识,无所谓
候选名来自推荐 JSON,未被用户确认待验证候选已定名,直接沿用
内容为单日研究快照名字或副标题注明日期与范围当作长期权威结论命名
包内已声明三类对象不宜统一称呼名称不得合并为一个总称用"三场××"概括
关键文件未读结论限定范围并列缺口按目录名推断内容

7. Gotchas(隐性陷阱)

#陷阱表现正确做法
1用 bundle 自述当事实照抄 index 里的"覆盖全流程"回到概念与参考文档核对实际步骤
2把文件数当内容用"15 篇文档"支撑一个宽名字名字描述内容与任务,不描述文件数量
3名字比内容宽正文没有开发或部署,名字却写"开发与发布"删掉未被覆盖的能力词
4中英各说各话中文"参赛准备",英文 publishing两侧表达同一范围,必要时加限定
5用状态给名字背书"因为包是 draft,所以名字可以宽"状态与命名无关,按内容判定
6复用被内部否定的统称文中说三类对象不宜合并,名字仍用总称采用文中已确认的称呼粒度
7把建议写成已批准报告写"最终名称已确定"固定写"待确认",并列出授权缺口
8审计顺手改文件边审边改 index 或重命名目录只读;改动需单独授权与预览
9忽略时效研究快照名字不写日期用副标题注明范围与日期

8. 安全检查清单

执行前逐项确认:

  • 已确认 bundle 路径存在且含 index.md
  • 已列出全部 Markdown 文件并记录已读/未读
  • 实际主题与读者任务来自文件内容,未照抄 bundle 自述
  • 每个候选名都有范围承诺与覆盖证据
  • 中文标题与英文目录名表达同一范围
  • 已做独立反向审查并保留否决理由
  • 结论标记"待确认",未声称用户批准
  • 时效性内容已在副标题注明范围或日期
  • 未重命名、未修改 bundle、未写 log.md、未提交
  • 结束时 git status 与基线一致

为什么? 这张清单对应本技能两类失败:把"读了一部分"当成"读全了",以及把"建议"当成"已执行"。两者都不会报错,只能靠逐项核对拦住。

9. 幂等与重入

探针状态重入动作
同一 bundle 已有审计结论文件清单与 mtime 未变复用结论,不重复全文读取
同一 bundle 文件有新增或修改清单变化只重读变更文件,更新覆盖台账与结论范围
用户已确认推荐名已获明确批准停止提名,转为改动面预览;执行需另行授权
候选名被用户替换新候选回到 S2 与 S3,不沿用旧判定
结论为"证据不足"未读文件仍不可得保留该结论,不凭目录名补推

10. 变更记录

版本日期变更
1.0.02026-10-28初始版本:只读覆盖台账、主题与读者任务映射、候选名三性检查、独立反向审查、待确认命名建议、只读边界与重入规则;萃取自会话 afb0eaf2-dff2-41f6-a96d-5a88922d8709 的 bundle 命名质疑实战
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall