design-refinement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Refinement

设计细化

Overview

概述

This skill deepens an existing design tree.

Its job is to take major branches that are still vague and push them toward implementable leaf nodes. It should make the design more specific, more bounded, and harder to misread during implementation.

本技能用于深化现有设计树。

其职责是将仍模糊的主要分支推进至可落地的叶节点，让设计更具体、边界更清晰，避免在实现过程中出现误解。

When to Use

使用场景

Use this skill when:

the design tree already exists
the design is still too high-level to guide implementation planning
important branches lack interfaces, boundaries, failure behavior, or validation detail
the user asks to make the design more concrete, more detailed, or more complete

Do not use this skill when:

there is no design tree yet
the main problem is a single bounded decision with multiple options
the main question is whether the current design is ready for planning
```
design_target_type
```
is missing from the current design state
the task is really a report, note, or SOP draft

在以下场景使用本技能：

已存在设计树
设计仍过于高层级，无法指导实现规划
重要分支缺少接口、边界、故障行为或验证细节
用户要求让设计更具体、更详细或更完整

请勿在以下场景使用本技能：

尚未有设计树
核心问题是单个明确决策节点存在多种方案
核心问题是当前设计是否已准备好进入规划阶段
当前设计状态中缺少
```
design_target_type
```
字段
任务实际是撰写报告、笔记或SOP草稿

Required Input

必要输入

Do not continue refinement without an explicit

design_target_type

If the design state is missing that field:

stop refinement
do not silently assume
```
system
```
hand back to
```
design-orchestrator
```
or
```
design-structure
```
so the type can be set explicitly

若未明确提供

design_target_type

，请勿继续细化。

若设计状态中缺少该字段：

停止细化
不要默认假设为
```
system
```
将任务交回
```
design-orchestrator
```
或
```
design-structure
```
，以便明确设置类型

Leaf Node Standard

叶节点标准

Use the target-type-specific completion standard from

../design-tree-core/REFERENCE.md

In summary:

```
system
```
: responsibility, non-responsibility, adjacent interaction, failure, validation
```
workflow
```
: stage goal, input/output, owner, rollback, quality gate
```
methodology
```
: applicability, non-applicability, decision rules, handoff form, exit condition
```
framework
```
: dimension or module, non-ownership, routing rule, handoff form, completion rule

If those answers are still missing for the current target type, the branch is not done.

使用

../design-tree-core/REFERENCE.md

中针对目标类型的完成标准。

总结如下：

```
system
```
：职责、非职责、相邻交互、故障处理、验证方式
```
workflow
```
：阶段目标、输入/输出、负责人、回滚机制、质量 gate
```
methodology
```
：适用场景、非适用场景、决策规则、移交表单、退出条件
```
framework
```
：维度或模块、非职责范围、路由规则、移交表单、完成规则

若当前目标类型仍缺少上述内容，则该分支未完成。

Refinement vs Derivation Boundary

细化与派生边界

Refinement should continue only while a branch remains part of the current tree's original core question.

Use the shared derivation rules in

../design-tree-core/REFERENCE.md

as the source of truth.

Stop refining inline when a branch begins to show all of the following:

it is answering a second distinct core question
it requires repeated local routing decisions of its own
it needs its own scope boundary
it needs its own completion check
continuing inline refinement would make the parent tree harder to route

When those conditions appear:

do not keep expanding the branch inline
surface the branch as a candidate for derivation
hand back to
```
design-orchestrator
```
or
```
design-structure
```
for explicit derived-tree creation

仅当分支仍属于当前树的原始核心问题时，才继续{ "description": "优化现有设计树，直到关键分支达到可实施状态。适用于已有高层级结构，但重要分支仍模糊、浅显或未解决的场景。当用户需要对部分设计完成的系统进行更深入的分解、边缘场景覆盖、故障路径明确、接口细节补充或验证标准定义时，触发此技能。请勿用于从零开始创建初始设计框架，或针对单个明确决策节点对比选项。", "content": "# 设计优化

Core Responsibilities

概述

Your responsibilities are:

Walk unresolved design branches one at a time.
Prioritize high-risk, high-dependency, or high-ambiguity branches first.
Expand branches into concrete sub-branches and leaf nodes using the current
```
design_target_type
```
.
Surface hidden assumptions and edge cases.
Add failure-path and validation detail where missing.
Explicitly mark newly discovered decision nodes instead of pretending they are settled.
Resolve
```
[RESEARCH]
```
nodes by performing deep validation of external dependencies (API compatibility, version constraints, integration patterns, error handling, rate limits). Replace
```
[RESEARCH]
```
with
```
✓
```
when validated,
```
✗
```
when rejected, or
```
[DECISION]
```
if alternatives need evaluation. If validation cannot be completed in the current context, document what was learned and retain
```
[RESEARCH]
```
.

此技能用于深化现有设计树。

其职责是将仍模糊的主要分支推进至可落地的叶子节点，使设计更具体、边界更清晰，避免在实施过程中出现误解。

Expected Outputs

适用场景

Produce or update a

design_state

that includes:

```
design_target_type
```
refined
```
design_tree
```
branches
updated
```
open_branches
```
```
confirmed_assumptions
```
```
risks
```
```
validation
```
updated
```
external_dependencies
```
if any [RESEARCH] nodes were resolved
new
```
decision_nodes
```
if discovered

在以下情况使用此技能：

已存在设计树
设计仍过于抽象，无法指导实施规划
重要分支缺少接口、边界、故障行为或验证细节
用户要求让设计更具体、更详细或更完整

请勿在以下情况使用此技能：

尚未形成设计树
核心问题是单个有多个选项的限定决策
核心问题是当前设计是否已准备好进入规划阶段
当前设计状态缺少
```
design_target_type
```
字段
任务实际是撰写报告、笔记或SOP草案

Diagram Conventions

必要输入

Use character diagrams inside code blocks (no language tag) to visualize component interactions, failure paths, and state transitions.

若无明确的

design_target_type

，请勿继续优化。

若设计状态缺少该字段：

停止优化
请勿默认假设为
```
system
```
将任务交回
```
design-orchestrator
```
或
```
design-structure
```
，以便明确设置类型

Sequence Diagrams

叶子节点标准

Use when a leaf node describes "how it interacts with adjacent parts" and involves 3+ components.

Client          API Server      Auth Service     DB
  │                │                │             │
  │── request ────→│                │             │
  │                │── verify ────→│             │
  │                │←── ok ────────│             │
  │                │── insert ─────────────────→│
  │←── response ───│                │             │

Rules:

Three-column maximum; split into two diagrams if more participants
Lifelines use
```
│
```
; messages use
```
──→
```
(right) or
```
←──
```
(left)
Labels sit on the arrow line:
```
── label ──→
```
Participant names ≤20 chars, left-aligned at top
Omit ACK returns unless they carry meaningful data

使用

../design-tree-core/REFERENCE.md

中针对目标类型的完成标准。

总结：

```
system
```
：职责、非职责、相邻交互、故障处理、验证标准
```
workflow
```
：阶段目标、输入/输出、负责人、回滚机制、quality gate
```
methodology
```
：适用场景、非适用场景、决策规则、交接表单、退出条件
```
framework
```
：维度或模块、非归属范围、路由规则、交接表单、完成规则

若当前目标类型仍缺少上述内容，则该分支尚未完成。

Data Flow Diagrams

优化与派生边界

Use when showing data pipelines or transformation chains.

Source
    │
    ▼
Transform ──── enrich ────→ Enrichment
    │                            │
    ▼                            ▼
Sink A                     Cache Store

Components as plain text (no brackets)
Vertical:
```
│
```
and
```
▼
```
; horizontal:
```
──→
```
; return:
```
◄────
```

仅当分支仍属于当前树的原始核心问题范畴时，才继续优化。

以

../design-tree-core/REFERENCE.md

中的共享派生规则为权威依据。

当分支同时出现以下所有特征时，停止内联优化：

正在回答第二个独立的核心问题
需要自行重复进行本地路由决策
需要拥有自己的范围边界
需要自己的完成检查机制
继续内联优化会使父树的路由难度增加

出现上述情况时：

请勿继续内联扩展分支
将该分支标记为派生候选
交回
```
design-orchestrator
```
或
```
design-structure
```
以明确创建派生树

State Machine Diagrams

核心职责

Use when a component has 3+ states with transitions.

┌──────────┐     approve     ┌───────────┐
│ Pending  │───────────────→│ Approved  │
└──────────┘                 └───────────┘
     │                            │
     │ timeout               │ start
     ▼                            ▼
┌──────────┐             ┌──────────┐     ok     ┌───────────┐
│ Expired  │             │ Running  │───────────→│ Succeeded │
└──────────┘             └──────────┘             └───────────┘

State boxes use
```
┌ ┐ └ ┘ ─ │
```
Transitions:
```
──→
```
with label above/below
Terminal states can include
```
✓
```
or
```
✗
```

你的职责包括：

逐一处理未解决的设计分支。
优先处理高风险、高依赖或高模糊性的分支。
根据当前
```
design_target_type
```
将分支扩展为具体的子分支和叶子节点。
揭示隐藏假设和边缘场景。
补充缺失的故障路径和验证细节。
明确标记新发现的决策节点，而非假装已解决。
通过深度验证外部依赖（API兼容性、版本约束、集成模式、错误处理、速率限制）解决
```
[RESEARCH]
```
节点。验证通过则替换为
```
✓
```
，验证失败则替换为
```
✗
```
，若需评估替代方案则替换为
```
[DECISION]
```
。若当前上下文无法完成验证，记录已了解的信息并保留
```
[RESEARCH]
```
。

When to Add Diagrams

预期输出

Sequence: 3+ components exchanging messages
Data flow: pipeline with 3+ stages or branching paths
State machine: a component has 3+ states with transitions
Do NOT add a diagram for 2-node linear flows — use a numbered list instead
Max width: 78 characters

生成或更新包含以下内容的

design_state

：

```
design_target_type
```
优化后的
```
design_tree
```
分支
更新后的
```
open_branches
```
```
confirmed_assumptions
```
```
risks
```
```
validation
```
若有
```
[RESEARCH]
```
节点被解决，更新
```
external_dependencies
```
若发现新节点，添加
```
decision_nodes
```

Entry and Exit Criteria

图表规范

Enter when:

a design tree already exists
important branches remain vague or incomplete

Exit when:

key branches have been refined to implementation-ready leaves
the remaining work is mainly decision evaluation or readiness checking

在代码块内使用字符图表（无需语言标签）可视化组件交互、故障路径和状态转换。

Handoff Rules

序列图

Hand off to
```
decision-evaluation
```
when you surface a clear decision node with multiple real options.
Hand off to
```
design-readiness-check
```
when key branches are closed and the main question becomes readiness.
Hand back to
```
design-structure
```
if the design tree itself is missing a foundational branch.

Hand back to

design-orchestrator

design-structure

immediately if

design_target_type

is missing.

Do not invent fake option comparisons just to make progress.
Do not use refinement to absorb a branch that should become a derived tree.
Do not force workflow, methodology, or framework branches into system-shaped leaves.

当叶子节点描述“如何与相邻组件交互”且涉及3个及以上组件时使用。

Client          API Server      Auth Service     DB
  │                │                │             │
  │── request ────→│                │             │
  │                │── verify ────→│             │
  │                │←── ok ────────│             │
  │                │── insert ─────────────────→│
  │←── response ───│                │             │

规则：

最多三列；若参与者超过三个，拆分为两个图表
生命线使用
```
│
```
；消息使用
```
──→
```
（向右）或
```
←──
```
（向左）
标签置于箭线上：
```
── label ──→
```
参与者名称≤20字符，顶部左对齐
除非携带有效数据，否则省略ACK返回

Journal Integration

数据流图

When operating on a task tracked under

.agents/tasks/<task-id>/

, append a journal entry at this skill's milestone.

Trigger: after a refinement pass updates the persisted design tree
Reserved key(s):
```
saved
```
(re-save) and optionally
```
note
```
for what was refined

Entry shape:

## <ISO8601-timestamp> — design-refinement
saved: docs/design-tree/<file>.md
[optional ≤ 15-line body; longer content goes to artifacts/]

Resolve the task id from the explicit caller argument or

.agents/tasks/.current

. If neither resolves, skip the append; do not guess.

See

task-journal

for the full convention.

用于展示数据管道或转换链时使用。

Source
    │
    ▼
Transform ──── enrich ────→ Enrichment
    │                            │
    ▼                            ▼
Sink A                     Cache Store

组件使用纯文本（无括号）
垂直方向：
```
│
```
和
```
▼
```
；水平方向：
```
──→
```
；返回：
```
◄────
```

—

状态机图

—

当组件有3个及以上状态且存在转换时使用。

┌──────────┐     approve     ┌───────────┐
│ Pending  │───────────────→│ Approved  │
└──────────┘                 └───────────┘
     │                            │
     │ timeout               │ start
     ▼                            ▼
┌──────────┐             ┌──────────┐     ok     ┌───────────┐
│ Expired  │             │ Running  │───────────→│ Succeeded │
└──────────┘             └──────────┘             └───────────┘

状态框使用
```
┌ ┐ └ ┘ ─ │
```
转换：
```
──→
```
，标签置于上方/下方
终端状态可包含
```
✓
```
或
```
✗
```

—

何时添加图表

—

序列图：3个及以上组件交互消息
数据流图：包含3个及以上阶段或分支路径的管道
状态机图：组件有3个及以上状态且存在转换
请勿为双节点线性流添加图表——改用编号列表
最大宽度：78字符

—

进入与退出条件

—

进入条件：

已存在设计树
重要分支仍模糊或不完整

退出条件：

关键分支已优化至可实施的叶子节点
剩余工作主要为决策评估或就绪检查

—

交接规则

—

当发现明确的多选项决策节点时，交至
```
decision-evaluation
```
。
当关键分支已完成，核心问题变为就绪性检查时，交至
```
design-readiness-check
```
。
若设计树本身缺少基础分支，交回
```
design-structure
```
。

若缺少

design_target_type

，立即交回

design-orchestrator

或

design-structure

。

请勿为推进进度伪造选项对比。
请勿通过优化吸收应成为派生树的分支。
请勿强行将workflow、methodology或framework分支转换为system形态的叶子节点。

—

日志集成

—

当处理

.agents/tasks/<task-id>/

路径下跟踪的任务时，在此技能的里程碑处追加日志条目。

触发条件： 完成一轮优化并更新持久化设计树后
保留关键字：
```
saved
```
（重新保存），可选
```
note
```
用于记录优化内容

条目格式：

## <ISO8601-timestamp> — design-refinement
saved: docs/design-tree/<file>.md
[可选≤15行正文；更长内容请存入artifacts/]

从调用方的显式参数或

.agents/tasks/.current

中解析任务ID。若两者均无法解析，则跳过追加操作，请勿猜测。完整约定请参考

task-journal

。",