Back to Details

visual-pr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Describe a Pull Request

描述 Pull Request

Create or update the pull request for the current task with a concise description that helps a reviewer understand why the change exists and the shape of the implementation.
为当前任务创建或更新 Pull Request，并使用简洁的描述帮助审查者了解变更存在的原因以及实现的整体结构。

Workflow

工作流程

  1. Read the description template:
    Read({SKILLBASE}/references/pr_description_template.md)
  2. Identify or create the pull request:
    • Check the current branch for a PR with 
      gh pr view --json url,number,title,state,baseRefName,headRefName 2>/dev/null
      .
    • If no PR exists, inspect 
      git status --short --branch
      and the commits on the current branch.
    • Commit task-related changes when needed, push the branch with an upstream, and create a PR for it. Follow the repository's git safety protocol.
    • Ask the user to select a PR only when the current branch has no relevant work and there is no safe current-branch PR to create.
  3. Gather only the context needed to explain the change:
    • Read the ticket and any relevant task artifacts.
    • Read the complete PR diff and enough surrounding code to understand behavior and ownership.
    • Use 
      gh pr view
      to collect PR metadata and changed files.
    • Read 
      {SKILLBASE}/references/show-me.md
      for the visual-outline conventions used in the PR body.
  4. Write the PR description using the template:
    • Keep Why the change to exactly one sentence.
    • Keep Special things to note to 1-3 bullets. Prioritize reviewer warnings, migrations, compatibility constraints, deliberate omissions, or surprising decisions. Write 
      - None.
      when there are no special considerations.
    • Make Change outline a compact, 
      /show-me
      -inspired structural view rather than prose or a file-by-file changelog.
    • Include only the views that help explain this PR:
      • SQL table and endpoint contract changes, plus pseudocode for business logic.
      • key data structure / type changes
      • A shallow file tree showing changed responsibilities.
      • React component tree changes, including important hooks, state, and package boundaries.
      • Call-tree, call-stack, control-flow, or data-flow changes.
    • Prefer 
      diff
      blocks when showing changes to an existing shape. Show the complete target shape when most of it is new or diff notation would obscure ownership or order.
    • Keep each view focused on what a reviewer needs. Omit categories that did not change.
    • optionaL: if you are aware of a ticket id/url, a humanlayer task url, or related plan/document urls, or other relevant links, include them in the header, otherwise omit the header
  5. Save and publish the description:
    • Use 
      .humanlayer/tasks/{task-slug}/pr-description.md
      when the task directory exists; otherwise use 
      .humanlayer/tasks/pr-{number}/description.md
      .
    • Update the PR with 
      gh pr edit {number} --body-file {output-path}
      .
    • Confirm the update succeeded.
  6. Report completion:
    • Read 
      {SKILLBASE}/references/describe_pr_final_answer.md
      .
    • Respond using that final answer template with the PR URL, saved description URL, and concise list of changed files.
Always read and follow 
{SKILLBASE}/references/pr_description_template.md
. Do not expand the PR body beyond that template.
Write as one human talking to another: avoid jargon and slang, and use simple, coherent, concise language.
  1. 读取描述模板：
    Read({SKILLBASE}/references/pr_description_template.md)
  2. 识别或创建 Pull Request：
    • 检查当前分支是否已有 PR：
      gh pr view --json url,number,title,state,baseRefName,headRefName 2>/dev/null
      。
    • 如果没有 PR，检查 
      git status --short --branch
      以及当前分支上的 commits。
    • 根据需要提交与任务相关的变更，将分支推送到其 upstream，并为其创建 PR。遵循仓库的 git 安全协议。
    • 仅当当前分支没有相关工作，且无法安全地基于当前分支创建 PR 时，才请用户选择 PR。
  3. 仅收集解释变更所需的上下文：
    • 读取 ticket 和相关的任务产物。
    • 读取完整的 PR diff，以及足以理解行为和归属的周边代码。
    • 使用 
      gh pr view
      收集 PR 元数据和变更文件。
    • 读取 
      {SKILLBASE}/references/show-me.md
      ，了解 PR 正文中使用的可视化大纲约定。
  4. 使用模板编写 PR 描述：
    • 将 Why the change 保持为恰好一句话。
    • 将 Special things to note 保持为 1-3 个要点。优先说明需要审查者注意的事项、迁移、兼容性限制、有意省略的内容或出人意料的决策。没有需要特别说明的事项时，写入 
      - None.
      。
    • 将 Change outline 写成紧凑的、受 
      /show-me
      启发的结构化视图，而不是叙述性文字或逐文件更新的日志。
    • 仅包含有助于解释此 PR 的视图：
      • SQL 表和 endpoint 契约变更，以及业务逻辑的 pseudocode。
      • 关键 data structure / type 变更。
      • 展示变更职责的浅层 file tree。
      • React component tree 变更，包括重要的 hooks、state 和 package 边界。
      • Call-tree、call-stack、control-flow 或 data-flow 变更。
    • 当现有结构发生变化时，优先使用 
      diff
      block 展示变更。当大部分内容为全新内容，或 diff 表示法会掩盖所有权或顺序时，展示完整的目标结构。
    • 每个视图都应聚焦于审查者需要的信息。省略未发生变化的类别。
    • 可选：如果已知 ticket id/url、humanlayer task url、相关计划或文档 URL，或其他相关链接，则将其包含在 header 中；否则省略 header。
  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 正文。
像人与人交流一样写作：避免行话和俚语，使用简单、连贯、简洁的语言。