scope-creep-detector

Scope Creep Detector 是一个用于分析 git diff 与声明意图之间关系的技能，旨在检测代码变更中的范围蔓延（scope creep）。它帮助开发者识别那些超出原始意图的变更，例如无关文件、过大的拉取请求、超出修复范围的改动以及新增依赖等。

用途

该技能主要用于在代码审查前评估变更的范围。它适用于以下场景：

• 在打开拉取请求前，diff 可能已超出其意图。
• 当 bug 修复触及意外文件或子系统时。
• 当用户询问暂存更改是否过于宽泛时。
• 当 diff 包含依赖、公共 API、配置、CI 或构建更改时。
• 当用户希望为混合变更制定具体的拆分计划时。

该技能不适用于：格式化代码、运行 linter、编写提交信息、在已同意的范围内审查正确性、安全性或测试质量、衡量跨多个提交的历史项目增长，以及未经用户批准编辑或还原文件。

主要能力

该技能的核心是一个确定性统一 diff 解析器和分类器（scripts/scope_creep.py），它能够：

• 解析 git diff，并与声明的意图进行对比。
• 识别 in_scope（至少有一个意图/路径关键字重叠的文件路径）。
• 识别 likely_creep（没有重叠的路径，并给出原因和检测到的信号）。
• 检测 new_deps（在支持的清单格式中引入的依赖）。
• 检测 api_renames（附近移除和添加的公共函数或类声明）。
• 检测 config_edits（CI、容器、构建、YAML 和 TOML 更改）。
• 提供 stats（代码变动量、子系统数量、过大的 hunk 以及仅格式化的文件）。

该技能还提供参考文档 references/scope-signals.md，其中包含信号定义、阈值和限制。

使用方式

首先，确定意图。使用用户提供的一行意图，保持具体，例如“fix null dereference in parser”或“add retry limit to webhook delivery”。如果没有提供意图，脚本会回退到当前分支名称。如果分支名称通用、分离或与工作无关，则需要请求一行意图。

然后，从技能目录运行分类器，指向目标仓库。支持多种 diff 来源：

• 工作树 diff：python3 scripts/scope_creep.py --repo /path/to/repo --intent "fix null dereference in parser" --json
• 暂存 diff：python3 scripts/scope_creep.py --repo /path/to/repo --staged --intent "fix null dereference in parser" --json
• 基于合并基的分支 diff：python3 scripts/scope_creep.py --repo /path/to/repo --base main --intent "fix null dereference in parser" --json
• 保存的 diff 或标准输入：python3 scripts/scope_creep.py --diff change.diff --intent "parser fix" --json 或 git diff --staged | python3 scripts/scope_creep.py --diff - --intent "parser fix" --json

仅在仓库有文档记录的理由更改默认变动阈值时，才使用 --hunk-threshold。不要仅仅为了消除警告而调整阈值。

解释 JSON 输出

在提出建议前，阅读 references/scope-signals.md。将分类器视为分诊证据，而非作者意图的证明。

JSON 输出包含以下字段：

• in_scope：文件路径与意图/路径关键字至少有一个重叠。
• likely_creep：没有重叠的路径，附带原因和检测到的信号。
• new_deps：在支持的清单格式中引入的依赖。
• api_renames：附近移除和添加的公共函数或类声明。
• config_edits：CI、容器、构建、YAML 和 TOML 更改。
• stats：代码变动量、子系统数量、过大的 hunk 以及仅格式化的文件。

空数组也是证据。应说明未检测到信号，而不是保证 diff 一定在范围内。

建议处理方式

对 likely_creep 中的每一项给出处理建议：

• Keep：当路径对于声明的意图是必要的，且连接直接时。用一句话解释连接。
• Split：当它可以独立落地、属于另一个子系统，或引入了意图不需要的依赖、API 重命名、配置编辑或大型 hunk 时。为后续变更命名文件或 hunk。
• Justify：当跨领域编辑无法安全分离时。说明需要它的不变量或构建约束，并指出审查风险。

当证据模糊时，优先选择 split。永远不要声称零重叠分数证明文件无关。路径词汇是一种廉价、确定性的代理。

编写范围报告

使用以下紧凑结构：

• 意图和 diff 来源
• 涉及的文件和子系统，以及总添加和删除行数
• 范围内的更改
• 可能蔓延的更改及信号证据
• Keep、split 或 justify 表格
• 建议的后续分组（如果有）

命名文件路径和 hunk 头。对于过大的混合 hunk，解释脚本无法自动拆分它，并描述最小的连贯编辑。在应用任何拆分、还原、暂存或提交操作前，先询问用户。

文件

• scripts/scope_creep.py：确定性统一 diff 解析器和分类器
• references/scope-signals.md：信号定义、阈值和限制

限制

该技能完全在本地运行，不进行网络调用，也不会修改工作树、索引、提交或分支。它不适用于格式化代码、运行 linter、编写提交信息、审查正确性、安全性或测试质量、衡量历史项目增长，以及未经用户批准编辑或还原文件。分类器仅提供分诊证据，不能证明作者意图。路径词汇重叠是一种廉价、确定性的代理，零重叠分数不能证明文件无关。