pr-description-writer

PR 描述编写技能

此技能用于生成清晰、结构化、可用于生产环境的 Markdown 格式 Pull Request 描述。

用户会提供 PR 的相关背景（更改、Bug、功能、架构等）。此技能会判断或询问 PR 类型，并生成正确的模板。

---

主动检测 PR

在生成任何内容之前，务必使用 gh CLI 检查当前分支是否已存在未关闭的 Pull Request：

gh pr view --json number,title,url,body 2>/dev/null

• 如果找到 PR，记录其编号、当前标题、URL 和正文。告知用户检测到了未关闭的 PR，并显示 PR URL。
• 如果未找到 PR（命令以非零状态退出），跳过此步骤并照常继续。

此检测会自动执行——不要询问用户是否要检查。务必进行检查。

---

PR 类型

支持的类型：

• issue
• feature
• big-feature

如果用户未指定类型，请让他们选择一种。

---

通用写作规则

• 使用英文撰写。
• 简洁且突出关键信息。
• 避免空泛的填充文字。
• 关注原因和影响，而不只是更改内容。
• 使用清晰、专业的技术写作风格。
• 优先采用清晰的技术说明，而非营销语言。

---

PR 标题规则

此技能必须始终先生成 PR 标题，再生成描述。

规则：

• 简洁且具有描述性
• 体现意图和影响（而不只是更改内容）
• 尽可能采用常见的 PR 格式

示例：

• fix(auth): prevent session reset on refresh
• feat(payments): add MercadoPago checkout support
• refactor(ui): migrate layout system to grid tokens

---

输出模式

此技能仅生成 Markdown 输出。

始终：

• 生成 PR 标题
• 生成 PR 描述
• 将所有内容格式化为 Markdown
• 确保内容可直接手动复制并粘贴到 GitHub

---

最终输出格式

# <PR Title>

<PR Description using the selected template>

---

Linear 问题 / 问题链接

始终询问是否存在相关问题（Linear、Jira、GitHub Issues 或类似平台）。

如果存在问题，在 PR 描述顶部添加此部分：

## Issue

[Issue link here]

如果不存在问题，则省略此部分。

---

模板 --- 问题

适用于：

• Bug
• 修复
• 回归问题
• 性能问题
• 技术修正

## Problem

<Explain the bug or problem clearly. What was happening? When did it occur?>

## Root Cause

<Explain the technical cause if known.>

## Solution

<Explain what was changed and why it fixes the problem.>

## Result

<Explain impact. Add demo links, videos, screenshots if available.>

---

模板 --- 功能（小型 / 中型）

适用于：

• 常规功能
• 改进
• 小型 UX 补充
• 非架构性更改

## Problem

<Explain the need, limitation, or missing capability.>

## Root Cause

<Optional. Only include if there was a technical limitation to solve.>

## Result

<Explain what the new feature enables and its impact.>

规则：

• 功能类 PR 不要包含 Solution 部分。
• Root Cause 为可选项。

---

模板 --- 大型功能

适用于：

• 新系统
• 架构更改
• 重大 UX 工作流
• 新平台功能
• 大规模重构

### Summary

<High level explanation of what this PR introduces and why it matters.>

### Key Changes

- <Main change>
- <Main change>
- <Main change>

---

## Architecture Overview

### 1. Concept / Strategy

<Explain main architectural idea>

### 2. Implementation

<Folders, routing, state, patterns, infra, etc>

### 3. Components / Systems

<Main modules or domains involved>

### 4. Data / State Flow

<How data moves through the system>

### 5. Navigation / UX Flow

<If applicable>

### 6. Migration / Breaking Changes

<If applicable>

---

### Notes

<Tradeoffs, future improvements, known limitations>

---

输出交付方式

生成 PR 标题和 PR 描述后，此技能必须询问用户希望如何接收输出。

如果检测到当前分支存在未关闭的 PR，请提供以下选项：

“要我直接更新未关闭的 PR、生成 .md 文件，还是直接在此处显示？”

选项：

• 更新未关闭的 PR（检测到 PR 时推荐）——使用 gh pr edit 直接在 GitHub 上更新标题和正文。
• 在聊天中显示
• 生成 .md 文件

如果未检测到未关闭的 PR，请提供标准选项：

“要我生成包含这些内容的 .md 文件，还是直接在此处显示？”

选项：

• 在聊天中显示（默认）
• 生成 .md 文件

---

更新未关闭的 PR

用户确认要更新未关闭的 PR 后，使用 gh CLI：

gh pr edit <number> --title "<new title>" --body "<new body>"

规则：

• 未经用户明确确认，绝不要更新 PR。 务必先使用 AskUserQuestion 询问。
• <number> 使用“主动检测 PR”步骤中检测到的 PR 编号。
• <new title> 使用生成的 PR 标题。
• <new body> 使用生成的 PR 描述正文（Markdown）。通过 heredoc 传递，以保留格式：

gh pr edit <number> --title "<new title>" --body "$(cat <<'EOF'
<generated PR description body>
EOF
)"

• 更新成功后，告知用户并显示 PR URL。
• 如果更新失败，显示错误，并改为在聊天中显示输出，以便用户手动复制并粘贴。

---

Markdown 文件规则

如果用户请求 .md 文件：

• 文件必须包含：
  • PR 标题，作为 H1
  • PR 描述正文
• Markdown 之外不得包含额外文本
• 文件必须可直接上传或提交

---

行为规则

运行此技能时：

1. 主动使用 gh pr view 检查当前分支上是否存在未关闭的 PR。 此操作会自动执行，不要询问用户是否检查。如果找到 PR，请告知用户（显示 PR URL 和编号）。

2. 根据上下文判断 PR 类型，或请用户选择：

   • issue
   • feature
   • big-feature

3. 始终询问是否有相关 issue 链接。

4. 如果存在 issue，请在顶部添加 Issue 部分。

5. 生成：

   • PR 标题
   • PR 描述（Markdown 正文）

6. 询问用户希望如何交付输出：

   • 如果检测到未关闭的 PR：提供直接更新 PR、在聊天中显示或生成 .md 文件的选项。使用 AskUserQuestion 进行确认。
   • 如果没有未关闭的 PR：提供在聊天中显示或生成 .md 文件的选项。

7. 如果用户选择更新未关闭的 PR，请使用生成的标题和正文运行 gh pr edit。未经确认，绝不得运行此命令。

8. 如果用户请求 .md 文件，请生成可直接使用的 Markdown 内容。

---

质量要求

生成的 PR 描述必须：

• 可直接复制粘贴到 GitHub PR
• 技术准确
• 易于浏览
• 对评审者和未来的维护者有帮助