visual-pr

描述 Pull Request

为当前任务创建或更新 Pull Request，并用简洁的描述帮助审阅者了解变更的原因和实现方式。

工作流

1. 阅读描述模板：

   Read({SKILLBASE}/references/pr_description_template.md)

2. 查找或创建 Pull Request：

   • 使用 gh pr view --json url,number,title,state,baseRefName,headRefName 2>/dev/null 检查当前分支是否已有 PR。
   • 如果没有 PR，检查 git status --short --branch 和当前分支上的提交。
   • 必要时提交与任务相关的变更，为分支设置上游并推送，然后为其创建 PR。遵循仓库的 Git 安全协议。
   • 仅当当前分支没有相关工作，且无法安全地在当前分支创建 PR 时，才请用户选择 PR。

3. 收集解释变更所需的上下文：

   • 阅读工单和相关任务文件。
   • 阅读完整的 PR 差异，以及足够的周边代码，以了解行为和职责归属。
   • 使用 gh pr view 收集 PR 元数据和变更文件。
   • 阅读 {SKILLBASE}/references/show-me.md，了解 PR 正文中使用的可视化大纲规范。

4. 使用模板撰写 PR 描述：

   • 变更原因必须严格为一句话。
   • 特别注意事项写 1-3 条要点。优先说明审阅者需留意的警告、迁移、兼容性限制、有意未实现的内容或出乎意料的决策。若没有特别注意事项，写 - None.。
   • 变更大纲应是简洁、受 /show-me 启发的结构化视图，而非叙述性文字或逐文件变更日志。
   • 仅包含有助于解释此 PR 的视图：
     • SQL 表和端点契约变更，以及业务逻辑伪代码。
     • 关键数据结构／类型变更。
     • 展示变更职责的浅层文件树。
     • React 组件树变更，包括重要的钩子、状态和包边界。
     • 调用树、调用栈、控制流或数据流变更。
   • 展示现有结构的变更时，优先使用 diff 代码块。如果大部分内容是新增的，或差异标记会模糊职责归属或顺序，则展示完整的目标结构。
   • 每个视图都应聚焦于审阅者需要了解的内容。省略未发生变更的类别。
   • 可选：如果知道工单 ID／URL、humanlayer 任务 URL、相关计划／文档 URL 或其他相关链接，可将其加入标题；否则省略标题。

5. 保存并发布描述：

   • 如果任务目录存在，使用 .humanlayer/tasks/{task-slug}/pr-description.md；否则使用 .humanlayer/tasks/pr-{number}/description.md。
   • 使用 gh pr edit {number} --body-file {output-path} 更新 PR。
   • 确认更新成功。

6. 报告完成情况：

   • 阅读 {SKILLBASE}/references/describe_pr_final_answer.md。
   • 使用该最终回复模板，提供 PR URL、已保存描述的 URL，以及简洁的变更文件列表。

务必阅读并遵循 {SKILLBASE}/references/pr_description_template.md。PR 正文不得超出该模板的范围。

用一个人对另一个人说话的方式写作：避免行话和俚语，语言简单、连贯、简洁。