Back to Details

spec-gap-sweep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sweep All Specs for Gaps

扫描所有Spec以排查漏洞

Estate-wide health. Individual spec skills go deep on one feature; this goes wide and finds what nobody maintained.
Reports only. Fixing is 
spec-maintain-on-ship
.
Format authority: 
references/spec-format.md
. Spec root: 
.engineering/config.yaml
.
全资产健康检查。单个spec技能针对某一功能深入分析；本技能则全面排查，找出无人维护的内容。
仅生成报告。 修复操作请使用
spec-maintain-on-ship
。
格式依据：
references/spec-format.md
。Spec根目录：
.engineering/config.yaml
。

When to use

使用场景

  • Periodic review — monthly or quarterly.
  • "What state are our specs in?"
  • Deciding where to spend maintenance effort.
  • Finding which open questions are actually blocking work.
Not this skill: auditing one spec against code (
spec-audit-drift
), fixing anything (
spec-maintain-on-ship
).
  • 定期审核——每月或每季度。
  • 询问“我们的spec处于什么状态？”时。
  • 决定维护工作投入方向时。
  • 查找实际阻碍工作的未解决问题时。
不属于本技能的场景：针对代码审核单个spec（
spec-audit-drift
）、修复问题（
spec-maintain-on-ship
）。

What to look for

排查要点

1. Roll-up statuses that disagree with their behaviours

1. 与行为不符的汇总状态

Recompute every front-matter 
status
from the behaviour badges and report mismatches. A spec marked 
implemented
containing a 🔵 behaviour is the common case, and it's how an estate starts overstating itself.
根据行为徽章重新计算所有前置元数据中的
status
，并报告不匹配情况。常见情况是标记为
implemented
的spec包含🔵行为，这也是资产开始夸大自身状态的原因。

2. Partial behaviours with no note

2. 无说明的部分行为

Every 🟡 requires a one-line note on what's missing. A 🟡 without one is work nobody is tracking, described nowhere else. The note is the requirement; a ticket reference is optional, and absent entirely when 
tickets.provider
is 
none
.
Where a provider is configured, also flag 🟡 behaviours whose ticket is closed. With 
provider: github
, resolve it properly — 
gh
is authenticated, so this is a real check rather than a guess. With 
linear
, 
jira
, or 
custom
, attempt it only if credentials exist and say plainly when you couldn't; an unresolvable ticket is evidence of nothing.
A closed ticket means the badge is worth verifying and nothing more. Report it as such and hand to 
spec-maintain-on-ship
, which requires the code and the test before promoting anything. Never infer a badge from tracker state — the spec owns intent, the tracker owns scheduling, and collapsing the two puts the estate back to being optimistic.
A closed ticket with a long thread is also the best candidate for 
spec-harvest-discussion
: that's where decisions were made that the spec never absorbed.
每个🟡行为都需要一行关于缺失内容的说明。无说明的🟡行为属于无人跟踪的工作，且未在其他地方记录。说明即为需求；工单参考为可选项，当
tickets.provider
设为
none
时可完全省略。
若已配置工单提供商，还需标记工单已关闭的🟡行为。对于
provider: github
，需通过已认证的
gh
工具进行准确检查，而非猜测。对于
linear
、
jira
或
custom
提供商，仅在存在凭证时尝试检查，且无法检查时需明确说明；无法解析的工单不代表任何问题。
工单关闭仅意味着该行为徽章值得验证，仅此而已。需如实报告此类情况，并交由
spec-maintain-on-ship
处理，该技能要求在升级状态前需核对代码和测试。绝不能根据工单系统状态推断徽章状态——spec定义意图，工单系统负责排期，混淆两者会导致资产状态再次过于乐观。
带有长讨论线程的已关闭工单也是使用
spec-harvest-discussion
的最佳候选对象：这些讨论中包含的决策从未被spec吸收。

3. Ageing future behaviours

3. 长期未处理的未来行为

🔵 behaviours that have sat untouched for a long time. Report age from git history rather than guessing.
Old 🔵 behaviours are not automatically a problem — a design record is allowed to sit. But a cluster of them in one spec usually means the feature was designed far beyond what anyone intends to build, and the spec would read better with them moved to Future Considerations.
长期未触动的🔵行为。需根据git历史记录报告时长，而非猜测。
老旧的🔵行为不一定是问题——设计记录可以长期留存。但同一spec中出现大量此类行为通常意味着该功能的设计远超实际计划开发范围，将这些行为移至“未来考虑事项”部分会使spec更易读。

4. Open Questions, split by kind

4. 未解决问题（按类型划分）

  • Blocks Bn:
    questions     — these are the ones that matter. Each is a behaviour that cannot proceed until someone decides something. List them with the behaviour they block and how long they've been open. Lead the report with these: they're the only category unblockable by a single conversation.
  • Unprefixed questions older than a few months — either they stopped mattering, or nobody owns them.
  • Settled:
    questions     — healthy. Count them but don't flag them; they're recorded reasoning, not debt.
  • Blocks Bn:
    类问题    ——这些是关键问题。每个此类问题都会导致某一行为无法推进，直至有人做出决策。需列出这些问题及其阻碍的行为、已持续时长。报告需以此类问题开头：这是唯一可通过单次沟通解决的类别。
  • 无前缀且存在数月以上的问题——要么已不再重要，要么无人负责。
  • Settled:
    类问题    ——属于健康状态。仅统计数量，无需标记为债务；这些是已记录的推理过程，而非债务。

5. Modules with no specs

5. 无Spec的模块

Compare the module structure of the codebase against the spec estate. A module with substantial code and no spec is the largest kind of gap, and the least visible — you can't notice a spec that was never written.
Rank by code volume and change frequency. A large, frequently-changed, unspecced module is where the estate's blind spot costs most.
对比代码库的模块结构与spec资产。包含大量代码但无spec的模块是最大的漏洞，且最不易被发现——你无法注意到从未编写过的spec。
需按代码量和变更频率排序。规模大、变更频繁且无spec的模块是资产盲区造成最大损失的地方。

6. Structural problems

6. 结构性问题

  • Specs missing required section headers.
  • Behaviour IDs that skip or repeat.
  • Flow contracts whose Mermaid sibling is older than the YAML — the diagram is stale.
  • covers
    references pointing at behaviour IDs that no longer exist.
  • 缺少必填章节标题的spec。
  • 跳过或重复的行为ID。
  • Mermaid流程图对应的YAML文件更新更早——图表已过时。
  • covers
    引用指向已不存在的行为ID。

Report

报告要求

Lead with blocking questions, then unspecced modules by size, then everything else. Order by what's costing most, not by category.
For each item: the spec path, the ID, the evidence with dates or counts, and the specific action. End with estate-level counts — specs by status, behaviours by badge, open questions by kind — so the trend is visible when you run it again.
Change nothing.
报告需以阻碍性问题开头，然后是按规模排序的无spec模块，最后是其他内容。需按影响成本排序，而非按类别排序。
每个条目需包含：spec路径、ID、带有日期或数量的证据，以及具体操作建议。结尾需包含资产层面的统计数据——按状态划分的spec数量、按徽章划分的行为数量、按类型划分的未解决问题数量——以便再次运行时能看到趋势变化。
不得修改任何内容。

Quality gate

质量检查清单

  • Every spec parsed; parse failures reported rather than skipped.
  • Roll-ups recomputed, not read.
  • Ages taken from git history, not estimated.
  • Blocking questions separated from ordinary ones and led with.
  • Unspecced modules ranked by size and change frequency.
  • Settled questions counted, not flagged as debt.
  • Nothing modified.
  • 所有spec均已解析；解析失败需报告，而非跳过。
  • 汇总状态为重新计算所得，而非直接读取。
  • 时长取自git历史记录，而非估算。
  • 阻碍性问题与普通问题分离，并置于报告开头。
  • 无spec模块按规模和变更频率排序。
  • 已解决问题仅统计数量，不标记为债务。
  • 未修改任何内容。

Anti-patterns

反模式

  • Treating every open question as debt. Settled ones are the system working; flagging them punishes recording your thinking.
  • Reporting counts with no ranking. A list of 200 items with no order is not actionable.
  • Skipping unparseable specs. Those are the most broken ones.
  • Ignoring modules with no specs because the sweep only looks at files that exist.
  • 将所有未解决问题视为债务。已解决问题是系统正常运作的体现；标记此类问题会打击记录思考过程的积极性。
  • 仅报告数量而不排序。无顺序的200条列表不具备可操作性。
  • 跳过无法解析的spec。这些是最破损的spec。
  • 忽略无spec的模块，因为扫描仅检查已存在的文件。

Related skills

相关技能

  • spec-maintain-on-ship
    — fix what this finds
  • spec-plan-gap
    — plan a spec for an unspecced module
  • spec-audit-drift
    — go deep on a spec this flagged
  • spec-visualize
    — the same data, browsable
  • ask-questions
    — asks current-work decisions; this skill only reports
  • spec-maintain-on-ship
    ——修复本技能发现的问题
  • spec-plan-gap
    ——为无spec的模块规划spec
  • spec-audit-drift
    ——深入分析本技能标记的spec
  • spec-visualize
    ——以可浏览方式呈现相同数据
  • ask-questions
    ——询问当前工作的决策；本技能仅生成报告