debug-specs

调试规范

如果尚未执行过，请始终使用技能 load-plain-reference 来获取 ***plain 语法规则。

何时使用

• 用户发现运行中的应用存在错误（视觉、行为、崩溃、性能）。
• 一致性测试或单元测试失败。
• 生成的代码出现意外或错误行为。
• 用户指出某项功能规范似乎有误。

指导原则

plain_modules/<module>/code/ 和 plain_modules/<module>/tests/ 中的生成代码均为只读——它们仅作为诊断依据。所有修复只能应用于 .plain 规范文件。工作流程为：观察 → 阅读生成的代码 → 追溯到规范 → 修复规范。

输入

1. 模块名称——用于确定 plain_modules/<module_name>/ 目录（code/ 和 tests/）以及对应的 .plain 文件。
2. 用户的观察——哪里出了问题？可以是错误描述、截图、测试失败、错误消息，或笼统的“这不太对劲”。
3. 可选：特定功能规范——如果用户怀疑某项特定规范有问题，则从该规范着手。否则，进行全面调查。

阶段 1 — 理解上下文

1. 阅读该模块的 .plain 文件——包括 frontmatter、定义、实现要求、测试要求和所有功能规范。还要阅读 import 和 requires 链。
2. 仔细阅读用户的观察。 复述一遍以确认理解。确定：
   • 预期行为是什么？
   • 实际行为是什么？
   • 这是视觉问题、逻辑问题、崩溃问题，还是数据问题？

阶段 2 — 调查生成的代码

阅读 plain_modules/<module_name>/code/ 中的文件，了解渲染器生成了什么。不要修改任何生成的文件。

2a. 缩小搜索范围

如果用户指出了特定规范或区域：

• 找出实现该规范行为的生成文件。
• 阅读这些文件，了解当前实现。

如果调查范围较广：

• 从入口点开始，沿着与观察到的问题相关的执行路径追踪。
• 根据观察缩小范围：UI 问题 → 检查组件/视图；逻辑问题 → 检查业务逻辑/提供程序；数据问题 → 检查模型/存储库。

2b. 阅读相关生成代码

针对每个相关文件：

1. 阅读代码并了解其作用。
2. 将其行为与规范中的要求进行比较。
3. 记录差异——即代码与规范意图不符之处。

2c. 检查一致性测试和单元测试（如相关）

如果错误表现为测试失败：

1. 阅读失败的测试——一致性测试位于 plain_modules/<module_name>/tests/<functionality>/，单元测试位于 plain_modules/<module_name>/code/ 内。
2. 理解测试的预期与实现的实际行为。
3. 确定测试预期是否正确（符合规范）或错误（不符合规范）。

阶段 3——诊断根本原因

从生成的代码反向追溯到规范。根本原因有五种——务必先确定适用哪一种，再进行修改：

根本原因	症状	修复方法
规范含糊	规范意图正确，但表述足够含糊，导致渲染器的解读与预期不同。	在规范中补充明确细节，消除歧义。
缺少规范	任何规范都未涵盖所需行为。渲染器没有依据，因此没有执行任何操作或自行作出了选择。	使用 add-functional-spec 技能添加新的功能规范。
规范冲突	两条规范相互矛盾，导致渲染器产生不一致的行为。	使用 resolve-spec-conflict 技能。
规范错误	规范明确描述了错误的行为。渲染器忠实地按规范实现，但规范本身有误。	重写规范，描述正确的行为。
缺少实现要求	规范正确，但实现要求未能为渲染器提供足够的指导，无法生成正确代码（例如，缺少库、架构约束或平台细节）。	使用 add-implementation-requirement 技能添加或更新实现要求。

如何诊断

1. 阅读规定有问题行为的规范。 该规范是否清晰、明确地描述了正确行为？
   • 如果规范清晰且正确，但代码有误 → 规范含糊（渲染器误解了规范）或缺少实现要求。
   • 如果规范完全没有提及该行为 → 缺少规范。
   • 如果规范明确描述了错误的行为 → 规范错误。
2. 检查是否存在冲突。 是否有其他规范覆盖或 contradict 了该行为？
   • 阅读涉及相同概念的所有功能规范。
   • 如果两条规范存在冲突 → 规范冲突。
3. 检查实现要求。 渲染器是否缺少正确实现所需的指导？
   • 实现要求是否指定了正确的库、模式或约束？
   • 如果缺少特定于平台或框架的细节 → 缺少实现要求。

阶段 4——修复规范

根据诊断出的根本原因应用修复。使用相应的技能：

根本原因	使用的技能
规范含糊	直接编辑规范——添加子项目符号或改写以使其更清晰
缺少规范	add-functional-spec
规范冲突	resolve-spec-conflict
规范错误	直接编辑规范——重写错误部分
缺少实现要求	add-implementation-requirement

修复指南

• 尽量少改。 只修改修复已观察到的问题所必需的内容。避免重写无关规范。
• 保持时间顺序。 如果要添加新规范，请根据现有规范的顺序正确放置。
• 与语言无关。 功能规范描述行为，而不是实现方式。特定于平台的指导应放在实现要求中。
• 遵守 200 LOC 限制。 如果修复使规范过于复杂，请使用 break-down-func-spec 将其拆分。
• 检查是否产生新冲突。 编辑后，运行一次 analyze-func-specs，并提供已编辑的规范以及涉及相同概念的所有现有规范，验证修复不会与其他规范冲突。批量分析器会在一次调用中报告所有冲突的规范对；使用 resolve-spec-conflict 逐一解决。

阶段 5 — 验证并报告

1. 完整重新阅读已修改的 .plain 文件，确认内容正确。
2. 向用户总结调查结果：
   • 观察到了什么（Bug）
   • 生成的代码做了什么（代码中的症状）
   • 哪些规范导致了问题（根本原因）
   • 规范做了哪些修改（修复）
   • 重新渲染后预期会发生什么
3. 如果无法确定，请先向用户说明诊断结果和建议的修复方案，并在修改前征求确认。有些 Bug 可能有多种原因——有疑问时，请说明各种可能性，让用户决定。

调试策略

策略 1：从观察出发（最常见）

从用户的观察出发，逆向追溯代码中的规范。

User sees bug → Read generated code → Find the responsible code path →
Identify which spec governs that code → Diagnose why the spec produced wrong code →
Fix the spec

策略 2：聚焦规范

用户怀疑某个特定规范时，直接将该规范与生成的代码进行比较。

User points to spec → Read the spec → Find the generated code that implements it →
Compare spec intent vs. code behavior → Diagnose the gap → Fix the spec

策略 3：从测试失败出发

测试失败时，以测试为切入点。

Read failing test → Understand what it expects → Read the implementation →
Determine if the test or the implementation is wrong → Trace back to the spec →
Fix the spec (or test reqs/acceptance tests if the test itself is wrong)

策略 4：差异比较

Bug 在添加新规范后出现时，比较添加前后的情况。

Identify the newly added spec → Read the specs it might conflict with →
Check if the new spec introduced the bug → Use resolve-spec-conflict or
revise the new spec

常见陷阱

修复代码，而不是规范

切勿修改 plain_modules/<module>/code/ 或 plain_modules/<module>/tests/ 中的文件。即使代码中的修复显而易见，也必须在 .plain 文件中进行修改，才能确保重新渲染后修改仍然有效。

处理症状，而不是根本原因

如果用户说“按钮位置不对”，不要只是补充定位细节。要调查渲染器为何将按钮放在那里——根本原因可能是缺少布局规范、屏幕描述含糊，或与其他规范冲突。

过度细化修复方案

在功能规范中添加过多实现细节（例如具体像素值、组件名称、CSS 属性）会使规范变得脆弱。优先采用行为层面的修复。平台特定的指导应使用实现要求。

忽略连带影响

规范修复可能会影响引用相同概念的其他规范。修改后务必检查相邻规范是否存在冲突。

验证清单

• 已清楚理解用户的观察（预期行为与实际行为）
• 已阅读生成的代码，以了解当前实现
• 已诊断根本原因（含糊／缺失／冲突／错误／缺少实现要求）
• 仅在 .plain 文件中应用修复——未修改生成的代码
• 修复精简，并针对观察到的 Bug
• 修复不会与现有规范产生新的冲突
• 修改后的规范未超过 200 LOC 限制
• 修改后的规范仍与语言无关
• 保留了时间顺序
• 已向用户说明调查结果和修复方案