management-talk

管理层沟通

受众与书面状态报告相同，但要适配沟通渠道——JIRA 评论、Slack 帖子、异步站会、电子邮件或会议要点。受众看得懂代码名称，但不会读代码。渠道决定内容长度、格式，以及页面上保留多少结构。

只要工程内容需要向上汇报、横向传达给产品或发布团队，或带入非工程会议，无论目的地是什么，都可以使用此模板。

何时调用

• “为管理层／高管／VP／总监／PM／发布经理写点东西”
• “把这段改写给［非工程受众］看”
• “让它不那么技术化”／“少点技术味”／“少用行话”
• “发一条 Slack 更新／站会记录／电子邮件”，内容涉及一项工程工作
• “执行摘要”／“高管摘要”／“领导层更新”／“状态更新”
• “根据一条工程更新，为［会议］准备发言要点”

如果触发后渠道仍不明确，只问一个简短问题——“JIRA、Slack、站会还是电子邮件？”——然后停止。

受众——“工程组织领导层”指什么

懂工程的非工程人员：VP、总监、PM、发布经理，以及在交付技术产品的公司任职的高管。他们看得懂产品和框架名称，也会交叉查阅 JIRA 编号和 PR。他们不会读代码。

他们想知道：*当前状态是什么、对客户意味着什么、由谁负责、接下来做什么。*他们不想知道：这个 bug 在函数层面是如何运作的。

这不适用于营销、财务、面向客户或真正的 ELI5 受众——这些情况需要另行改写。制作此类内容前，请先说明并确认。

语气

**保留。**产品名称、框架名称、团队负责的组件名称、JIRA 编号、PR 编号、客户／工作负载标识符（Tada、DeepSpeed、PyTorch、Llama-2-70B、vLLM、JIRA-12345、PR #5751）。这些是工程团队与领导层跟踪信息之间的桥梁。

**删去。**函数名称、文件路径、结构体字段、提交 SHA、代码表达式、环境变量名称、行号、内部数据结构行话（tadaLaunchPrepare、tada/prim.h::syncWaitPeer、scratchBuf、0e0a6bac）。这些对受众没有可执行价值。

**转述。**用一两句话把机制说成通俗易懂的因果关系。不要写“内核从 scratchBuf == NULL 中读取”，而要写“GPU 最终从未初始化的缓冲区中读取，并一直等待一个永远不会到来的信号。”转述时不要歪曲事实——竞态仍然是竞态；回归仍然是回归。

**不要删得过头。**工程组织的领导层能流畅理解概念层面的技术术语——竞态条件、同步、未初始化缓冲区、快速路径、临时解决方案、注册、队列、驱动程序、内核（GPU 语境）。界限在于：概念本身存在且与此相关（保留），还是函数／结构体／文件／SHA 的具体细节（删去）。把“竞态”换成“时序问题”，是在轻视读者。

倾向于使用主动语态、明确的主语和简短的段落。“我们发现了这个 bug。Alex 写好了修复方案。PR 已提交，等待评审。”胜过“根本原因已确定，修复方案也已编写并提交评审。”

避免：

• 并非真正谨慎的模糊措辞（“我们认为”“似乎”“可能”）。明确表述，或者不表述。
• 为求面面俱到而重复显而易见的信息（“这个 bug 出在 Tada，而 Tada 用于 GPU 通信；GPU 通信对分布式训练很重要，所以……”）。
• 指导领导层如何履行职责（“你们应该优先处理”“这必须在 X 之前合入”）。提供事实，由他们决定。
• 工程流程的琐碎细节：二分排查、调试迭代、GDB 会话。他们关心的是你找到了问题，而不是你如何找到的。（例外：当过程本身就是重点时——“我们花了三周才意识到二分排查结果有误导性”——可以用一句话总结经验，不要逐步叙述。）

渠道形式

内容相同，呈现形式不同。选择与发布渠道相匹配的形式。

JIRA 评论 / 书面状态报告

完整的结构化内容。加粗的分节标签。便于在工单页面快速浏览。

构建模块（按需选用）：

• 状态 / TL;DR。 一行加粗文字。读者看到这里就能了解正确答案。"已修复，等待合并。" / "根因未知——正在调查。" / "受供应商阻碍。" / "7.2 中出现客户可见的回归问题；正在回滚。
• 影响。 受影响对象、影响程度以及他们看到的现象。使用客户 / 工作负载 / 产品术语，而不是测试套件术语。"Llama-2-70B 微调在每个 eval 步骤都会卡住" > "测试失败。"
• 故障原因。 简短段落。用通俗语言描述故障机制，以及一层原因，不要使用代码标识符。
• 为何现在出现 / 为何未能及时发现。 可选。如果领导层无论如何都会问到，就写上：潜在回归、CI 缺口、此前未完成的修复、冻结期间合入的变更。
• 负责人。 人员 + 团队 + 对应的 PR / 分支 / JIRA 内容。放一个链接，不要放五个。
• 后续步骤。 具体、近期、有序。"代码审查 → 合并 → 回移植到 7.2。"
• 解决方法 / 缓解措施。 如果客户现在正遇到问题，他们今天可以怎么做？用一句话说明。
• 风险。 可选。只写真正的风险——*"修复会触及热路径；完成基准测试前可能出现性能回归。"*不要为了显得周全而编造风险。

根据当前事项的重要程度排序。

Slack — 频道消息或私信

一条消息，不要写成大段文字。醒目的加粗分节标签会让人觉得“我从 JIRA 逃出来了”——不要这样写。

• 第一行写一条加粗的 TL;DR。
• 下方写 2–4 条简短要点：影响、负责人 + 链接、后续步骤。删去不适用的部分。
• 一个链接，内嵌在文字中（JIRA-12345 / PR #5751）。不要堆砌链接。
• 不要问候，也不要署名。频道本身就是上下文。
• 如果是线程回复而不是新消息，就省略 TL;DR，直接给出答案。

长度目标：顶层消息少于约 80 个词；线程回复少于约 40 个词。

异步站会记录

读者会在 30 秒内浏览 10 条记录。把动词放在最前面。

• 1–3 行，最多。
• 格式："<state> <thing>。<owner if not me>。<next>。"
• 示例：
  • "已修复影响 dumbModel 运行的 Tada 卡顿问题（JIRA-12345）。PR #5751 正在审查。接下来回移植到 v7.2。"
  • "仍在追查 LLM-7B eval 步骤卡顿问题。现在已能稳定复现；正在二分排查。暂时没有预计完成时间。"
• 不要用项目符号，也不要加粗标签。格式本身就是句子。

电子邮件 — 内部高管 / 跨团队

主题行的价值占了一半。

• **主题：**将 TL;DR 改写为名词短语。"dumbModel 中的 Tada 卡顿：修复正在审查（JIRA-12345）。"
• **称呼：**与收件人的语气保持一致（Hi Sam, / Hi all,）。
• **正文：**采用 JIRA 评论的结构，但改为流畅的段落，段落之间空一行，不用加粗的分节标签。两三段足矣。
• 结尾写上需要收件人关注的下一个决策点（如有）。如果没有，简单写上 "— [Name]" 即可。

会议发言要点

你要说出来，而不是展示出来。

• 使用项目符号列表，每条最多一个简短分句。
• 按发言顺序排列。
• 把想要口头提及的数字 / 标识放在要点中，避免临场忘词。
• 不要写散文。"dumbModel 的 LLM-7B 微调一直卡住。" / "根因：Tada 快速路径中跳过了同步。" / "Alex 的修复正在审查，PR #5751。" / "合入后回移植到 v7.2。"

源材料

输入内容为以下之一：

1. JIRA 票据键（例如 JIRA-12345）→ 通过 GET /rest/api/3/issue/<KEY>?fields=summary,status,priority,assignee,comment 获取，并附上实例用于技术评估的任何自定义字段——通常这是获取当前状态最简洁的来源。应重新表述最新的实质性评论；不要倾倒整个讨论串。
2. 粘贴的技术文本 → 直接使用。
3. 当前对话 → 如果你（或用户）刚刚提供了工程内容，而用户现在说 “现在发到 slack” / “现在给 VP 看，”，则重用上下文中的内容。

如果来源不明确，只问一个问题，然后停止。

输出流程

1. 确认发布渠道（如果未说明）。
2. 生成草稿，作为单个聊天区块，并按该渠道的呈现方式进行格式化。
3. 询问发布位置：
   • 默认：仅输出——由用户复制。
   • 回帖到 JIRA：仅当用户明确提出时才可以。显示确切的 ADF payload，等待用户明确回复 “发布” / “继续” / “是，”，然后执行 POST /rest/api/3/issue/<KEY>/comment。
   • 绝不通过此技能发布到 Slack、电子邮件或任何非 JIRA 渠道。 将草稿交给用户，由用户发布。
4. 通常迭代一次；三次就值得警惕。 如果用户进行第三次修改，应询问缺少了什么具体的表述方式／受众假设；不要盲目地继续调整。

示例——同一错误，不同渠道的三种写法

来源（工程 JIRA 评论）：

机制： tadaLaunchPrepare / tadaLaunchKernel / tadaLaunchFinish 中的单流快速路径（由 scheduler->numStreams == 1 && !plan->persistent 控制）跳过了 launchStream 与 handle->shared->deviceStream 之间的跨流事件。dumbModel 恰好会触发这个条件。内核在 deviceStream 的 IPC 发布／暂存缓冲区写入（用于填充 scratchBuf）对 launchStream 可见之前就启动了 → 内核中的 scratchBuf == NULL → 意外的指针解引用 → 从垃圾数据中读取环形缓冲区就绪标志 → 线程永远循环等待。

作为 JIRA 评论

状态：已修复，待合并。 已发现错误，修复已验证，PR 正在评审。

影响： 在 8 张 GPU 上对 LLM-7B 进行微调时，每次尝试评估模型都会挂起，导致整个工作负载受阻。影响使用 dumbModel 的客户（这是一个用于训练无法放入单张 GPU 的大模型的热门框架），也就是说，平台上大多数大模型微调任务都可能受到影响。

故障原因： 我们的 GPU 通信库 Tada 在特定配置下跳过了内部同步步骤，而 dumbModel 恰好会触发该配置。GPU 最终读取了未初始化的缓冲区，并卡在等待一个永远不会到来的信号上。这个不安全的捷径已存在于代码中数月，但直到现在才被实际工作负载触发。

先前的修复尝试增加了一项防御性检查，在某些路径中掩盖了症状，却没有消除底层竞争条件。这个新修复彻底移除了不安全的捷径，并加强了设备端的安全检查。

负责人： Alex（Tada 团队）。PR org/platform#5751。

后续步骤： 代码评审 → 合并。当前遇到此问题的客户可以禁用 IPC 注册，作为临时解决方法。

作为 Slack 帖子

影响 dumbModel LLM-7B 微调的 Tada 挂起问题已修复，待合并。（JIRA-12345）

• 通信快速路径跳过同步 → GPU 读取未初始化的内存 → 挂起。该问题潜伏了数月；dumbModel 是首个触发它的工作负载。
• 负责人：Alex，PR #5751 正在评审。
• 合并前的临时解决方法：禁用 IPC 注册。

作为站会记录

修复了 dumbModel LLM-7B 上的 Tada 卡死问题（JIRA-12345）。Alex 的 PR #5751 正在审核。已在工单中发布解决方法；下一步是回移植到 v7.2。

不同渠道之间的变化：诊断结果、负责人和下一步都相同。JIRA 会记录所有信息。Slack 会省略“为何现在处理”和“之前尝试过的修复”——对该渠道来说太多了。站会记录只保留状态 + 关键编号 + 负责人 + 下一步。其中没有任何一条提到 scratchBuf 或 tadaLaunchPrepare。

规则

• 绝不编造事实，让改写显得更简洁。如果工程资料写着“根本原因未知”，改写就必须写“根本原因未知”——不要为了叙述简洁，把推测说成结论。
• 绝不在去行话时删掉 JIRA 编号、PR 编号或客户／工作负载名称。它们是交叉引用的桥梁，删掉会导致追踪中断。
• **绝不编造负责人。**如果来源未注明负责人，请询问用户——不要根据 git blame 或近期提交来猜测。
• **在发布到 JIRA 前先获得确认。**沿用 jira-check 的审批流程。仅输出文本则无需审批。
• **绝不通过此技能向 Slack、电子邮件或任何非 JIRA 渠道发布内容。**将草稿交给用户，由用户发布。
• **避免表达立场。**此技能用于生成状态更新，而非提出建议。如果用户需要建议备忘录，请先确认再改写。