507-inspect

name	507-inspect
description	不围绕某次交付 diff，只读检查代码库的模块形状、接缝与架构摩擦，产出证据候选报告交给 507-simplify。Use when user says 架构审查, 代码体检, 找重构机会, 浅模块改深, 找接缝, inspect architecture, codebase architecture review, refactor opportunity. 明确变更范围的交付 review 使用 507-review。

架构审查（inspect）

只读检查代码库，找出真实的架构摩擦与“加深机会”：让小接口隐藏更多行为，减少调用者跳转，集中变更并改善可测性。507-inspect 只报告、不修改；完整候选报告交给 507-simplify，由后者建立行为基线、验证、修改或带证据关闭。

合同

• 只读：不得修改源代码、测试、配置或文档；不得以补测试、格式化或生成报告为由改变项目内容。
• 代码证据：每张卡必须引用可定位的代码观察（文件、符号、调用路径、测试事实或可复现现象），不能只写架构直觉。
• 置信等级：每张卡必须给 High / Medium / Low，并说明等级依据和未知点。
• 完整交接：报告包含全部候选卡、未采纳的观察与范围说明，整体交给 507-simplify；不要求每张卡最终改代码。
• 不承诺行为变化：候选只描述摩擦和内部简化机会；若目标需要改变公开 API、公开契约或调用者可观察行为，明确标记为需求实施，不得放入 507-simplify。
• 宿主中立、公开通用：只依赖代码、项目文档和项目既有验证信息；不假定特定 Agent 宿主、调度器、插件或命令格式，不使用旧斜杠命令。

核心词汇

• Module（模块）：有接口与实现的东西，函数、类、包或切片均可。
• Interface（接口）：调用者必须知道的一切，包括类型、不变量、错误模式、顺序和配置。
• Depth（深度）：单位接口能调动的行为量；小接口藏大量行为即为深。
• Seam（接缝）：不就地改也能改变行为的位置。
• Adapter（适配器）：在接缝处满足接口的具体物。
• Leverage（杠杆）：一次实现被多处调用者复用的收益。
• Locality（局部性）：修改集中在少数位置、缺陷不扩散的收益。

范围与前置阅读

先确认目标范围；未指定范围时，只做必要的项目结构读取，不自行承诺全库扫描。按项目规范读取适用的 AGENTS.md、README、术语表、决策记录、目标模块及相关测试。遵循既有 ADR；发现真实摩擦与 ADR 冲突时，记录冲突和证据，不自行重开决策。

记录：

• 检查范围与明确未检查范围；
• 使用过的文档、代码入口和验证信息；
• 代码版本或其他可复现的观察上下文。

探索信号

跟着真实维护摩擦走，重点观察：

• 理解一个概念必须在多个浅模块间反复跳转；
• 接口与实现几乎一样复杂，调用者承担了本应隐藏的流程；
• 为了测试硬抽纯函数，但真正风险藏在调用顺序或接缝组合；
• 模块跨接缝泄漏内部假设，或 adapter 没有真实变化；
• 重复、透传、职责分散导致错误修复无法集中；
• 关键路径没有测试，或按当前接口难以建立可靠验证信号。

使用删除测试：删除模块后，若复杂度消失且没有在调用处重现，它可能只是透传；若复杂度会在多个调用处重现，它可能正在提供深度和杠杆。不要机械套规则。

候选卡格式

每个候选一张卡，至少包含：

### Candidate <稳定编号>: <简洁标题>
- files_and_modules: <涉及文件、符号、module 与调用者>
- code_observation: <可定位的代码事实、调用路径、测试事实或复现现象>
- confidence: <High | Medium | Low>
- confidence_basis: <为何达到该等级；仍缺什么证据>
- friction: <调用者或维护者承受的具体摩擦>
- deletion_test: <删除后复杂度消失，还是会在调用处重现；证据是什么>
- seam_observation: <现有 seam/adapter 与真实变化；没有则写无>
- deepening_direction: <白话描述可探索的内部加深方向，不指定实现步骤>
- locality_and_leverage: <预期如何集中修改、复用行为、改善测试>
- public_behavior_constraint: <必须保持的公开 API、契约和可观察行为>
- design_constraints: <已经确认的依赖、边界和不可违反条件>
- decision_status: <工程细节可自行收口 / 尚需用户决策；需要时引用 grill 共识>
- verification_gap: <需要 `507-simplify` 建立的基线或验证信号>
- recommendation: <Strong | Worth exploring | Speculative>
- status: <待 507-simplify 验证>

deepening_direction 只描述方向，不在 507-inspect 阶段拍板具体接口或修改方案。任何“收益”必须连接到 locality、leverage、depth 或验证面，不能只写“更优雅”。

工作流程

1. 只读探索

读取范围内的代码与上下文，沿调用者、接缝和测试追踪行为。用事实记录摩擦；不修改代码，不补测试，不把猜测写成结论。对每个观察标注证据位置和置信等级。

2. 形成完整报告

默认输出 Markdown；只有用户明确要求时才输出其他格式。报告包含：

1. 检查范围、版本上下文与未检查范围；
2. 观察摘要与证据质量；
3. 按优先级排列的全部候选卡；
4. 与现有 ADR 的关系和冲突；
5. Top 推荐及推荐理由；
6. 仍无法判断的观察、所需验证信号和明确“不建议修改”的项；
7. 交接说明：将完整报告交给 507-simplify，由其逐项判断成立、关闭或路由需求实施。

报告不把候选列表变成修改步骤，也不要求用户在 507-inspect 内先选一张才能交接。

3. 收束可执行约束

每张卡在交接前都要写清公开行为不变量、依赖、范围和设计约束。内部 API（接口）、参数和模块细节由 agent 自行收口；只有产品意图、权责边界、不可逆成本或风险承受需要用户决定时，调用 507-grill 对齐并把共识引用回卡片。

若一个候选存在真实的接口取舍，至少比较两个差异成立的只读方案，再记录推荐方向及未解决风险。可使用宿主已有的只读并行能力，也可顺序完成；不得把某一种宿主工具写成流程前提。

4. 交接边界

报告完成即停止 507-inspect 的代码工作。后续若要简化，使用 507-simplify：它可以接收完整报告，也可以接收用户明确指定的范围；它必须为每项建立行为基线/验证信号，成立才修改，不成立带证据关闭。若需要改变产品行为或公开契约，则退出 507-simplify，进入需求与正常实施流程。

不覆盖什么

• 实际修改代码、测试、配置或文档；
• 为候选建立基线、运行修改后的回归验证或关闭候选；
• 新增能力、修正产品语义或其他行为变化的需求设计；
• 仅凭审美偏好进行重命名、格式化或大规模重排；
• 方案文档、工单或宿主专属执行编排。

与相邻技能的分工

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

收口检查

• 全部探索都在声明范围内，工作区没有写入。
• 每张卡都有可定位的代码观察证据。
• 每张卡都有置信等级及等级依据。
• 每张卡都说明公开行为不变量、设计约束、决策状态和 507-simplify 所需验证缺口。
• 报告包含全部候选、关闭/不建议项及未检查范围。
• 已明确把完整报告交给 507-simplify，没有把 507-inspect 变成修改入口。

完成与接力

• 完成信号：声明范围已读完，全部候选与关闭项都有代码证据、置信等级、行为不变量和验证缺口，工作区保持只读。
• 产物：完整架构摩擦报告，不是零散建议或直接修改。
• 候选出口：行为不变候选交给 507-simplify；需要改变产品语义的候选进入 507-grill、507-prd 或 507-issue；地图失真进入 507-map；只要求审查报告时直接结束。
• 回退条件：证据不足的观察降级置信度或列入未检查范围，不把猜测升级为改造任务。