Back to Details

debug-specs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug Specs

调试规范

Always use the skill 
load-plain-reference
to retrieve the ***plain syntax rules — but only if you haven't done so yet.
请务必使用技能
load-plain-reference
获取***plain语法规则——但仅在你尚未获取过的情况下使用。

When to Use

使用场景

  • The user observes a bug in the running application (visual, behavioral, crash, performance).
  • A conformance test or unit test is failing.
  • The generated code does something unexpected or incorrect.
  • The user points to a specific functional spec that seems wrong.
  • 用户观察到运行中应用程序存在bug（视觉、行为、崩溃、性能问题）。
  • 一致性测试或单元测试失败。
  • 生成代码出现意外或错误行为。
  • 用户指出某个特定功能spec存在问题。

Guiding Principle

指导原则

Generated code in 
plain_modules/
and 
conformance_tests/
is read-only — it exists solely as evidence for diagnosis. All fixes are applied exclusively to the 
.plain
spec files. The workflow is: observe → read generated code → trace to spec → fix the spec.
plain_modules/
和
conformance_tests/
中的生成代码为只读文件——仅作为诊断依据存在。所有修复必须仅应用于.plain规范文件。工作流程为：观察问题 → 读取生成代码 → 追溯到spec → 修复spec。

Input

输入信息

  1. The module name — identifies the 
    plain_modules/<module_name>/
    directory and the corresponding 
    .plain
    file(s).
  2. The user's observation — what is wrong? This can be a bug description, a screenshot, a test failure, an error message, or a general "this doesn't work right."
  3. Optional: a specific functional spec — if the user suspects a particular spec, start there. Otherwise, investigate broadly.
  1. 模块名称——用于定位
    plain_modules/<module_name>/
    目录及对应的.plain文件。
  2. 用户观察结果——具体问题是什么？可以是bug描述、截图、测试失败信息、错误提示或“这个功能无法正常工作”这类一般性反馈。
  3. 可选：特定功能spec——如果用户怀疑某个特定spec，可从该spec开始排查；否则进行全面调查。

Phase 1 — Understand the Context

阶段1 — 理解上下文

  1. Read the 
    .plain
    file(s)     for the module — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read 
    import
    and 
    requires
    chains.
  2. Read the user's observation carefully. Rephrase it back to confirm understanding. Identify:
    • What is the expected behavior?
    • What is the actual behavior?
    • Is this a visual issue, a logic issue, a crash, or a data issue?
  1. 读取模块对应的.plain文件——包括前置信息、定义、实现要求、测试要求及所有功能spec。同时读取
    import
    和
    requires
    依赖链。
  2. 仔细阅读用户的观察结果。重新表述以确认理解无误。明确：
    • 预期行为是什么？
    • 实际行为是什么？
    • 这是视觉问题、逻辑问题、崩溃问题还是数据问题？

Phase 2 — Investigate the Generated Code

阶段2 — 排查生成代码

Read files in 
plain_modules/<module_name>/
to understand what the renderer produced. Do not modify any generated files.
读取
plain_modules/<module_name>/
中的文件，了解渲染器生成的内容。请勿修改任何生成文件。

2a. Narrow the search

2a. 缩小搜索范围

If the user pointed to a specific spec or area:
  • Identify which generated files implement that spec's behavior.
  • Read those files to understand the current implementation.
If the investigation is broad:
  • Start from the entry point and follow the execution path related to the observed bug.
  • Use the observation to narrow down: UI issue → look at widgets/views, logic issue → look at business logic/providers, data issue → look at models/repositories.
如果用户指向特定spec或区域：
  • 确定哪些生成文件实现了该spec的行为。
  • 读取这些文件，理解当前实现逻辑。
如果需要全面排查：
  • 从入口点开始，跟踪与观察到的bug相关的执行路径。
  • 根据观察结果缩小范围：UI问题→查看组件/视图，逻辑问题→查看业务逻辑/提供者，数据问题→查看模型/仓库。

2b. Read the relevant generated code

2b. 读取相关生成代码

For each relevant file:
  1. Read the code and understand what it does.
  2. Compare the behavior to what the spec says it should do.
  3. Note any discrepancies — places where the code doesn't match the spec's intent.
针对每个相关文件：
  1. 读取代码并理解其功能。
  2. 将代码行为与spec描述的预期行为进行对比。
  3. 记录所有差异——即代码与spec意图不符的地方。

2c. Check conformance tests and unit tests (if relevant)

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

If the bug manifests as a test failure:
  1. Read the failing test in 
    conformance_tests/<module_name>/
    or 
    plain_modules/<module_name>/test/
    .
  2. Understand what the test expects vs. what the implementation does.
  3. Determine whether the test expectation is correct (matches the spec) or incorrect (doesn't match the spec).
如果bug表现为测试失败：
  1. 读取
    conformance_tests/<module_name>/
    或
    plain_modules/<module_name>/test/
    中的失败测试用例。
  2. 理解测试的预期结果与实际实现的差异。
  3. 判断测试预期是否正确（与spec一致）或错误（与spec不符）。

Phase 3 — Diagnose the Root Cause

阶段3 — 诊断根本原因

Trace the issue from the generated code back to the specs. There are five possible root causes — determine which one applies before making changes:
Root CauseSymptomFix
Ambiguous specThe spec is correct in intent, but vague enough that the renderer interpreted it differently than intended.Add explicit detail to the spec to eliminate the ambiguity.
Missing specThe desired behavior is not covered by any spec. The renderer had no guidance and either did nothing or made an arbitrary choice.Add a new functional spec using the 
add-functional-spec
skill.
Conflicting specsTwo specs contradict each other, causing the renderer to produce inconsistent behavior.Use the 
resolve-spec-conflict
skill.
Incorrect specThe spec explicitly describes the wrong behavior. The renderer implemented it faithfully, but the spec itself is wrong.Rewrite the spec to describe the correct behavior.
Missing implementation reqThe spec is correct, but the implementation req doesn't provide enough guidance for the renderer to produce the right code (e.g., missing library, missing architectural constraint, missing platform detail).Add or update the implementation req using the 
add-implementation-requirement
skill.
从生成代码追溯问题到spec。存在五种可能的根本原因——在进行修改前需确定具体属于哪一种：
根本原因症状修复方案
模糊specspec意图正确，但表述过于模糊，导致渲染器的解释与预期不符。为spec添加明确细节，消除歧义。
缺失spec所需行为未被任何spec覆盖。渲染器无指导依据，要么未实现该功能，要么做出了任意选择。使用
add-functional-spec
技能添加新的功能spec。
冲突spec两个spec相互矛盾，导致渲染器生成不一致的行为。使用
resolve-spec-conflict
技能解决冲突。
错误specspec明确描述了错误行为。渲染器忠实地实现了该spec，但spec本身存在错误。重写spec以描述正确行为。
缺失实现要求spec正确，但实现要求未为渲染器提供足够指导以生成正确代码（例如缺少库、架构约束或平台细节）。使用
add-implementation-requirement
技能添加或更新实现要求。

How to diagnose

诊断方法

  1. Read the spec that governs the buggy behavior. Does it clearly and unambiguously describe the correct behavior?
    • If the spec is clear and correct but the code is wrong → ambiguous spec (the renderer misinterpreted it) or missing implementation req.
    • If the spec doesn't mention the behavior at all → missing spec.
    • If the spec explicitly describes the wrong behavior → incorrect spec.
  2. Check for conflicts. Could another spec be overriding or contradicting this behavior?
    • Read all functional specs that touch the same concepts.
    • If two specs are in tension → conflicting specs.
  3. Check implementation reqs. Is the renderer missing guidance on how to implement correctly?
    • Does the implementation req specify the right library, pattern, or constraint?
    • If a platform-specific or framework-specific detail is missing → missing implementation req.
  1. 读取控制bug行为的spec。它是否清晰、无歧义地描述了正确行为？
    • 如果spec清晰正确但代码存在错误→模糊spec（渲染器误解了spec）或缺失实现要求。
    • 如果spec完全未提及该行为→缺失spec。
    • 如果spec明确描述了错误行为→错误spec。
  2. 检查冲突情况。是否存在其他spec覆盖或矛盾该行为？
    • 读取所有涉及相同概念的功能spec。
    • 如果两个spec存在冲突→冲突spec。
  3. 检查实现要求。渲染器是否缺少正确实现的指导？
    • 实现要求是否指定了正确的库、模式或约束？
    • 如果缺少平台或框架特定细节→缺失实现要求。

Phase 4 — Fix the Specs

阶段4 — 修复spec

Apply the fix based on the diagnosed root cause. Use the appropriate skill:
Root CauseSkill to Use
Ambiguous specEdit the spec inline — add sub-bullets or reword for clarity
Missing spec
add-functional-spec
Conflicting specs
resolve-spec-conflict
Incorrect specEdit the spec inline — rewrite the incorrect part
Missing implementation req
add-implementation-requirement
根据诊断出的根本原因应用修复方案，使用相应技能：
根本原因使用技能
模糊spec内联编辑spec——添加子项目或重新表述以明确含义
缺失spec
add-functional-spec
冲突spec
resolve-spec-conflict
错误spec内联编辑spec——重写错误部分
缺失实现要求
add-implementation-requirement

Fix guidelines

修复准则

  • Minimal changes. Only modify what is necessary to fix the observed bug. Avoid rewriting unrelated specs.
  • Preserve chronological order. If adding a new spec, place it correctly relative to existing specs.
  • Stay language-agnostic. Functional specs describe behavior, not implementation. Platform-specific guidance belongs in implementation reqs.
  • Respect the 200 LOC limit. If a fix makes a spec too complex, use 
    break-down-func-spec
    to split it.
  • Check for new conflicts. After editing, verify the fix doesn't conflict with other specs by running 
    analyze-func-specs
    once with the edited spec(s) plus every existing spec that touches the same concepts. The batched analyzer reports all conflicting pairs in a single call; resolve each with 
    resolve-spec-conflict
    .
  • 最小化修改。仅修改修复观察到的bug所需的内容。避免重写无关spec。
  • 保留时间顺序。如果添加新spec，需将其放置在现有spec的正确位置。
  • 保持语言无关性。功能spec描述行为而非实现。平台特定指导应放在实现要求中。
  • 遵守200 LOC限制。如果修复导致spec过于复杂，使用
    break-down-func-spec
    拆分spec。
  • 检查新冲突。编辑完成后，需验证修复不会与其他spec冲突——将编辑后的spec与所有涉及相同概念的现有spec一起运行
    analyze-func-specs
    。批量分析器会一次性报告所有冲突对，使用
    resolve-spec-conflict
    解决每个冲突。

Phase 5 — Verify and Report

阶段5 — 验证与报告

  1. Re-read the modified 
    .plain
    file(s)     in full to confirm correctness.
  2. Summarize the findings for the user:
    • What was observed (the bug)
    • What the generated code was doing (the symptom in code)
    • Which spec(s) caused the issue (the root cause)
    • What was changed in the specs (the fix)
    • What to expect after re-rendering
  3. If uncertain, present the diagnosis and proposed fix to the user for confirmation before making changes. Some bugs have multiple possible causes — when in doubt, explain the options and let the user decide.
  1. 重新阅读修改后的.plain文件，确认修改正确。
  2. 向用户总结排查结果：
    • 观察到的问题（bug）
    • 生成代码的当前行为（代码层面的症状）
    • 导致问题的spec（根本原因）
    • spec中的修改内容（修复方案）
    • 重新渲染后的预期结果
  3. 如有不确定，在修改前向用户展示诊断结果和拟议修复方案以确认。部分bug可能存在多种原因——如有疑问，请解释可选方案并让用户决定。

Debugging Strategies

调试策略

Strategy 1: Observation-Driven (most common)

策略1：观察驱动（最常见）

Start from the user's observation and work backward through the code to the spec.
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
从用户的观察结果出发，反向追溯代码到spec。
用户发现bug → 读取生成代码 → 找到相关代码路径 →
确定控制该代码的spec → 诊断spec生成错误代码的原因 →
修复spec

Strategy 2: Spec-Focused

策略2：Spec聚焦

The user suspects a specific spec. Compare the spec directly against the generated code.
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
用户怀疑某个特定spec。直接对比spec与生成代码。
用户指向spec → 读取spec → 找到实现该spec的生成代码 →
对比spec意图与代码行为 → 诊断差异 → 修复spec

Strategy 3: Test-Failure-Driven

策略3：测试失败驱动

A test is failing. Use the test as the entry point.
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)
测试用例失败。以测试用例为入口点。
读取失败测试用例 → 理解测试预期 → 读取实现代码 →
判断测试或实现是否错误 → 追溯到spec →
修复spec（如果测试本身错误，则修复测试要求/验收测试）

Strategy 4: Differential

策略4：差异对比

The bug appeared after a new spec was added. Compare before and after.
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
添加新spec后出现bug。对比前后版本。
确定新增的spec → 读取可能与之冲突的spec →
检查新spec是否引入了bug → 使用resolve-spec-conflict或
修改新spec

Common Pitfalls

常见陷阱

Fixing the code instead of the spec

修改代码而非spec

Never modify files in 
plain_modules/
or 
conformance_tests/
. Even if the fix is obvious in the code, the change must be made in the 
.plain
file so it persists across re-renders.
切勿修改
plain_modules/
或
conformance_tests/
中的文件。即使代码中的修复方案很明显，也必须在.plain文件中进行修改，以确保修改在重新渲染后仍能保留。

Treating symptoms instead of root causes

只修复症状而非根本原因

If the user says "the button is in the wrong place," don't just add positioning detail. Investigate why the renderer placed it there — the root cause might be a missing layout spec, an ambiguous screen description, or a conflict with another spec.
如果用户反馈“按钮位置错误”，不要仅添加定位细节。需排查渲染器将按钮放在该位置的原因——根本原因可能是缺失布局spec、模糊的屏幕描述或与其他spec冲突。

Over-specifying the fix

过度指定修复方案

Adding too much implementation detail to a functional spec (e.g., specific pixel values, widget names, CSS properties) makes it brittle. Prefer behavior-level fixes. Use implementation reqs for platform-specific guidance.
在功能spec中添加过多实现细节（例如特定像素值、组件名称、CSS属性）会导致spec变得脆弱。优先选择行为层面的修复。平台特定指导应放在实现要求中。

Ignoring ripple effects

忽略连锁反应

A spec fix may affect other specs that reference the same concepts. Always check neighboring specs for conflicts after making a change.
spec修复可能会影响其他涉及相同概念的spec。修改后务必检查相邻spec是否存在冲突。

Validation Checklist

验证清单

  • User's observation is clearly understood (expected vs. actual behavior)
  • Generated code has been read to understand the current implementation
  • Root cause is diagnosed (ambiguous / missing / conflicting / incorrect / missing impl req)
  • Fix is applied in the 
    .plain
    file(s) only — no generated code modified
  • Fix is minimal and targeted to the observed bug
  • Fix does not introduce new conflicts with existing specs
  • Modified specs respect the 200 LOC limit
  • Modified specs remain language-agnostic
  • Chronological ordering is preserved
  • Summary of findings and fix presented to the user
  • 已明确理解用户的观察结果（预期行为vs实际行为）
  • 已读取生成代码以理解当前实现
  • 已诊断根本原因（模糊/缺失/冲突/错误/缺失实现要求）
  • 仅在.plain文件中应用了修复——未修改任何生成代码
  • 修复最小化且针对观察到的bug
  • 修复未与现有spec产生新冲突
  • 修改后的spec遵守200 LOC限制
  • 修改后的spec保持语言无关性
  • 保留了时间顺序
  • 已向用户展示排查结果和修复方案的总结