Back to Details

analyze-if-func-spec-too-complex

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Analyze If Functional Spec Is Too Complex

分析功能规格是否过于复杂

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

Why This Matters

为什么这很重要

The renderer enforces a hard complexity limit: each functional spec must imply a maximum of 200 changed lines of code. If a spec exceeds this, the renderer rejects it with "Functional spec too complex!" and the spec must be broken down. Catching this before insertion saves a failed render cycle.
渲染器有严格的复杂度限制：每个功能规格对应的代码变更行数最多为200行。如果规格超出此限制，渲染器会返回“Functional spec too complex!”并拒绝该规格，此时必须将规格拆分。在插入前提前发现问题可以避免渲染失败的流程。

Input

输入

A drafted functional spec (not yet inserted into the file), plus the full context of the 
.plain
file it will be added to — definitions, implementation reqs, and existing functional specs.
一份已起草但尚未插入文件的功能规格，加上它将被添加到的
.plain
文件的完整上下文——包括定义、实现要求和现有功能规格。

Workflow

工作流程

  1. Read the full 
    .plain
    file     (and any 
    requires
    /
    import
    modules) to understand the current codebase context — what already exists and what the new spec builds on.
  2. Read the drafted functional spec carefully.
  3. Run the complexity analysis using the checklist below.
  4. Output the verdict and nothing else — either 
    ACCEPTABLE
    or 
    TOO COMPLEX
    . No reasoning, no LOC estimate, no breakdown.
  1. 读取完整的
    .plain
    文件    （以及任何
    requires
    /
    import
    模块），了解当前代码库的上下文——已有的内容以及新规格将基于哪些内容构建。
  2. 仔细阅读已起草的功能规格。
  3. 使用下方的检查清单进行复杂度分析。
  4. 仅输出判定结果——只能是
    ACCEPTABLE
    或
    TOO COMPLEX
    。无需解释、无需代码行数估算、无需拆分说明。

Complexity Analysis Checklist

复杂度分析检查清单

Work through each indicator. A single "yes" does not automatically mean the spec is too complex, but multiple "yes" answers are a strong signal.
逐一检查每个指标。单个“是”并不自动意味着规格过于复杂，但多个“是”则是强烈的信号。

1. Number of Distinct Behaviors

1. 独立行为数量

Does the spec describe more than one independently testable behavior?
Too complex:
- :User: should be able to create, edit, delete, and archive :Task: items,
  with validation on all fields and confirmation dialogs for destructive actions.

Acceptable (one behavior each):
- :User: should be able to create :Task:. Only valid :Task: items can be added.
- :User: should be able to edit :Task:.
- :User: should be able to delete :Task:.
- :User: should be able to archive :Task:.
该规格是否描述了多个可独立测试的行为？
过于复杂：
- :User: 应能够创建、编辑、删除和归档:Task:项，
  所有字段均需验证，且执行破坏性操作时需弹出确认对话框。

可接受（每个对应一个行为）：
- :User: 应能够创建:Task:。仅允许添加有效的:Task:项。
- :User: 应能够编辑:Task:。
- :User: 应能够删除:Task:。
- :User: 应能够归档:Task:。

2. Number of Concepts Introduced or Modified

2. 引入或修改的概念数量

Does the spec require introducing new data structures, UI components, API endpoints, or other constructs that don't already exist? Count them.
  • 0–1 new constructs → likely fine
  • 2–3 new constructs → borderline, examine closely
  • 4+ new constructs → almost certainly too complex
该规格是否需要引入不存在的新数据结构、UI组件、API端点或其他结构？统计这些结构的数量。
  • 0–1个新结构 → 通常没问题
  • 2–3个新结构 → 临界情况，需仔细检查
  • 4个及以上新结构 → 几乎肯定过于复杂

3. Branching Logic and Conditions

3. 分支逻辑和条件

Does the spec describe multiple conditional paths, modes, or special cases?
Too complex:
- The system should process :Order: differently based on :OrderType:.
  Standard orders are validated and stored. Express orders skip validation
  and are queued for immediate dispatch. Bulk orders are split into
  sub-orders of 100 items each, validated individually, and processed
  in parallel with progress tracking.

Acceptable (separate the modes):
- The system should process standard :Order: by validating and storing it.
- The system should process express :Order: by queuing it for immediate dispatch
  without validation.
- The system should process bulk :Order: by splitting it into sub-orders of 100
  items each and processing them individually.
该规格是否描述了多个条件路径、模式或特殊情况？
过于复杂：
- 系统应根据:OrderType:以不同方式处理:Order:。
  标准订单需验证并存储。加急订单跳过验证，
  直接进入立即调度队列。批量订单拆分为
  每份100个项的子订单，分别验证并
  并行处理，同时跟踪进度。

可接受（拆分模式）：
- 系统应通过验证并存储来处理标准:Order:。
- 系统应将加急:Order:加入立即调度队列，
  无需验证。
- 系统应将批量:Order:拆分为每份100个项的子订单，
  并分别处理。

4. Cross-Cutting Concerns

4. 横切关注点

Does the spec bundle core functionality with cross-cutting concerns like error handling, logging, retry logic, pagination, or caching?
Too complex:
- The system should fetch :Resource: items from the external API with
  pagination support, retry on transient errors with exponential backoff,
  cache results for 5 minutes, and log all API calls.

Acceptable (separate concerns):
- The system should fetch :Resource: items from the external API.
- The system should paginate when fetching :Resource: items from the external API.
- The system should retry fetching :Resource: on transient errors using
  exponential backoff.
该规格是否将核心功能与错误处理、日志记录、重试逻辑、分页或缓存等横切关注点捆绑在一起？
过于复杂：
- 系统应从外部API获取:Resource:项，
  支持分页，对瞬时错误使用指数退避重试，
  缓存结果5分钟，并记录所有API调用。

可接受（拆分关注点）：
- 系统应从外部API获取:Resource:项。
- 系统在从外部API获取:Resource:项时应支持分页。
- 系统应使用指数退避重试获取:Resource:的瞬时错误。

5. UI Complexity

5. UI复杂度

Does the spec describe a complete screen or page with multiple interactive elements, layouts, and state transitions?
Too complex:
- Display a dashboard showing :User: profile, recent :Task: items in a
  sortable table, a notification bell with unread count, and a sidebar
  with navigation links that highlights the active page.

Acceptable (build incrementally):
- Display a dashboard page for :User:.
- Show recent :Task: items in a sortable table on the dashboard.
- Show a notification indicator with the unread count on the dashboard.
该规格是否描述了包含多个交互元素、布局和状态转换的完整屏幕或页面？
过于复杂：
- 显示一个仪表板，包含:User:资料、可排序表格中的最近:Task:项、
  带有未读计数的通知铃铛，以及突出显示当前页面的导航链接侧边栏。

可接受（逐步构建）：
- 显示:User:的仪表板页面。
- 在仪表板上以可排序表格显示最近的:Task:项。
- 在仪表板上显示带有未读计数的通知指示器。

6. Data Transformation Complexity

6. 数据转换复杂度

Does the spec involve complex data mapping, aggregation, or transformation across multiple entities?
  • Simple field mapping or filtering → likely fine
  • Multi-step transformations, joins across entities, or aggregations → likely too complex
该规格是否涉及跨多个实体的复杂数据映射、聚合或转换？
  • 简单字段映射或过滤 → 通常没问题
  • 多步转换、跨实体关联或聚合 → 通常过于复杂

7. Rough LOC Estimation

7. 大致代码行数估算

Mentally estimate the implementation. Consider:
  • New files that need to be created
  • New functions/methods
  • Data model changes (schema, migrations, types)
  • UI components (if applicable)
  • Test setup and assertions (unit tests are auto-generated alongside)
  • Error handling paths
  • Import statements and boilerplate
If the estimate exceeds ~150 LOC, the spec is at high risk of being too complex (leave headroom for the renderer to add necessary boilerplate).
从心理上估算实现所需的代码量。考虑：
  • 需要创建的新文件
  • 新函数/方法
  • 数据模型变更（ schema、迁移、类型）
  • UI组件（如适用）
  • 测试设置和断言（单元测试会自动生成）
  • 错误处理路径
  • 导入语句和样板代码
如果估算超过约150行代码，该规格存在过于复杂的高风险（需为渲染器添加必要的样板代码预留空间）。

Output Format

输出格式

The skill emits exactly one of these two strings, with no surrounding text, explanation, estimate, or breakdown:
ACCEPTABLE
or
TOO COMPLEX
The internal analysis (checklist, LOC estimation, reasoning) informs the verdict but must not appear in the output. The caller decides what to do with the result.
该skill仅输出以下两个字符串之一，无任何周围文本、解释、估算或拆分说明：
ACCEPTABLE
或
TOO COMPLEX
内部分析（检查清单、代码行数估算、推理）用于得出判定结果，但不得出现在输出中。调用方将决定如何处理该结果。

Integration with add-functional-spec / add-functional-specs

与add-functional-spec / add-functional-specs的集成

This skill is called during step 3 of the 
add-functional-spec
workflow (or per spec during 
add-functional-specs
), after drafting a spec but before inserting it into the file. The caller acts on the one-word verdict:
  • ACCEPTABLE — proceed to insert the spec.
  • TOO COMPLEX — invoke 
    break-down-func-spec
    to produce smaller specs, then insert each one individually (running conflict checks on each).
该skill在
add-functional-spec
工作流程的第3步（或
add-functional-specs
流程中针对单个规格）调用，即在起草规格后但插入文件前。调用方根据单字判定结果执行操作：
  • ACCEPTABLE — 继续插入规格。
  • TOO COMPLEX — 调用
    break-down-func-spec
    生成更小的规格，然后逐个插入（每个规格都需运行冲突检查）。