Back to Details

break-down-func-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Break Down Functional Spec

拆分功能规格

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

使用场景

  • analyze-if-func-spec-too-complex
    flagged a spec as TOO COMPLEX.
  • A spec is suspected of exceeding the 200 LOC limit and needs to be split preemptively.
  • A spec bundles multiple behaviors, constructs, or concerns that should be separated.
  • analyze-if-func-spec-too-complex
    标记某个规格为“过于复杂”。
  • 怀疑某个规格超出200 LOC限制，需要提前拆分。
  • 某个规格包含了多个应分离的行为、结构或关注点。

Input

输入

The functional spec to break down, plus the full 
.plain
file it belongs to.
需要拆分的功能规格，以及它所属的完整
.plain
文件。

Workflow

工作流程

  1. Read the full 
    .plain
    file     — definitions, implementation reqs, and all functional specs (including 
    requires
    modules) to understand context.
  2. Identify the spec to break down — the one flagged as too complex or pointed to by the user.
  3. Analyze why it is too complex — use the indicators from 
    analyze-if-func-spec-too-complex
    :
    • Multiple distinct behaviors bundled together?
    • Too many new constructs introduced at once?
    • Complex branching logic or conditional paths?
    • Cross-cutting concerns mixed with core functionality?
    • A full UI screen described in one spec?
    • Complex data transformations across multiple entities?
  4. Identify the split boundaries — find the natural seams where the spec can be divided. Each resulting spec must be:
    • Independently meaningful (makes sense on its own with previous specs as context)
    • Self-contained (does not require a later spec to be useful)
    • Within the 200 LOC limit
  5. Draft the replacement specs — write the smaller specs in chronological order. The first replacement spec typically sets up the foundation, and subsequent ones layer behavior on top.
  6. Verify functional completeness — this is critical. The replacement specs taken together must cover 100% of the functionality described in the original spec. Walk through every behavior, condition, and detail in the original and confirm it appears in exactly one of the replacement specs. Nothing may be lost, weakened, or left implicit. If any functionality from the original is missing, add it to the appropriate replacement spec or create an additional one.
  7. Verify each replacement spec — run 
    analyze-if-func-spec-too-complex
    on each to confirm it fits within the limit.
  8. Check for conflicts — run 
    analyze-func-specs
    once with the full set of replacement specs plus every existing spec in the file and its 
    requires
    chain. The batched analyzer reports every conflicting pair (replacement × existing and replacement × replacement) in one call — do not loop over pairs. Resolve each reported pair with 
    resolve-spec-conflict
    , then re-run 
    analyze-func-specs
    over the touched set until the verdict is 
    COMPATIBLE
    .
  9. Replace in the file — remove the original spec and insert the replacement specs in its position, preserving chronological order.
  10. Read the file again to confirm correct placement and syntax.
  1. 读取完整的
    .plain
    文件    ——包括定义、实现要求和所有功能规格（含
    requires
    模块），以了解上下文。
  2. 确定需要拆分的规格——即被标记为过于复杂或用户指定的那个规格。
  3. 分析复杂度原因——使用
    analyze-if-func-spec-too-complex
    提供的指标：
    • 是否包含多个独立的行为？
    • 是否一次性引入了过多新结构？
    • 是否存在复杂的分支逻辑或条件路径？
    • 是否将横切关注点与核心功能混合？
    • 是否在单个规格中描述了完整的UI界面？
    • 是否涉及跨多个实体的复杂数据转换？
  4. 确定拆分边界——找到规格可以自然划分的界限。拆分后的每个规格必须：
    • 具有独立意义（结合之前的规格上下文即可理解）
    • 自包含（无需依赖后续规格即可生效）
    • 代码量不超过200 LOC限制
  5. 草拟替代规格——按时间顺序编写较小的规格。第一个替代规格通常负责搭建基础，后续规格在此之上逐步添加行为。
  6. 验证功能完整性——这一点至关重要。所有替代规格合起来必须覆盖原始规格描述的100%功能。逐一检查原始规格中的每一项行为、条件和细节，确认它们恰好出现在某一个替代规格中。不得遗漏、弱化或隐含任何内容。如果原始规格中的某项功能缺失，需将其添加到相应的替代规格中，或创建新的替代规格。
  7. 验证每个替代规格——对每个替代规格运行
    analyze-if-func-spec-too-complex
    ，确认其符合限制要求。
  8. 检查冲突——对全套替代规格加上文件中所有现有规格及其
    requires
    链，一次性运行
    analyze-func-specs
    。批量分析器会一次性报告所有冲突对（替代规格与现有规格、替代规格之间）——请勿逐个检查冲突对。使用
    resolve-spec-conflict
    解决每个报告的冲突，然后重新运行
    analyze-func-specs
    检查受影响的规格集，直到结果为
    COMPATIBLE
    。
  9. 替换文件中的内容——删除原始规格，将替代规格插入到原位置，保持时间顺序不变。
  10. 再次读取文件，确认位置和语法正确。

Splitting Strategies

拆分策略

Strategy 1: Separate Distinct Behaviors

策略1：分离独立行为

If the spec bundles multiple independently testable actions, split each into its own spec.
Before:
plain
- :User: should be able to create, edit, and delete :Recipe: items, with
  validation on all fields.
After:
plain
- :User: should be able to create a :Recipe:. Only valid :Recipe: items can be created.
- :User: should be able to edit an existing :Recipe:. Validation rules apply to the edited fields.
- :User: should be able to delete a :Recipe:.
如果规格包含多个可独立测试的操作，将每个操作拆分为单独的规格。
拆分前：
plain
- :User: should be able to create, edit, and delete :Recipe: items, with
  validation on all fields.
拆分后：
plain
- :User: should be able to create a :Recipe:. Only valid :Recipe: items can be created.
- :User: should be able to edit an existing :Recipe:. Validation rules apply to the edited fields.
- :User: should be able to delete a :Recipe:.

Strategy 2: Separate Setup from Behavior

策略2：分离设置与行为

If the spec introduces a new construct and immediately defines complex behavior on it, split into setup + behavior.
Before:
plain
- The system should provide a :MealPlan: screen that displays a weekly grid of
  :Slot: items, allows drag-and-drop reordering, and shows nutritional totals
  per day.
After:
plain
- The system should provide a :MealPlan: screen that displays a weekly grid of :Slot: items.
- :User: should be able to reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
- The :MealPlan: screen should display nutritional totals for each day.
如果规格引入了新结构并立即定义了其上的复杂行为，拆分为设置+行为两个部分。
拆分前：
plain
- The system should provide a :MealPlan: screen that displays a weekly grid of
  :Slot: items, allows drag-and-drop reordering, and shows nutritional totals
  per day.
拆分后：
plain
- The system should provide a :MealPlan: screen that displays a weekly grid of :Slot: items.
- :User: should be able to reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
- The :MealPlan: screen should display nutritional totals for each day.

Strategy 3: Separate Core Logic from Cross-Cutting Concerns

策略3：分离核心逻辑与横切关注点

If the spec mixes primary functionality with error handling, retries, caching, pagination, or logging, pull cross-cutting concerns into their own specs.
Before:
plain
- The system should fetch :Ingredient: data from the external API with
  pagination, retry on transient errors, and cache results for 10 minutes.
After:
plain
- The system should fetch :Ingredient: data from the external API.
- The system should paginate when fetching :Ingredient: data from the external API.
- The system should retry fetching :Ingredient: data on transient errors.
如果规格将核心功能与错误处理、重试、缓存、分页或日志记录等横切关注点混合，将横切关注点拆分为单独的规格。
拆分前：
plain
- The system should fetch :Ingredient: data from the external API with
  pagination, retry on transient errors, and cache results for 10 minutes.
拆分后：
plain
- The system should fetch :Ingredient: data from the external API.
- The system should paginate when fetching :Ingredient: data from the external API.
- The system should retry fetching :Ingredient: data on transient errors.

Strategy 4: Separate Conditional Paths

策略4：分离条件路径

If the spec describes different modes or branches, give each its own spec.
Before:
plain
- The system should process :MealPlan: generation differently based on :DietType:.
  Standard plans use round-robin assignment. Restrictive plans filter out
  excluded ingredients first, then apply round-robin. Custom plans allow manual
  slot-by-slot selection.
After:
plain
- The system should generate a standard :MealPlan: using round-robin :Recipe: assignment.
- The system should generate a restrictive :MealPlan: by filtering out excluded
  :Ingredient: items before applying round-robin assignment.
- The system should allow :User: to manually assign :Recipe: items to individual
  :Slot: items for a custom :MealPlan:.
如果规格描述了不同的模式或分支，为每个分支创建单独的规格。
拆分前：
plain
- The system should process :MealPlan: generation differently based on :DietType:.
  Standard plans use round-robin assignment. Restrictive plans filter out
  excluded ingredients first, then apply round-robin. Custom plans allow manual
  slot-by-slot selection.
拆分后：
plain
- The system should generate a standard :MealPlan: using round-robin :Recipe: assignment.
- The system should generate a restrictive :MealPlan: by filtering out excluded
  :Ingredient: items before applying round-robin assignment.
- The system should allow :User: to manually assign :Recipe: items to individual
  :Slot: items for a custom :MealPlan:.

Strategy 5: Build UI Incrementally

策略5：逐步构建UI

If the spec describes a full screen, split into layout + individual interactive elements.
Before:
plain
- Display the :Dashboard: screen showing a summary card with stats, a scrollable
  list of recent :MealPlan: items, a floating action button to create a new plan,
  and a bottom navigation bar.
After:
plain
- Display the :Dashboard: screen with a summary card showing :MealFrameStats:.
- The :Dashboard: screen should show a scrollable list of recent :MealPlan: items.
- The :Dashboard: screen should include a button to create a new :MealPlan:.
如果规格描述了完整的界面，拆分为布局+单个交互元素。
拆分前：
plain
- Display the :Dashboard: screen showing a summary card with stats, a scrollable
  list of recent :MealPlan: items, a floating action button to create a new plan,
  and a bottom navigation bar.
拆分后：
plain
- Display the :Dashboard: screen with a summary card showing :MealFrameStats:.
- The :Dashboard: screen should show a scrollable list of recent :MealPlan: items.
- The :Dashboard: screen should include a button to create a new :MealPlan:.

Preserving Chronological Order

保持时间顺序

The replacement specs take the position of the original spec. Earlier specs remain unchanged. The first replacement spec should make sense given only the specs above it. Each subsequent replacement spec can reference behavior from the ones before it.
If the original spec had acceptance tests, redistribute them to the most appropriate replacement spec — or drop tests that no longer apply to a single smaller spec and rewrite them.
替代规格将取代原始规格的位置。之前的规格保持不变。第一个替代规格应仅基于其上方的规格即可理解。每个后续替代规格可以引用之前替代规格中的行为。
如果原始规格包含验收测试，将其重新分配到最合适的替代规格中——或者删除不再适用于单个较小规格的测试并重新编写。

Validation Checklist

验证 Checklist

  • Original spec has been removed from the file
  • Replacement specs together cover 100% of the original spec's functionality — nothing lost
  • Each replacement spec implies ≤ 200 LOC (verified via 
    analyze-if-func-spec-too-complex
    )
  • No conflicts between replacement specs and existing specs (verified via one batched 
    analyze-func-specs
    call)
  • No conflicts between the replacement specs themselves (covered by the same batched call)
  • Replacement specs are in correct chronological order
  • Each replacement spec is independently meaningful
  • All 
    :Concepts:
    referenced in replacement specs are defined
  • Replacement specs are language-agnostic
  • All external interfaces remain explicit
  • Acceptance tests (if any) have been redistributed or rewritten
  • 原始规格已从文件中移除
  • 所有替代规格合起来覆盖了原始规格的100%功能——无遗漏
  • 每个替代规格对应的代码量≤200 LOC（已通过
    analyze-if-func-spec-too-complex
    验证）
  • 替代规格与现有规格之间无冲突（已通过一次批量
    analyze-func-specs
    调用验证）
  • 替代规格之间无冲突（已通过同一次批量调用覆盖）
  • 替代规格顺序正确
  • 每个替代规格具有独立意义
  • 替代规格中引用的所有
    :Concepts:
    均已定义
  • 替代规格与语言无关
  • 所有外部接口保持明确
  • 验收测试（如有）已重新分配或重写