resolve-spec-conflict

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Resolve Spec Conflict

解决规范冲突

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 This Applies

适用场景

A conflict exists (or is suspected) when:

Conformance tests for a previously passing functional spec begin to fail after a new spec is rendered.
A new spec being added (via the
```
add-functional-spec
```
or
```
add-functional-specs
```
skill) appears to contradict an existing spec.
Two specs make incompatible assertions about the same behavior, data, or state.

当出现以下情况时，说明存在（或疑似存在）冲突：

某一此前已通过的功能规范的一致性测试在新规范渲染后开始失败。
通过
```
add-functional-spec
```
或
```
add-functional-specs
```
技能添加的新规范似乎与现有规范存在矛盾。
两个规范对同一行为、数据或状态做出了互斥的断言。

Workflow

工作流程

Step 1: Identify the Conflicting Pair

步骤1：识别冲突对

Read the

.plain

file and pinpoint the two specs in tension. If the conflict was detected via a conformance test failure, also read the failing test and the generated implementation in

plain_modules/

to understand what behavior changed.

阅读

.plain

文件，找出存在冲突的两个规范。如果冲突是通过一致性测试失败检测到的，还需阅读失败的测试用例以及

plain_modules/

中的生成实现，以了解行为发生了哪些变化。

Step 2: Diagnose the Root Cause

步骤2：诊断根本原因

There are three possible outcomes — determine which one applies before making changes:

Outcome	Symptom	Fix
Implementation is incorrect	Generated code doesn't match the spec's intent. The specs themselves are fine.	Clarify the ambiguous spec so the renderer interprets it correctly. Re-render.
Conformance tests are incorrect	The tests don't accurately verify the spec. The implementation is actually correct.	Adjust `*test reqs` or `acceptance tests*` to guide better test generation. Re-render.
Requirements truly conflict	The two specs are inherently contradictory — no implementation can satisfy both.	One or both specs must be revised. See Step 3.

How to diagnose:

Read both functional specs carefully. Can a single implementation satisfy both simultaneously?
If yes → the specs are compatible; the issue is ambiguity (outcome 1) or bad tests (outcome 2).
If no → the requirements truly conflict (outcome 3).

存在三种可能的结果——在进行更改前，请确定适用哪一种：

结果	症状	修复方案
实现不正确	生成的代码不符合规范的意图，规范本身没有问题。	明确模糊的规范，使渲染器能够正确解读。重新渲染。
一致性测试不正确	测试未能准确验证规范，实际实现是正确的。	调整 `*test reqs` 或 `acceptance tests*` 以引导生成更合适的测试用例。重新渲染。
需求确实冲突	两个规范存在本质矛盾——没有任何实现能同时满足两者。	必须修订其中一个或两个规范。请查看步骤3。

诊断方法：

仔细阅读两个功能规范。是否存在单一实现能同时满足两者？
如果是→规范兼容，问题出在模糊性（结果1）或测试质量不佳（结果2）。
如果否→需求确实存在冲突（结果3）。

Step 3: Resolve the Conflict

步骤3：解决冲突

When the requirements truly conflict, choose a resolution strategy:

Strategy A: Add detail to disambiguate. Often the specs aren't contradictory — they're just ambiguous enough that the renderer picks a conflicting interpretation. Adding explicit context to one or both specs eliminates the ambiguity.

Before (ambiguous):
- The system should return all :Resource: items.
- The system should return only active :Resource: items.

After (disambiguated):
- The system should return all :Resource: items when no filter is specified.
- When the "active" filter is specified, the system should return only active :Resource: items.

Strategy B: Revise the newer spec. If the new spec introduced the conflict, rewrite it to be compatible with the established behavior from earlier specs.

Strategy C: Revise the older spec. If the older spec was under-specified and the new requirement reveals a better design, update the older spec. This is more disruptive — all conformance tests for that spec and everything after it may need re-rendering.

Strategy D: Merge into one spec. If the two specs describe overlapping behavior, combine them into a single, clear spec. Remove the redundant one. Be mindful of the 200 LOC limit.

当需求确实冲突时，选择以下解决策略：

策略A：添加细节以消除模糊性。通常规范并非真的矛盾——只是模糊到让渲染器做出了冲突的解读。为一个或两个规范添加明确的上下文即可消除模糊性。

修改前（模糊）：
- 系统应返回所有:Resource:项。
- 系统应仅返回活跃的:Resource:项。

修改后（明确）：
- 未指定过滤器时，系统应返回所有:Resource:项。
- 当指定“活跃”过滤器时，系统应仅返回活跃的:Resource:项。

策略B：修订较新的规范。如果是新规范引入了冲突，重写使其与早期规范确立的行为兼容。

策略C：修订较旧的规范。如果旧规范描述不够明确，而新需求揭示了更优设计，则更新旧规范。此方式破坏性更强——该规范及后续所有相关的一致性测试可能都需要重新渲染。

策略D：合并为单个规范。如果两个规范描述的行为存在重叠，将它们合并为一个清晰的规范，移除冗余的那个。注意200 LOC限制。

Step 4: Validate the Resolution

步骤4：验证解决方案

After editing:

Re-read the full
```
***functional specs***
```
section to confirm no new conflicts were introduced.
Check that any revised spec still respects the 200 LOC limit.
Check that chronological ordering still makes sense (earlier specs should not depend on later ones).
If resolving via test adjustments, verify the
```
***test reqs***
```
or
```
***acceptance tests***
```
changes are appropriate.

编辑完成后：

重新阅读完整的
```
***functional specs***
```
部分，确认未引入新的冲突。
检查修订后的规范是否仍遵守200 LOC限制。
检查时间顺序是否依然合理（早期规范不应依赖后期规范）。
如果通过调整测试解决冲突，验证
```
***test reqs***
```
或
```
***acceptance tests***
```
的修改是否恰当。

Prevention (for use during add-functional-spec / add-functional-specs)

预防措施（在添加功能规范时使用）

Before adding a new spec, run through this quick conflict check:

List every existing functional spec that touches the same
```
:Concepts:
```
as the new spec.
For each, ask: "Can a single implementation satisfy both this existing spec and the new one?"
If any answer is "not obviously yes" — add explicit detail to the new spec to eliminate the ambiguity before inserting it.

添加新规范前，执行以下快速冲突检查：

列出所有与新规范涉及相同
```
:Concepts:
```
的现有功能规范。
针对每个现有规范，询问：“是否存在单一实现能同时满足该现有规范和新规范？”
如果任何答案为“并非显然是”——在插入新规范前，添加明确细节以消除模糊性。

Validation Checklist

验证清单

Root cause diagnosed (implementation / tests / true conflict)
Resolution strategy chosen and applied
Revised specs are language-agnostic
Revised specs each imply ≤ 200 LOC
No new conflicts introduced by the fix
Chronological ordering preserved
All referenced
```
:Concepts:
```
are still defined

已诊断根本原因（实现/测试/真实冲突）
已选择并应用解决策略
修订后的规范与语言无关
每个修订后的规范对应的代码量≤200 LOC
修复未引入新冲突
时间顺序得以保留
所有引用的
```
:Concepts:
```
仍有定义