wtf.refine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refine

优化流程

Update an existing Epic, Feature, or Task issue based on new insights. Core value: merges insights from any source, determines exactly which sections change, re-runs only the validations those changes require, shows you a precise diff before touching anything, and cascades to children so nothing goes stale.

基于新见解更新现有的Epic、Feature或Task议题。核心价值：整合来自任意来源的见解，精准确定需要修改的部分，仅重新运行变更所需的验证，在执行任何修改前展示精确的差异对比，并级联更新子议题，避免内容过时。

Process

流程步骤

0. GitHub CLI setup

0. GitHub CLI 配置

Run steps 1–2 of

../references/gh-setup.md

(install check and auth check). Stop if

gh

is not installed or not authenticated. Note whether the extensions are available — they are used in step 1 (hierarchy fetch) and step 9 (cascade).

Skip this step if gh-setup was already confirmed this session.

执行

../references/gh-setup.md

中的步骤1-2（安装检查和身份验证检查）。如果未安装

gh

或未完成身份验证，则停止操作。记录扩展是否可用——它们将在步骤1（层级获取）和步骤9（级联更新）中使用。如果本次会话已确认完成gh配置，则跳过此步骤。

1. Identify the issue and its hierarchy

1. 确定议题及其层级结构

If an issue number was passed in as context or a CLI argument, use it directly. Otherwise call

AskUserQuestion

with

question: "Which issue are you refining?"

header: "Issue"

, and

options

pre-filled with recently-updated open issues across all WTF labels (epic, feature, task) inferred from:

bash

gh issue list --label "epic,feature,task" --state open --json number,title,labels --limit 10

Fetch the issue:

bash

gh issue view <issue_number> --json number,title,body,labels,comments,updatedAt

Detect the issue type from its labels:

Has label
```
epic
```
→ type = Epic
Has label
```
feature
```
→ type = Feature
Has label
```
task
```
→ type = Task

None of the above → call

AskUserQuestion

with

question: "I couldn't detect the type from the labels. What kind of issue is this?"

header: "Issue type"

, and

options: [{label: "Epic"}, {label: "Feature"}, {label: "Task"}]

Fetch the hierarchy for context and cascade planning:

bash

undefined

如果通过上下文或CLI参数传入了议题编号，则直接使用该编号。否则调用

AskUserQuestion

，参数为

question: "你要优化哪个议题？"

，

header: "议题"

，并根据以下命令获取的所有WTF标签（epic、feature、task）下最近更新的开放议题预填充

options

：

bash

gh issue list --label "epic,feature,task" --state open --json number,title,labels --limit 10

获取议题详情：

bash

gh issue view <issue_number> --json number,title,body,labels,comments,updatedAt

从标签检测议题类型：

包含
```
epic
```
标签 → 类型 = Epic
包含
```
feature
```
标签 → 类型 = Feature
包含
```
task
```
标签 → 类型 = Task

以上都不满足 → 调用

AskUserQuestion

，参数为

question: "我无法从标签中检测议题类型。这是什么类型的议题？"

，

header: "议题类型"

，以及

options: [{label: "Epic"}, {label: "Feature"}, {label: "Task"}]

。

获取层级结构以用于上下文参考和级联更新规划：

bash

undefined

Parent (always fetch — needed for context)

父议题（必须获取——用于上下文参考）

gh sub-issue list <issue_number> --relation parent

Children (needed for cascade planning in step 9)

子议题（步骤9中级联更新规划需要）

gh sub-issue list <issue_number>


For the parent issue, fetch its body to extract goal, bounded context, and success metrics — these inform whether a change in the child conflicts with the parent's intent.

gh sub-issue list <issue_number>


对于父议题，获取其正文以提取目标、限定上下文和成功指标——这些信息用于判断子议题的变更是否与父议题的意图冲突。

2. Gather insights from all sources

2. 从所有来源收集见解

Merge insights from every available source into a single consolidated list. Process all sources in parallel:

a. CLI argument / conversation context

If the user passed insight text in the invocation (e.g.

refine #42 "scope changed — exclude mobile"

), treat that as the primary insight. If nothing was passed, call

AskUserQuestion

with

question: "What changed or what new insight should I incorporate?"

header: "Insight"

, and

options

pre-filled with 1–2 plausible changes inferred from recent issue comments (e.g. the last comment's key point).

b. GitHub comments since last body edit

Extract comments posted after the issue body was last edited:

bash

gh issue view <issue_number> --json comments,updatedAt \
  --jq '.updatedAt as $bodyUpdatedAt | .comments[] | select(.createdAt > $bodyUpdatedAt) | "[\(.author.login)] \(.body)"'

Read each comment and extract actionable insights — discard discussion noise ("+1", "agreed", "thanks"). Synthesise into concrete change signals (e.g. "Stakeholder comment: settlement must support multi-currency").

c. Referenced files

If the user referenced any file paths or URLs in the CLI argument or conversation, read them now:

File paths → use the Read tool
URLs → use the WebFetch tool (if available) or ask the user to paste the relevant content

Extract the relevant change signals from each document.

d. Consolidate

Merge all signals into a numbered list of insights. Present them briefly to the user:

"I found [n] insight(s) to incorporate:

[insight summary]

[insight summary] ..."

Call

AskUserQuestion

with

question: "Does this capture everything you want to incorporate?"

header: "Insights"

, and

options: [{label: "Yes — proceed", description: "Continue with these insights"}, {label: "Add more", description: "I have additional context to provide"}, {label: "Remove one", description: "Some of these aren't relevant"}]

Apply any adjustments before continuing.

将所有可用来源的见解合并为一个统一列表。并行处理所有来源：

a. CLI参数 / 对话上下文

如果用户在调用时传入了见解文本（例如

refine #42 "范围变更——排除移动端"

），则将其作为主要见解。如果未传入任何内容，则调用

AskUserQuestion

，参数为

question: "有什么变更或新见解需要整合？"

，

header: "见解"

，并根据最近的议题评论推断1-2个合理变更预填充

options

（例如最后一条评论的核心要点）。

b. 上次正文编辑后的GitHub评论

提取议题正文上次编辑后发布的评论：

bash

gh issue view <issue_number> --json comments,updatedAt \
  --jq '.updatedAt as $bodyUpdatedAt | .comments[] | select(.createdAt > $bodyUpdatedAt) | "[\(.author.login)] \(.body)"'

读取每条评论并提取可执行的见解——剔除讨论噪音（如"+1"、"同意"、"谢谢"）。将其整合为具体的变更信号（例如"利益相关者评论：结算必须支持多币种"）。

c. 引用文件

如果用户在CLI参数或对话中引用了文件路径或URL，现在读取这些内容：

文件路径 → 使用Read工具
URL → 使用WebFetch工具（如果可用）或请求用户粘贴相关内容

从每个文档中提取相关的变更信号。

d. 整合

将所有信号合并为编号列表形式的见解。向用户简要展示：

"我找到了[n]条需要整合的见解：

[见解摘要]

[见解摘要] ..."

调用

AskUserQuestion

，参数为

question: "这是否涵盖了你想要整合的所有内容？"

，

header: "见解确认"

，以及

options: [{label: "是的——继续", description: "基于这些见解继续操作"}, {label: "添加更多", description: "我还有额外的上下文要提供"}, {label: "移除部分", description: "其中一些见解不相关"}]

。

在继续前应用所有调整。

3. Classify the changes

3. 对变更进行分类

For each insight, determine which sections of the issue it affects and what type of change it is. This classification drives which validations run in step 4 and which sections are rewritten in step 5.

Change types and their affected sections:

Change type	Affected (Epic)	Affected (Feature)	Affected (Task)
Scope narrowed / expanded	Goal, Success Metrics, Feature Breakdown	ACs, Edge Cases, Proposed Tasks	Gherkin, Functional Description
New constraint	Risks, Bounded Context	ACs, Edge Cases, Rollout	Contracts, Observability, Rollout
Domain language correction	Context, Goal, Bounded Context	Capability name, User Stories, ACs	Gherkin steps, Contracts
New stakeholder / actor	Context, Goal	Capability name, User Stories	—
New domain event	—	Domain Events	Gherkin (When steps), Contracts
Technical constraint	—	Edge Cases	Contracts, Technical Approach
Deadline / priority	Risks	—	—

Produce a change map — a structured internal summary:

Change map:
  scope changed:        yes
  DDD language changed: no
  ACs changed:          yes
  Gherkin affected:     yes  (because ACs changed)
  Contracts affected:   no
  Sections to rewrite:  [Goal, Success Metrics] / [ACs, Edge Cases] / [Gherkin, Functional Description]

针对每条见解，确定它会影响议题的哪些部分以及变更类型。此分类将决定步骤4中运行哪些验证，以及步骤5中重写哪些部分。

变更类型及其影响的部分：

变更类型	影响（Epic）	影响（Feature）	影响（Task）
范围缩小/扩大	目标、成功指标、功能分解	验收标准、边缘案例、拟议任务	Gherkin用例、功能描述
新增约束	风险、限定上下文	验收标准、边缘案例、发布计划	契约、可观测性、发布计划
领域语言修正	上下文、目标、限定上下文	能力名称、用户故事、验收标准	Gherkin步骤、契约
新增利益相关者/参与者	上下文、目标	能力名称、用户故事	—
新增领域事件	—	领域事件	Gherkin（When步骤）、契约
技术约束	—	边缘案例	契约、技术方案
截止日期/优先级	风险	—	—

生成变更映射——结构化的内部摘要：

变更映射:
  范围变更:        是
  DDD语言变更:     否
  验收标准变更:     是
  Gherkin受影响:   是 （因为验收标准变更）
  契约受影响:       否
  需重写的部分:     [目标、成功指标] / [验收标准、边缘案例] / [Gherkin用例、功能描述]

4. Re-run relevant validations only

4. 仅重新运行相关验证

Using the change map from step 3, run only the validations that apply. Skip the rest — do not re-validate unchanged sections.

Scope changed → Vertical slice + Scope gate

Re-assess whether the refined issue still satisfies the vertical slice requirement and passes the scope gate for its type. Use the same criteria as in the original write-* skill:

Epic scope gate: split signals (multiple business objectives, >8 features, spans contexts without seam)
Feature scope gate: split signals (>6 ACs, multiple actors, "and" in capability name)
Task scope gate: split signals (>4 Gherkin scenarios, >4 unrelated modules, migration + behavior bundled)

If a split signal fires on the refined issue, present it as a refinement concern (not a blocker). Call

AskUserQuestion

with the same options as in the original skill: keep / split / stop.

Domain language changed → DDD Language Guard

Re-run the checks from

../references/ddd-writing-rules.md

on any section whose text is being rewritten. Flag and correct violations silently; note corrections in the diff (step 5).

ACs changed (Feature or Task) → Gherkin re-derivation

If Feature ACs changed, mark the Proposed Tasks section as potentially stale — note which tasks may need re-scoping. Do not automatically update child Tasks here; that is handled in step 9 (cascade).

If Task ACs changed, re-derive only the Gherkin scenarios that map to the changed AC(s). Keep unchanged scenarios exactly as they are.

使用步骤3中的变更映射，仅运行适用的验证。跳过其余验证——不要重新验证未变更的部分。

范围变更 → 垂直切片 + 范围检查

重新评估优化后的议题是否仍满足垂直切片要求，并通过对应类型的范围检查。使用与原始编写技能相同的标准：

Epic范围检查：拆分信号（多个业务目标、超过8个功能、跨上下文且无衔接）
Feature范围检查：拆分信号（超过6条验收标准、多个参与者、能力名称包含"和"）
Task范围检查：拆分信号（超过4个Gherkin场景、超过4个不相关模块、迁移与行为捆绑）

如果优化后的议题触发拆分信号，将其作为优化关注点（而非阻塞点）。调用

AskUserQuestion

，提供与原始技能相同的选项：保留/拆分/停止。

领域语言变更 → DDD语言校验

对任何要重写文本的部分，重新运行

../references/ddd-writing-rules.md

中的检查。自动标记并修正违规内容；在差异对比（步骤5）中记录修正内容。

验收标准变更（Feature或Task）→ Gherkin重新推导

如果Feature的验收标准变更，将拟议任务部分标记为可能过时——记录哪些任务可能需要重新规划范围。此处不要自动更新子Task；这将在步骤9（级联更新）中处理。

如果Task的验收标准变更，仅重新推导与变更验收标准对应的Gherkin场景。未变更的场景保持原样。

5. Draft the section updates and show a diff

5. 起草部分更新内容并展示差异对比

Produce the updated content for each section in the change map. Do not touch sections that are not in the change map.

Present a section-by-section before/after diff for every changed section. Format each section's diff as:

undefined

为变更映射中的每个部分生成更新内容。不要触碰变更映射外的部分。

为每个变更部分展示分节的前后差异对比。每个部分的差异对比格式如下：

undefined

[Section name]

[部分名称]

BEFORE: [original text]

AFTER: [updated text]


Then call `AskUserQuestion` with `question: "Does this diff look right?"`, `header: "Diff review"`, and `options: [{label: "Looks good — apply it", description: "Write the changes to the issue"}, {label: "I have corrections", description: "I want to adjust one or more sections"}, {label: "Start over", description: "The insights were wrong — let me re-describe what changed"}]`.

Apply any corrections, then proceed.

BEFORE: [原始文本]

AFTER: [更新文本]


然后调用`AskUserQuestion`，参数为`question: "这个差异对比看起来正确吗？"`，`header: "差异审核"`，以及`options: [{label: "看起来没问题——应用变更", description: "将变更写入议题"}, {label: "我需要修正", description: "我要调整一个或多个部分"}, {label: "重新开始", description: "见解有误——让我重新描述变更内容"}]`。

应用所有修正，然后继续。

6. Lifecycle label check

6. 生命周期标签检查

Check the current labels on the issue:

bash

gh issue view <issue_number> --json labels --jq '.labels[].name'

Stale label rules by change type:

What changed	Stale labels (Task)	Stale labels (Feature)
Gherkin scenarios changed	`implemented` , `verified`	—
ACs changed	`verified`	DoR: "Acceptance criteria written and reviewed" unchecked
Contracts changed	`implemented` , `verified`	—
Functional Description changed	—	—

If any stale labels are present, call

AskUserQuestion

with:

```
question
```
: "The following labels may no longer be accurate after this refinement: [list]. How should I handle them?"
```
header
```
: "Stale labels"

options

[{label: "Strip stale labels", description: "Remove the labels that no longer reflect reality (recommended)"}, {label: "Keep labels as-is", description: "Leave labels unchanged — I'll manage them manually"}]

Record the decision for the audit comment in step 8.

检查议题当前的标签：

bash

gh issue view <issue_number> --json labels --jq '.labels[].name'

按变更类型划分的过时标签规则：

变更内容	过时标签（Task）	过时标签（Feature）
Gherkin场景变更	`implemented` , `verified`	—
验收标准变更	`verified`	DoR：「验收标准已编写并审核」未勾选
契约变更	`implemented` , `verified`	—
功能描述变更	—	—

如果存在任何过时标签，调用

AskUserQuestion

，参数为：

```
question
```
: "优化后以下标签可能不再准确：[列表]。我该如何处理？"
```
header
```
: "过时标签"

options

[{label: "移除过时标签", description: "删除不再符合实际情况的标签（推荐）"}, {label: "保持标签不变", description: "保留标签——我会手动管理"}]

记录该决定，用于步骤8的审计评论。

7. Apply the changes

7. 应用变更

Read the current issue body, merge only the changed sections (preserving all unchanged content), and write the updated body:

bash

gh issue view <issue_number> --json body -q .body > /tmp/wtf-refine-body.md

Use the Edit tool to replace each changed section in

/tmp/wtf-refine-body.md

with its updated content. Preserve all other sections verbatim.

bash

gh issue edit <issue_number> --body-file /tmp/wtf-refine-body.md

If stale labels should be stripped (from step 6):

bash

gh issue edit <issue_number> --remove-label "implemented,verified"

读取当前议题正文，仅合并变更部分（保留所有未变更内容），并写入更新后的正文：

bash

gh issue view <issue_number> --json body -q .body > /tmp/wtf-refine-body.md

使用Edit工具将

/tmp/wtf-refine-body.md

中的每个变更部分替换为更新后的内容。所有其他部分保持原样。

bash

gh issue edit <issue_number> --body-file /tmp/wtf-refine-body.md

如果需要移除过时标签（来自步骤6）：

bash

gh issue edit <issue_number> --remove-label "implemented,verified"

Only remove labels that were confirmed stale — use the actual list

仅移除确认过时的标签——使用实际列表


Print the updated issue URL.


打印更新后的议题URL。

8. Post the audit trail comment

8. 发布审计追踪评论

Post a structured comment summarising the refinement:

bash

gh issue comment <issue_number> --body "<audit_comment>"

The audit comment must include:

markdown

undefined

发布结构化评论总结优化操作：

bash

gh issue comment <issue_number> --body "<audit_comment>"

审计评论必须包含：

markdown

undefined

Refinement — <YYYY-MM-DD>

优化记录 — <YYYY-MM-DD>

Insights incorporated:

[insight 1]
[insight 2]

Sections updated: [comma-separated list]

Validations re-run: [scope gate / DDD guard / Gherkin re-derivation — or "none required"]

Labels affected: [stripped: implemented, verified — or "none"]

Children that may need refinement: [list with issue numbers and reason — or "none identified"]

undefined

整合的见解：

[见解1]
[见解2]

更新的部分： [逗号分隔的列表]

重新运行的验证： [范围检查 / DDD校验 / Gherkin重新推导 — 或 "无需验证"]

受影响的标签： [已移除：implemented, verified — 或 "无"]

可能需要优化的子议题： [含议题编号和原因的列表 — 或 "未识别"]

undefined

9. Cascade to affected children

9. 级联更新受影响的子议题

Using the hierarchy fetched in step 1, determine which children are affected by this refinement:

Epic refined:

Features whose scope overlaps the changed Goal or Success Metrics
Features listed in the Feature Breakdown that reference changed bounded context terms

Feature refined:

Tasks whose Gherkin scenarios directly test the changed ACs
Tasks whose Proposed Tasks checklist entry was modified or removed

Present the affected children as a numbered list. Then call

AskUserQuestion

with:

```
question
```
: "These child issues may be out of sync with the updated spec: [list]. How would you like to handle them?"
```
header
```
: "Cascade"

options

[{label: "Refine each one now", description: "Walk through

refine

 for each affected child in order (default)"}, {label: "I'll handle them manually", description: "Exit — I'll open each child and update it myself"}, {label: "Skip", description: "Leave children as-is"}]

Refine each one now → spawn one sub-agent per affected child in parallel using the Agent tool. Each sub-agent receives: the child issue number, the parent insight as pre-loaded context (so the user is not asked for it again), and instructions to run this skill from step 2. Do not run refinements inline or sequentially — use parallel sub-agents so all children are refined concurrently. Wait for all sub-agents to complete, then summarise results.
I'll handle them manually / Skip → exit.

If no children are affected, skip this step entirely.

使用步骤1中获取的层级结构，确定哪些子议题会受到本次优化的影响：

Epic已优化：

范围与变更后的目标或成功指标重叠的Feature
功能分解中引用了已变更限定上下文术语的Feature

Feature已优化：

Gherkin场景直接测试已变更验收标准的Task
拟议任务清单条目已修改或移除的Task

将受影响的子议题以编号列表形式展示。然后调用

AskUserQuestion

，参数为：

```
question
```
: "这些子议题可能与更新后的规范不一致：[列表]。你希望如何处理？"
```
header
```
: "级联更新"

options

[{label: "立即优化每个子议题", description: "按顺序为每个受影响的子议题执行

refine

流程（默认）"}, {label: "我会手动处理", description: "退出——我会打开每个子议题自行更新"}, {label: "跳过", description: "保持子议题不变"}]

立即优化每个子议题 → 使用Agent工具为每个受影响的子议题并行生成一个子Agent。每个子Agent将收到：子议题编号、预加载的父议题见解上下文（避免再次询问用户），以及从步骤2开始执行本技能的指令。不要按顺序或内联执行优化——使用并行子Agent同时优化所有子议题。等待所有子Agent完成后，总结结果。
我会手动处理 / 跳过 → 退出。

如果没有受影响的子议题，直接跳过此步骤。