507 Simplify

行为不变简化（simplify）

把已有代码的内部结构改得更深、更集中、更易验证，同时保持公开契约与调用者可观察行为不变。507-simplify 接收一个指定范围或完整的 507-inspect 报告，逐项验证后修改；不把“有候选”误当成“必须修改”。

合同

• 可直接处理两类输入：用户明确指定的文件/目录/模块范围，或 507-inspect 的完整候选报告。没有范围时不得自行扩大到全库。
• 逐项双层证据链：507-inspect 的代码观察证据是候选依据；507-simplify 还必须为每项建立行为基线或可执行验证信号。
• 先验证、后修改：只有基线/信号足以证明候选成立，且重构目标可定义时才修改代码；否则保留现状并带证据关闭该项。
• 行为不变：允许深改内部模块、抽象和接缝，但不得改变公开 API、公开契约、错误模式、时序、持久化语义、兼容性或其他调用者可观察行为。
• 行为变化即退出：若证据显示目标需要新增能力、修正产品语义或改变公开行为，停止该项，说明证据，并路由到需求澄清与正常实施流程；不得以 507-simplify 名义偷偷改变行为。
• 宿主中立：只依赖可获得的代码、文档、测试和项目验证命令；不假定特定 Agent 宿主、编排器、插件或命令格式。
• 公开通用：使用 module、interface、seam、adapter、depth、locality、leverage 等通用架构词；不要把宿主专属操作写进合同，也不使用旧斜杠命令作为入口或下一步。

不做什么

• 不做无证据的“顺手清理”、全库扫描或架构重设计。
• 不把 507-inspect 的推荐强度当作实施批准；Strong 也必须通过本 skill 的行为验证门槛。
• 不重写需求、不修复需要改变产品行为的问题、不替代需求规格或工单流程。
• 不为了制造 seam、adapter 或抽象而改代码；没有真实变化或复用证据时优先删除透传层。
• 不把通过测试等同于证明行为不变；测试只是验证信号的一部分。

输入与范围确认

按以下优先级确定输入：

1. 用户明确指定的文件、目录或模块；
2. 507-inspect 的完整报告；
3. 没有指定时，以当前 Git diff（版本差异）作为候选范围；若工作区没有相关差异，先询问是否改看某个 commit（提交）或明确路径，不自动扫描全库。

开始时记录：

1. 来源：直接范围、507-inspect 报告，或两者；报告必须完整接收，不只挑最方便的一张卡。
2. 范围：允许读取和修改的文件/目录/模块，以及明确不包含的邻接范围。
3. 目标：要降低的具体摩擦（如重复、泄漏、透传、难测接缝或局部性差）。
4. 不变量：公开 API、调用约定、错误与时序、数据格式、资源生命周期及用户可见结果中哪些必须保持不变。
5. 验证条件：现有测试、回归命令、类型/静态检查、可复现样例或其他项目既有信号。

若报告缺少定位证据、置信等级、范围或不变量，先补读代码和项目规范；仍无法建立验证信号时，带缺口证据关闭，不猜测修改。

每项重构的记录卡

无论来自报告还是直接指定，都为每项建立如下记录；记录可在工作报告中呈现，也可落在项目已有的变更载体中：

### Simplify item: 
- source: 
- scope: 
- observation: 
- confidence: ；
- claimed_friction: 
- public_invariants: 
- baseline: 
- verification_signal: 
- gate: 
- change: 
- result: 
- evidence: 

observation 必须来自代码事实，不写只有直觉的评价；confidence 不能省略。基线和验证信号必须说明“比较什么”以及“什么结果算通过”。

工作流程

1. 读取上下文并锁定范围

先读项目的适用规范、相关术语、决策记录、目标模块及其调用者和测试。核对 507-inspect 卡片与当前代码是否仍匹配。若已失效，记录差异并关闭，不按旧定位修改。

2. 建立行为基线

按风险选择最小但足够的基线组合：

• 现有单元/集成/端到端测试及其结果；
• 公开入口的输入—输出、错误、顺序、重试、并发或资源生命周期样例；
• 序列化、持久化、日志/事件等确属调用者或外部系统可观察的结果；
• 类型、静态检查、构建和回归命令；
• 对没有现成测试的路径，先记录可复现样例或建立不改变产品行为的验证信号。

基线不足以区分候选是否成立时，不先改代码。优先补验证信号；若补信号本身需要改变公开行为，则退出并路由需求实施。

3. 判断候选是否成立

用证据回答：

• 该摩擦是否在当前代码中真实存在，而非历史描述或偏好？
• 删除测试是否显示模块只是透传，或复杂度会在多个调用处重现？
• proposed seam 是否有真实变化；一个 adapter 只是一个假设，两个不同适配物才是接缝证据？
• 重构能否保持 public_invariants，并由 verification_signal 判定？

结论只有三类：

• 成立才修改：证据和信号足够，目标是行为不变的内部重构。
• 不成立，带证据关闭：摩擦不存在、报告已过时、收益不足，或无法建立可靠信号。
• 需要行为变化，退出并路由：目标超出内部重构合同。

4. 小步修改

一次只做一个可解释的内部重构，优先改善 locality、leverage、depth 和可测试性。可以合并/删除透传模块、收拢职责、重放接缝后的实现、替换内部 adapter 或重排私有抽象；不得借机修改公开 API 或可观察语义。

每一步保持代码可验证。若修改中发现必须扩大范围，先暂停并记录原因；不得静默修改范围外文件。

5. 验证与回归

对每项运行其基线对应的验证信号，并补做受影响调用者、接缝和错误路径的最小回归。比较重构前后：

• 公开入口结果、错误与时序是否一致；
• 兼容格式、持久化/事件语义和资源生命周期是否一致；
• 测试、类型/静态检查、构建及项目既有检查是否通过；
• 变更是否确实减少跳转、重复、泄漏或测试摩擦，而非只移动复杂度。

失败时回退该小步或停止该项，保留失败证据；不得通过放宽断言、删除覆盖或改变测试期望来“绿化”。

6. 收口报告

报告必须逐项覆盖完整输入报告，不修改的项也要列出。至少包含：

• 范围与未触及范围；
• 每项记录卡及成立/关闭/路由结论；
• 修改文件与内部结构变化；
• 行为不变的基线、验证信号和结果；
• 关闭项的反证或证据缺口；
• 仍需走需求实施的行为变化项；
• 未验证的风险和建议下一步（使用通用描述，不指定宿主命令）。

质量门槛

完成前逐项确认：

• [ ] 每项都有代码观察证据和置信等级。
• [ ] 每项都有改动前基线或明确验证信号。
• [ ] 只有成立项被修改；不成立项带证据关闭。
• [ ] 公开 API、契约和可观察行为未改变。
• [ ] 深改仅发生在允许范围内，接缝变化有真实理由。
• [ ] 相关验证已运行并记录结果，失败没有被掩盖。
• [ ] 行为变化候选已停止并路由，而非混入内部重构。

与相邻技能的边界

| 技能 | 责任 | |---|---| | 507-inspect | 只读发现摩擦，产出带代码观察证据与置信等级的完整候选报告；不修改。 | | 507-simplify | 本技能：逐项建立基线、验证、修改或带证据关闭；可独立接收指定范围。 | | 需求/规格工作流 | 处理新增能力、产品语义或公开行为变化。 | | 正常实现/审查工作流 | 执行已批准的行为变化，并验证交付质量。 |

完整报告交给 507-simplify，不要求每张卡都产生代码变更；“关闭”也是有证据的交付结果。重构完成后可用 507-review 独立审查；用户明确要求提交时再用 507-commit。

完成与接力

• 完成信号：每个指定候选都有“修改并验证”或“带证据关闭”的结论，公开契约与可观察行为保持不变。
• 产物：经验证的内部简化、逐项证据结论、测试结果和必要地图更新。
• 候选出口：需要行为变化的候选进入 507-grill、507-prd 或 507-issue；地图变化进入 507-map；完成后进入 507-review，用户明确要求提交时再进入 507-commit。
• 回退条件：无法建立行为基线或验证信号时停止该项，不凭结构偏好继续改造。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ssdiwu
• Source: ssdiwu/507-skills
• License: MIT

Install and usage instructions live in the source repository linked above.