consolidate-concepts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Consolidate Concepts

概念整合

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

使用场景

Multiple modules define the same or closely related concepts independently.
A
```
requires
```
chain uses long
```
exported_concepts
```
lists to share definitions that would be simpler as an import.
After a
```
refactor-module
```
split, shared concepts ended up duplicated or awkwardly exported.
The user wants a single source of truth for domain concepts used across modules.

多个模块独立定义了相同或密切相关的概念。
```
requires
```
依赖链使用冗长的
```
exported_concepts
```
列表来共享定义，而通过导入方式实现会更简洁。
在
```
refactor-module
```
拆分操作后，共享概念出现重复或导出方式不合理的情况。
用户希望将跨模块使用的领域概念统一到单一可信源中。

Guiding Principle

指导原则

This is a structural refactoring. The behavior of every affected module must remain identical. No functional spec, implementation req, or test req is changed. Only concept definitions move — from scattered locations into one shared import module — and the modules'

import

lists are updated to reference it.

这是一种结构性重构。所有受影响模块的行为必须保持完全一致。不得修改任何功能规范（functional spec）、实现要求（implementation req）或测试要求（test req）。仅迁移概念定义——从分散的位置移至单个共享导入模块——并更新模块的

import

列表以引用该模块。

Input

输入

The set of modules to consolidate from, plus optionally the name for the new (or existing) import module. If not specified, ask the user.

需要整合的模块集合，以及可选的新（或现有）导入模块名称。如果未指定名称，请询问用户。

Phase 1 — Analyze Concepts Across Modules

阶段1：跨模块分析概念

Read all source modules. For each
```
.plain
```
file involved, read the full file including frontmatter, definitions, implementation reqs, test reqs, and functional specs. Also read their
```
import
```
and
```
requires
```
chains.
Build a concept inventory. For each concept defined across all source modules, record:
- Where it is defined (which file, which line)
- Which modules reference it (in definitions, functional specs, implementation reqs, or test reqs)
- Whether it is currently in an
```
exported_concepts
```
  list
- Which other concepts it references in its definition (dependency graph)
Identify consolidation candidates. A concept should be consolidated if:
- It is defined in one module but referenced by specs in another module (currently shared via
```
exported_concepts
```
  )
- It is duplicated across multiple modules
- It is a foundational domain concept that logically belongs in a shared vocabulary
Identify concepts that should stay local. A concept should remain in its module if:
- It is only used within that single module's specs and definitions
- It is an internal implementation detail not meaningful outside that module

读取所有源模块：对于所有涉及的
```
.plain
```
文件，读取完整文件内容，包括前置元数据、定义、实现要求、测试要求和功能规范。同时读取它们的
```
import
```
和
```
requires
```
依赖链。
构建概念清单：针对所有源模块中定义的每个概念，记录：
- 定义位置（哪个文件、哪一行）
- 哪些模块引用了该概念（在定义、功能规范、实现要求或测试要求中）
- 该概念当前是否在
```
exported_concepts
```
  列表中
- 其定义中引用了哪些其他概念（依赖关系图）
确定整合候选概念：满足以下条件的概念应被整合：
- 在一个模块中定义，但被另一个模块的规范引用（当前通过
```
exported_concepts
```
  共享）
- 在多个模块中重复定义
- 是基础领域概念，逻辑上属于共享词汇表的一部分
确定应保留在本地的概念：满足以下条件的概念应保留在原模块中：
- 仅在该模块的规范和定义中使用
- 是内部实现细节，对其他模块无意义

Phase 2 — Plan the Consolidation

阶段2：规划整合方案

Present the plan to the user and get explicit confirmation before making changes.

在进行修改前，向用户展示规划方案并获得明确确认。

2a. Choose the target import module

2a. 选择目标导入模块

New import module — create a new
```
.plain
```
file in
```
template/
```
. Choose a name that reflects the shared domain (e.g.,
```
template/myapp-concepts.plain
```
).
Existing import module — add the concepts to an import module that is already used by the affected modules. This avoids adding another import reference.

If the target is an existing import module, read it fully to understand what it already contains.

新建导入模块：在
```
template/
```
目录下创建一个新的
```
.plain
```
文件。选择一个能体现共享领域的名称（例如：
```
template/myapp-concepts.plain
```
）。
现有导入模块：将概念添加到已被受影响模块使用的导入模块中。这样可以避免添加额外的导入引用。

如果目标是现有导入模块，请完整读取该文件以了解其现有内容。

2b. Determine which concepts move

2b. 确定需要迁移的概念

For each consolidation candidate, confirm:

The concept will be removed from its current module's
```
***definitions***
```
section.
The concept will be added to the target import module's
```
***definitions***
```
section.
The concept's full definition text (including all sub-bullets for attributes and constraints) is moved verbatim.

针对每个整合候选概念，确认：

该概念将从当前模块的
```
***definitions***
```
部分移除。
该概念将被添加到目标导入模块的
```
***definitions***
```
部分。
概念的完整定义文本（包括属性和约束的所有子项目符号）将原封不动地迁移。

2c. Determine concept ordering in the target

2c. 确定目标模块中的概念顺序

Concepts in the import module must be ordered so that every concept is defined after any concepts it references. Use the dependency graph from Phase 1 to establish a valid topological order.

导入模块中的概念必须按以下顺序排列：每个概念必须在其引用的所有概念之后定义。使用阶段1构建的依赖关系图来建立有效的拓扑顺序。

2d. Determine import and export changes

2d. 确定导入和导出的变更

For each affected module, determine the frontmatter changes:

Change	When
Add the new import to `import` list	Module does not already import the target
Remove concepts from `exported_concepts`	Concepts that were exported only to share definitions — now handled by the import
Keep concepts in `exported_concepts`	Concepts that downstream `requires` modules still need via export (because those downstream modules do not import the new template)

Important:

import

provides definitions to the importing module.

exported_concepts

on a

requires

module provides concepts to downstream modules in the build chain. If a downstream module will now

import

the shared template directly, the concept can be removed from

exported_concepts

. If a downstream module does not import the template, the concept must remain exported.

针对每个受影响的模块，确定前置元数据的变更：

变更内容	适用场景
将新导入添加到 `import` 列表	模块尚未导入目标模块
从 `exported_concepts` 中移除概念	仅为共享定义而导出的概念——现在通过导入方式处理
保留 `exported_concepts` 中的概念	下游 `requires` 模块仍需通过导出获取这些概念（因为这些下游模块未导入新的模板）

重要提示：

import

为导入模块提供定义。

requires

模块上的

exported_concepts

为构建链中的下游模块提供概念。如果下游模块现在将直接

import

共享模板，则可以从

exported_concepts

中移除该概念。如果下游模块未导入该模板，则必须保留该概念的导出。

2e. Present the plan

2e. 展示规划方案

Summarize for the user:

Target import module (new or existing) and its path
List of concepts being moved, with source module for each
List of concepts staying local (and why)
Frontmatter changes per module (
```
import
```
additions,
```
exported_concepts
```
removals)
Confirmation that no functional specs, implementation reqs, or test reqs are changing

Get explicit user confirmation before proceeding.

向用户总结以下内容：

目标导入模块（新建或现有）及其路径
待迁移概念列表，以及每个概念的源模块
保留在本地的概念列表（及原因）
每个模块的前置元数据变更（添加
```
import
```
、移除
```
exported_concepts
```
中的概念）
确认未修改任何功能规范、实现要求或测试要求

在继续执行前获得用户的明确确认。

Phase 3 — Execute

阶段3：执行整合

3a. Create or update the import module

3a. 创建或更新导入模块

If creating a new import module:

Create
```
template/<name>.plain
```
with YAML frontmatter. If it needs concepts from another import, add that to its own
```
import
```
list.
Add a
```
***definitions***
```
section with all consolidated concepts in dependency order.
Do not add
```
***functional specs***
```
— import modules must not contain them.

If updating an existing import module:

Read the current file.
Insert the new concepts into the
```
***definitions***
```
section, respecting dependency order relative to existing concepts.
Verify no concept name collisions with concepts already in the file or its own imports.

如果创建新导入模块：

创建
```
template/<name>.plain
```
文件并添加YAML前置元数据。如果它需要从其他导入模块获取概念，请将该模块添加到其自身的
```
import
```
列表中。
添加
```
***definitions***
```
部分，按依赖顺序添加所有整合后的概念。
请勿添加
```
***functional specs***
```
——导入模块不得包含功能规范。

如果更新现有导入模块：

读取当前文件内容。
将新概念插入到
```
***definitions***
```
部分，确保相对于现有概念的依赖顺序正确。
验证与文件中已有的概念或其自身导入的概念不存在名称冲突。

3b. Update each source module

3b. 更新每个源模块

For each module that had concepts moved out:

Remove the concept definitions from the module's
```
***definitions***
```
section. Remove the full definition including all sub-bullets.
Add the import to the module's YAML frontmatter
```
import
```
list (if not already present).
Update
exported_concepts
— remove concepts that no longer need to be exported (see 2d).
Do not touch
```
***functional specs***
```
,
```
***implementation reqs***
```
, or
```
***test reqs***
```
— concept references (
```
:ConceptName:
```
) in these sections remain unchanged since the concept is now provided by the import.

针对每个有概念移出的模块：

移除概念定义：从模块的
```
***definitions***
```
部分移除概念定义。移除完整的定义内容，包括所有子项目符号。
添加导入：在模块的YAML前置元数据
```
import
```
列表中添加导入（如果尚未存在）。
更新
exported_concepts
——移除不再需要导出的概念（参见2d部分）。
请勿修改
```
***functional specs***
```
、
```
***implementation reqs***
```
或
```
***test reqs***
```
——这些部分中的概念引用（
```
:ConceptName:
```
）保持不变，因为概念现在由导入模块提供。

3c. Update downstream modules (if applicable)

3c. 更新下游模块（如适用）

If concepts were removed from a module's

exported_concepts

and downstream

requires

modules relied on them:

Add the new import to the downstream module's
```
import
```
list so it gets the concepts directly.
Verify the downstream module's specs can still resolve all concept references.

如果从模块的

exported_concepts

中移除了概念，且下游

requires

模块依赖这些概念：

将新导入添加到下游模块的
```
import
```
列表中，使其直接获取概念。
验证下游模块的规范仍能解析所有概念引用。

Phase 4 — Verify

阶段4：验证

4a. Concept availability check

4a. 概念可用性检查

For every affected module (source modules, downstream modules, and the import module itself):

Every
```
:Concept:
```
referenced in functional specs is resolvable (defined locally, via import, or via exported concepts from requires)
Every
```
:Concept:
```
referenced in definitions is defined before the concept that references it
Every
```
:Concept:
```
referenced in implementation reqs and test reqs is resolvable

针对所有受影响的模块（源模块、下游模块和导入模块本身）：

功能规范中引用的每个
```
:Concept:
```
都可解析（本地定义、通过导入或通过requires模块的导出概念）
定义中引用的每个
```
:Concept:
```
都在引用它的概念之前定义
实现要求和测试要求中引用的每个
```
:Concept:
```
都可解析

4b. No duplicates check

4b. 无重复检查

No concept is defined in both the import module and a source module
No concept is defined in both the import module and another import that a source module uses
Concept names are globally unique across each module's full resolution scope (local + imports + requires exports)

没有概念同时在导入模块和源模块中定义
没有概念同时在导入模块和源模块使用的其他导入模块中定义
概念名称在每个模块的完整解析范围（本地+导入+requires导出）内全局唯一

4c. Definition integrity check

4c. 定义完整性检查

Each moved concept's definition text is identical to the original — no rewording, no lost sub-bullets
Concept ordering in the import module respects the dependency graph (no forward references)

每个迁移概念的定义文本与原始文本完全一致——未重写、未丢失子项目符号
导入模块中的概念顺序符合依赖关系图（无前置引用）

4d. No behavioral change check

4d. 无行为变更检查

No
```
***functional specs***
```
were modified in any module
No
```
***implementation reqs***
```
were modified in any module
No
```
***test reqs***
```
were modified in any module
No
```
***acceptance tests***
```
were modified in any module

未修改任何模块的
```
***functional specs***
```
未修改任何模块的
```
***implementation reqs***
```
未修改任何模块的
```
***test reqs***
```
未修改任何模块的
```
***acceptance tests***
```

4e. Structural validation

4e. 结构验证

For the import module:

File is in the
```
template/
```
directory
Does not contain
```
***functional specs***
```
Does not use
```
requires
```
YAML frontmatter is correctly formatted

For each source module:

YAML frontmatter
```
import
```
list includes the target import module
```
exported_concepts
```
is correct (no over-export, no missing exports)
Module still has at least one functional spec and one implementation req

针对导入模块：

文件位于
```
template/
```
目录下
不包含
```
***functional specs***
```
未使用
```
requires
```
YAML前置元数据格式正确

针对每个源模块：

YAML前置元数据
```
import
```
列表包含目标导入模块
```
exported_concepts
```
内容正确（无过度导出、无缺失导出）
模块仍至少包含一个功能规范和一个实现要求

4f. Read all modified files

4f. 读取所有修改后的文件

Read each modified

.plain

file in full and present the changes to the user for approval. If the user requests changes, apply them and re-verify.

完整读取每个修改后的

.plain

文件，并向用户展示变更内容以获得批准。如果用户要求变更，应用变更后重新验证。

Common Pitfalls

常见陷阱

Moving a concept that is only used locally

迁移仅在本地使用的概念

If a concept is only referenced within a single module, consolidating it into a shared import adds unnecessary coupling. Keep it local.

如果一个概念仅在单个模块内被引用，将其整合到共享导入模块会增加不必要的耦合。应保留在本地。

Forgetting to update downstream requires modules

忘记更新下游requires模块

When a concept is removed from

exported_concepts

, any module that

requires

the source module and references that concept will break — unless it now imports the shared template. Always trace the full dependency chain.

当从

exported_concepts

中移除概念时，任何

requires

该源模块并引用该概念的模块都会失效——除非它现在导入了共享模板。务必追踪完整的依赖链。

Breaking concept ordering

破坏概念顺序

Concepts in the import module must be topologically ordered. If

:Meal:

references

:MealType:

in its definition, then

:MealType:

must appear first. The source modules may have had them in the right order locally, but merging concepts from different modules requires re-establishing a valid order.

导入模块中的概念必须按拓扑顺序排列。如果

:Meal:

在其定义中引用了

:MealType:

，则

:MealType:

必须排在前面。源模块中可能已在本地保持正确顺序，但合并来自不同模块的概念需要重新建立有效顺序。

Creating circular imports

创建循环导入

An import module cannot

import

a module that directly or indirectly imports it back. If the shared concepts reference concepts from an existing template, the new import module should itself import that template — not the other way around.

导入模块不能

import

直接或间接导入它的模块。如果共享概念引用了现有模板中的概念，新导入模块应

import

该现有模板——而不是反过来。

Removing concepts from exported_concepts prematurely

过早从exported_concepts中移除概念

Only remove a concept from

exported_concepts

if every downstream

requires

module that needs it will now get it via

import

. If even one downstream module does not import the shared template, the export must stay.

仅当所有需要该概念的下游

requires

模块现在都通过

import

获取它时，才能从

exported_concepts

中移除该概念。如果有任何一个下游模块未导入共享模板，则必须保留该导出。

Validation Checklist

验证清单

User confirmed the consolidation plan before execution
All moved concepts are defined in the import module with identical text
Concepts are in valid dependency order in the import module
No concept is defined in both the import module and a source module
Every affected module's
```
import
```
list includes the target import module
```
exported_concepts
```
updated correctly — no missing exports, no unnecessary exports
All concept references in all affected modules resolve correctly
No functional specs, implementation reqs, test reqs, or acceptance tests were modified
Import module is in
```
template/
```
and has no functional specs or requires
No circular imports introduced
Downstream requires modules updated if needed
User approved the final result

执行前用户已确认整合方案
所有迁移的概念在导入模块中的定义文本与原始完全一致
导入模块中的概念顺序符合依赖关系
没有概念同时在导入模块和源模块中定义
所有受影响模块的
```
import
```
列表包含目标导入模块
```
exported_concepts
```
已正确更新——无缺失导出、无不必要导出
所有受影响模块中的概念引用均可正确解析
未修改任何功能规范、实现要求、测试要求或验收测试
导入模块位于
```
template/
```
目录下，且无功能规范或requires
未引入循环导入
已按需更新下游requires模块
用户已批准最终结果