wtf.write-epic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Epic

撰写Epic

Create a GitHub Epic issue capturing a strategic initiative with stakeholders, goals, success metrics, and a feature breakdown scaffold.

创建一个GitHub Epic issue，记录包含干系人、目标、成功指标和功能分解框架的战略计划。

Process

流程

0. GitHub CLI setup

0. GitHub CLI 配置

Run the setup check from

../references/gh-setup.md

. Stop if

gh

is not installed or not authenticated. Note whether the extensions are available — this determines whether native dependency links are created in step 8.

Skip this step if gh-setup was already confirmed this session (e.g. when this skill is re-invoked via

write-feature

step 11 "Write another Epic").

运行

../references/gh-setup.md

中的配置检查。如果未安装

gh

或未完成认证，则停止操作。记录扩展是否可用——这将决定步骤8中是否创建原生依赖链接。

如果本次会话中已确认gh-setup完成（例如，通过

write-feature

步骤11“撰写另一个Epic”重新调用此技能），则跳过此步骤。

1. Capture the seed idea

1. 记录初始想法

Ask ONE question: "What initiative are you working on?"

Do not ask follow-up questions yet. Acknowledge the idea briefly and move straight to research.

提出一个问题：“你正在推进哪项计划？”

暂不追问后续问题。简要确认想法后直接进入研究环节。

2. Deep research

2. 深度调研

Run in parallel using the Agent tool and GitHub issue search:

Codebase exploration:

Use the Agent tool with these concrete searches (run in parallel):

Glob('**/{README,readme}.md')

Glob('docs/**/*.md')

Glob('**/*.{adr,ADR}.md')

— for existing product descriptions, ADRs, and architectural notes

```
Glob('src/**', 'lib/**', 'packages/**')
```
— to understand the module structure and which systems exist
```
Grep
```
for the initiative's key domain nouns across
```
*.{ts,tsx,js,jsx,py,go,rb,java,cs}
```
files — to find existing implementations, prior attempts, or integration points
```
Glob('**/{GLOSSARY,glossary,ubiquitous-language,domain}.md')
```
+
```
Glob('.github/**/*.md')
```
— for any existing domain glossary, ubiquitous language docs, or prior DDD artefacts

Wiki / glossary fetch: Fetch relevant GitHub wiki pages or in-repo glossary docs. Search for pages matching the initiative's domain area. Use these to:

Identify existing Ubiquitous Language terms the team already uses
Avoid introducing synonyms for already-named concepts
Surface any existing Bounded Context definitions

Related issues (optional — if GitHub is unavailable, skip this sub-step without comment):

Open and closed issues/epics that overlap or inform this initiative
Prior discussions, decisions, or rejected approaches

Synthesise findings internally. Do not dump raw research at the user.

并行使用Agent工具和GitHub问题搜索：

代码库探索：

使用Agent工具执行以下具体搜索（并行运行）：

Glob('**/{README,readme}.md')

Glob('docs/**/*.md')

Glob('**/*.{adr,ADR}.md')

—— 用于查找现有产品描述、ADR和架构说明

```
Glob('src/**', 'lib/**', 'packages/**')
```
—— 了解模块结构和现有系统
```
Grep
```
在
```
*.{ts,tsx,js,jsx,py,go,rb,java,cs}
```
文件中搜索计划的关键领域名词——查找现有实现、先前尝试或集成点

Glob('**/{GLOSSARY,glossary,ubiquitous-language,domain}.md')

Glob('.github/**/*.md')

—— 查找现有领域术语表、通用语言文档或先前的DDD工件

Wiki / 术语表获取： 获取相关的GitHub Wiki页面或代码库内的术语表文档。搜索与计划领域匹配的页面。使用这些内容：

识别团队已在使用的现有通用语言术语
避免为已命名的概念引入同义词
呈现任何现有限界上下文定义

相关问题（可选——若GitHub不可用，无需说明直接跳过此子步骤）：

与本计划重叠或相关的已打开和已关闭的问题/epic
先前的讨论、决策或被否决的方案

内部整合调研结果。不要向用户输出原始调研内容。

3. Grill the user

3. 向用户确认细节

Using what research revealed, ask targeted follow-up questions to close the remaining gaps. The topics below are a completeness checklist — only ask about items that research did not already answer:

Scope boundaries (what is explicitly out of scope?)
Success criteria (how will we know we're done?)
Stakeholders (Product Owner, Lead Designer, Tech Lead — skip any that don't apply)
Constraints or deadlines that must shape the approach
Any known risks or dependencies the research surfaced that need confirmation
Bounded Context: Which domain context(s) does this initiative live in? (Ask last — use option list if multiple contexts were found in research)
Ubiquitous Language: What domain actors (named roles, not "users") and domain verbs (business actions) define this space? Are there existing terms the team already uses that must be preserved?

Questioning style:

Ask questions one at a time in order of priority. Wait for the answer before asking the next.
Always use the
AskUserQuestion
tool for every question — including open-ended ones like "What are the success criteria?" or "Who is the stakeholder?". For each question, infer 1–2 likely answers from research (e.g. if research found a bounded context named "Payments", offer that as an option) and pass them as
```
options
```
. The UI automatically appends an "Other (type your answer)" escape hatch — do NOT add one manually.
- Example: for "Who is the primary stakeholder?", call
```
AskUserQuestion
```
  with
```
question: "Who is the primary stakeholder?"
```
  ,
```
header: "Stakeholder"
```
  , and
```
options: [{label: "Product Owner"}, {label: "CTO / Eng lead"}, {label: "External client"}]
```
  .
- Example for open-ended: for "What are the success criteria?", call
```
AskUserQuestion
```
  with
```
question: "What does success look like for this initiative?"
```
  ,
```
header: "Success criteria"
```
  , and
```
options
```
  pre-filled with 1–2 plausible outcomes inferred from research.
After each answer, acknowledge briefly and ask the next question.
Stop when you have enough to write a complete draft — do not ask questions you can fill in confidently from research. Skip any topic already answered by research.

利用调研结果，提出针对性的后续问题以填补剩余信息空白。以下主题是完整性检查清单——仅询问调研未回答的内容：

范围边界（明确排除哪些内容？）
成功标准（如何判断已完成？）
干系人（产品负责人、首席设计师、技术负责人——不适用的项可跳过）
必须影响方案的约束条件或截止日期
调研发现的需确认的已知风险或依赖项
限界上下文（Bounded Context）： 本计划属于哪些领域上下文？（最后询问——若调研发现多个上下文，则提供选项列表）
通用语言（Ubiquitous Language）： 定义此领域的领域参与者（命名角色，而非“用户”）和领域动词（业务动作）是什么？团队是否已有必须保留的现有术语？

提问方式：

按优先级逐个提问。等待回答后再提出下一个问题。
每个问题都必须使用
AskUserQuestion
工具——包括开放式问题，如“成功标准是什么？”或“干系人是谁？”。对于每个问题，从调研中推断1-2个可能的答案（例如，若调研发现名为“Payments”的限界上下文，则将其作为选项）并作为
```
options
```
传递。UI会自动添加“其他（输入你的答案）”选项——请勿手动添加。
- 示例：对于“主要干系人是谁？”，调用
```
AskUserQuestion
```
  ，参数为
```
question: "Who is the primary stakeholder?"
```
  ,
```
header: "Stakeholder"
```
  , and
```
options: [{label: "Product Owner"}, {label: "CTO / Eng lead"}, {label: "External client"}]
```
  。
- 开放式问题示例：对于“成功标准是什么？”，调用
```
AskUserQuestion
```
  ，参数为
```
question: "What does success look like for this initiative?"
```
  ,
```
header: "Success criteria"
```
  , and
```
options
```
  预填1-2个从调研中推断的合理结果。
每个回答后简要确认，然后提出下一个问题。
当获取到足够信息以撰写完整草稿时停止提问——不要询问可通过调研自信填补的内容。跳过调研已回答的任何主题。

4. DDD Language Check

4. DDD语言检查

Before drafting, review the seed idea and all gathered context against the rules in

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

Does the Epic title describe a business outcome, not a technology action?
Does the Goal use domain vocabulary — not engineering jargon?
Reframe any tech terms as business outcomes — the implementation detail belongs in Tasks.
Flag any ambiguous or undefined term and propose the domain-correct alternative.

撰写草稿前，对照

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

中的规则，复查初始想法和所有收集到的上下文：

Epic标题是否描述业务成果而非技术动作？
目标是否使用领域词汇而非工程术语？
将任何技术术语重新表述为业务成果——实现细节应放在任务中。
标记任何模糊或未定义的术语，并提出符合领域规范的替代方案。

5. Vertical slice assessment

5. 垂直切片评估

An epic must be a coherent, independently deliverable strategic initiative — it should produce real user or business value on its own, not only as a dependency for another epic.

This assessment runs on the gathered context (seed idea, research findings, and stakeholder answers) — before a draft exists. It catches structural incoherence early. A second, draft-level scope check runs at step 8 after the written artefact is complete.

Evaluate:

Passes → proceed.
Too broad → propose splitting into focused epics; present the breakdown and ask the user to confirm before continuing.
Has dependencies → identify them explicitly:
- Epics this epic depends on (must ship first)
- Epics that depend on this epic (will be blocked until this ships)

Record each dependency issue number — these are applied in step 8. Do not write them to the body yet to avoid double-applying; step 8 handles all body writes and native links together.

Epic必须是连贯、可独立交付的战略计划——它应能独立产生真实的用户或业务价值，而非仅作为其他Epic的依赖项。

此评估基于收集到的上下文（初始想法、调研结果和干系人回答）——在草稿生成前进行。它能及早发现结构不一致问题。在步骤8中，生成书面工件后还会进行第二次草稿级别的范围检查。

评估结果：

通过 → 继续。
范围过宽 → 建议拆分为聚焦的Epic；呈现拆分方案并请求用户确认后再继续。
存在依赖项 → 明确识别：
- 本Epic依赖的Epic（必须先交付）
- 依赖本Epic的Epic（本Epic交付前将被阻塞）

记录每个依赖项的问题编号——这些将在步骤8中应用。暂不要将其写入正文，避免重复应用；步骤8会统一处理所有正文写入和原生链接。

6. Draft the Epic

6. 草拟Epic

Produce a complete draft. Success Metrics must be specific and measurable. Feature Breakdown stays as empty placeholders.

Use the issue body structure from @.github/ISSUE_TEMPLATE/EPIC.md (ignore the YAML frontmatter — use only the markdown body below the second

---

delimiter). Fill in all sections with the gathered context. If the file is missing or the reference cannot be resolved, use the following minimal structure:

## Context

## Goal

## Success Metrics

## Feature Breakdown

## Risks

## Bounded Context

DDD writing rules for this draft:

Bounded Context: Fill in the Bounded Context field. If the epic spans multiple contexts, name each and describe where the seam is.
Context and Goal sections: Every sentence must use Ubiquitous Language. No tech jargon.
Success Metrics: Phrase as business-observable outcomes ("Merchants can view settlement status within 2 minutes of payment"), not system metrics ("API latency < 200ms").
Risks: Frame risks in domain terms ("Dispute resolution rules differ by jurisdiction") before listing technical risks.

生成完整草稿。成功指标必须具体且可衡量。功能分解保留为空占位符。

使用@.github/ISSUE_TEMPLATE/EPIC.md中的问题正文结构（忽略YAML前置内容——仅使用第二个

---

分隔符下方的markdown正文）。用收集到的上下文填充所有章节。若文件缺失或无法解析引用，则使用以下最小结构：

## Context

、

## Goal

、

## Success Metrics

、

## Feature Breakdown

、

## Risks

、

## Bounded Context

。

本草稿的DDD写作规则：

限界上下文（Bounded Context）： 填充限界上下文字段。若Epic跨多个上下文，则分别命名并描述衔接点。
Context和Goal章节： 每句话必须使用通用语言。禁止使用技术术语。
成功指标： 表述为可观察的业务成果（“商家可在付款后2分钟内查看结算状态”），而非系统指标（“API延迟<200ms”）。
风险： 先以领域术语描述风险（“争议解决规则因司法管辖区而异”），再列出技术风险。

7. Scope gate

7. 范围校验

This is a final structural guardrail that operates on the written draft — distinct from step 5, which checked intent before drafting. It runs before user review so any structural issues are caught while they are cheapest to fix. Even if step 5 passed, run this check: drafting sometimes reveals bundled objectives that were not visible in the abstract.

Look for these Epic-level split signals (heuristics — use judgement, not rigid thresholds):

The Goal statement contains multiple distinct business objectives joined by "and" — each could stand alone as a separate initiative
The Feature Breakdown has more than 8 proposed features — treat this as a signal worth scrutiny, not an automatic trigger (8 tightly related features in one domain can be fine)
The Epic spans more than one Bounded Context without a clear seam or handoff point
Success Metrics describe outcomes that belong to completely different user journeys
The epic's beneficiary cannot be stated in a single sentence without using "and" to cover unrelated groups

If no signals are present, proceed to creation.

If one or more signals fire, present your case: state which signals you found, explain why they suggest the epic should be split, and propose a concrete split (two or three focused epic titles with a one-line goal each). Then call

AskUserQuestion

with:

```
question
```
: "I think this Epic may be too broad — see my reasoning above. How do you want to proceed?"
```
header
```
: "Scope check"

options

{label: "Keep the original draft", description: "Proceed with the current draft without splitting"}

{label: "Split it", description: "Start over with one of the proposed smaller Epics"}

{label: "Stop here", description: "Exit without creating — I'll revisit the scope separately"}

Keep the original draft → proceed to user review (step 8) without further comment.
Split it → return to step 3 with the chosen focused Epic as the seed. Carry forward all research and codebase findings already gathered — only re-ask stakeholder questions that the narrowed scope makes ambiguous. Note the remaining proposed sub-epics to the user as follow-on work.
Stop here → exit.

这是针对书面草稿的最终结构防护措施——与步骤5不同，步骤5是在草拟前检查意图。在用户审核前运行此检查，以便在成本最低时发现任何结构问题。即使步骤5通过，也需运行此检查：草拟过程有时会暴露出抽象阶段未发现的捆绑目标。

查找这些Epic级别拆分信号（启发式规则——使用判断，而非严格阈值）：

目标语句包含多个由“and”连接的不同业务目标——每个目标可独立作为一项计划
功能分解包含超过8个拟议功能——将此视为值得审视的信号，而非自动触发拆分的条件（同一领域内8个紧密相关的功能是可行的）
Epic跨多个限界上下文且无明确衔接点或交接点
成功指标描述属于完全不同用户旅程的成果
无法用单句表述Epic的受益方，而无需使用“and”涵盖无关群体

若无信号触发，则继续创建。

若触发一个或多个信号，则说明理由：指出发现的信号，解释为何建议拆分Epic，并提出具体的拆分方案（2-3个聚焦的Epic标题及各自的单行目标）。然后调用

AskUserQuestion

：

```
question
```
: "I think this Epic may be too broad — see my reasoning above. How do you want to proceed?"
```
header
```
: "Scope check"

options

{label: "Keep the original draft", description: "Proceed with the current draft without splitting"}

{label: "Split it", description: "Start over with one of the proposed smaller Epics"}

{label: "Stop here", description: "Exit without creating — I'll revisit the scope separately"}

保留原始草稿 → 直接进入用户审核（步骤8），无需额外说明。
拆分 → 以选定的聚焦Epic为初始想法，返回步骤3。保留已收集的所有调研和代码库结果——仅重新询问因范围缩小而变得模糊的干系人问题。向用户说明剩余的拟议子Epic作为后续工作。
在此停止 → 退出。

8. Review with user

8. 用户审核

Show the draft. Then call

AskUserQuestion

with

question: "Does this look right?"

header: "Review"

, and

options: [{label: "Looks good — create the issue", description: "Proceed with issue creation"}, {label: "I have changes", description: "I want to adjust something first"}]

Apply edits, then proceed immediately.

展示草稿。然后调用

AskUserQuestion

，参数为

question: "Does this look right?"

header: "Review"

, and

options: [{label: "Looks good — create the issue", description: "Proceed with issue creation"}, {label: "I have changes", description: "I want to adjust something first"}]

。

应用修改后立即继续。

9. Create the issue

9. 创建问题

Note: Write the issue body to a temp file with the Write tool, then use
--body-file
to avoid shell quoting issues with multi-line content.

Title generation: Spawn a subagent using the
claude-haiku-4-5
model to generate a concise, domain-language title from the Epic's Goal. Pass in the Goal text and ask for a title (no prefix emoji/label needed — that is added below).

bash

undefined

注意：使用Write工具将问题正文写入临时文件，然后使用
--body-file
避免多行内容的shell引用问题。

标题生成： 使用
claude-haiku-4-5
模型生成子Agent，根据Epic的Goal生成简洁的领域语言标题。传入Goal文本并请求生成标题（无需前缀表情符号/标签——后续会添加）。

bash

undefined

Ensure the label exists before creating the issue

确保创建问题前标签已存在

gh label create epic --color 5319e7 --description "Strategic initiative spanning multiple features" 2>/dev/null || true

gh issue create --title "🎯 Epic: <title>" --body-file /tmp/wtf-epic-body.md --label "epic"


Print the issue URL and number.

**Native dependency links:** Epics are top-level — no `gh sub-issue` call is needed here. If `gh-issue-dependency-available` (from step 0), create a blocking link for each dependency identified in step 5:

```bash

gh label create epic --color 5319e7 --description "Strategic initiative spanning multiple features" 2>/dev/null || true

gh issue create --title "🎯 Epic: <title>" --body-file /tmp/wtf-epic-body.md --label "epic"


打印问题URL和编号。

**原生依赖链接：** Epics是顶级项——无需在此调用`gh sub-issue`。若步骤0中`gh-issue-dependency-available`可用，则为步骤5中识别的每个依赖项创建阻塞链接：

```bash

For each issue this epic depends on (must ship first):

对于本Epic依赖的每个问题（必须先交付）：

gh issue-dependency add <this_epic_number> --blocked-by <blocker_number>


If the extension is unavailable, warn the user — do not write dependency references into the issue body.

gh issue-dependency add <this_epic_number> --blocked-by <blocker_number>


若扩展不可用，则向用户发出警告——不要将依赖引用写入问题正文。

10. Update the wiki / glossary

10. 更新Wiki / 术语表

If this Epic introduced or refined any Bounded Context definitions or Ubiquitous Language terms (domain actors, domain verbs, domain objects), update the project's glossary:

Check whether a wiki page or in-repo glossary doc exists for this Bounded Context (e.g.
```
docs/glossary.md
```
, GitHub wiki page matching the context name).
If a page exists: add or update the relevant term definitions, linking back to the Epic issue number.
If no page exists: create one (prefer the GitHub wiki if available, otherwise
```
docs/glossary.md
```
), seeding it with the terms defined in this Epic.

Skip without comment if no terms were introduced. Report only the page name and terms added if an update was made.

若本Epic引入或完善了任何限界上下文定义或通用语言术语（领域参与者、领域动词、领域对象），则更新项目的术语表：

检查是否存在针对此限界上下文的Wiki页面或代码库内术语表文档（例如
```
docs/glossary.md
```
、与上下文名称匹配的GitHub Wiki页面）。
若页面存在：添加或更新相关术语定义，并链接回Epic问题编号。
若页面不存在：创建一个（优先使用GitHub Wiki，否则使用
```
docs/glossary.md
```
），并使用本Epic中定义的术语作为初始内容。

若未引入任何术语，则无需说明直接跳过。若进行了更新，则仅报告页面名称和添加的术语。

11. Offer to continue

11. 提供后续操作选项

Use the

AskUserQuestion

tool with the following question and options:

question: "What's next?"
header: "Next step"
options:
1. label: "Plan all Features" · description: "Propose the full Feature list for this Epic and create them one by one (default)"
2. label: "Write one Feature" · description: "Write a single Feature for this Epic now"
3. label: "Write another Epic" · description: "Start a new Epic from scratch"
4. label: "Stop here" · description: "Exit — no further action"

Route based on the answer:

Plan all Features → invoke the
```
epic-to-features
```
skill, passing the Epic number in as context.
Write one Feature → proceed with the
```
write-feature
```
skill, passing the Epic number in as context so the user is not asked for it again.
Write another Epic → restart this skill from step 1.
Stop here → exit.

Suggest clearing context before continuing to features if the conversation has grown long: "The context is getting long — you may want to
/clear
before continuing."

使用

AskUserQuestion

工具，参数如下：

question: "What's next?"
header: "Next step"
options:
1. label: "Plan all Features" · description: "Propose the full Feature list for this Epic and create them one by one (default)"
2. label: "Write one Feature" · description: "Write a single Feature for this Epic now"
3. label: "Write another Epic" · description: "Start a new Epic from scratch"
4. label: "Stop here" · description: "Exit — no further action"

根据回答进行路由：

Plan all Features → 调用
```
epic-to-features
```
技能，并传入Epic编号作为上下文。
Write one Feature → 继续执行
```
write-feature
```
技能，并传入Epic编号作为上下文，避免再次向用户询问。
Write another Epic → 从步骤1重新启动此技能。
Stop here → 退出。

建议在继续处理功能前清除上下文（若对话已较长）："The context is getting long — you may want to
/clear
before continuing."