create-issues-update-pr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create GitHub issues from a PR's work, and update the PR

根据 PR 的工作创建 GitHub issue,并更新 PR

Takes work that's already happened on a branch (or that the user is about to describe) and turns it into GitHub issues — one flat issue for a single atomic change, or a parent epic plus child issues when the work genuinely splits into distinct pieces — then rewrites the pull request's title and description so the description carries an itemized, correctly nested list of every issue it's tracked by.
The two halves of this (creating issues, updating the PR) are meant to happen together: an issue list in a PR description is only useful if the numbers in it are real and current, and issues filed for a PR are only useful if the PR actually points back at them.
将分支上已经完成的工作(或用户即将描述的工作)转换为 GitHub issues:对于单个原子变更,创建一个扁平 issue;当工作确实可拆分为不同部分时,创建一个父级 epic issue 以及每个部分对应的子 issue;然后重写 pull request 的标题和描述,使描述带有一份逐项列出且嵌套正确的 issue 清单。
这两个部分(创建 issues 与更新 PR)应当协同执行:只有清单中的编号真实且最新,PR 描述中的 issue 列表才有意义;而为 PR 创建的 issue,也只有 PR 确实反向链接到它们时才有用。

Workflow

工作流

  1. Establish what work you're filing issues for. If a PR number is given or obvious from context (the current branch's open PR), read it —
    pull_request_read
    method
    get
    for its title/body/branches, and either
    get_commits
    or a local
    git log
    /
    git diff
    against the base branch for what actually changed. Ground every issue in real, verifiable work: a commit, a diff, a file. If the user is describing work that isn't reflected in commits yet, that's fine to file too, but say so explicitly rather than presenting it as already-done. If there's no PR yet and no clear scope, ask rather than guessing at what to track.
  2. Decide the shape: one issue, or a parent epic with children?
    • A single, atomic, well-scoped change — one commit's worth, one coherent piece of work — gets one issue. Don't manufacture an epic-of-one just to have a hierarchy.
    • Multiple genuinely distinct pieces of work serving one umbrella goal (typically: several commits, each a self-contained step) get a parent epic issue plus one child per piece, linked through GitHub's actual parent/child issue relationship — not just shared labels or a checklist with no real links behind it.
    • A reliable way to find the right split: look at the commit history for the branch/PR. One child issue per tightly-scoped commit (or small cluster of commits that are really one step) tends to produce issues that are each individually closeable and meaningful — check this shape before inventing your own grouping from scratch.
    • "Group where applicable" cuts both ways: don't force unrelated work under one parent, and don't flatten obviously related, multi-step work into a flat pile of ungrouped issues either.
  3. Check issue-type support before creating anything. Call
    list_issue_types
    for the owner/repo. If the repository defines types (commonly something like Feature/Bug/Task), pick the closest fit for each issue you create and pass it. If the repository has no issue types configured, omit the
    type
    field entirely rather than guessing at a value that doesn't exist there.
  4. Search before creating, to avoid duplicates. Use
    search_issues
    (or
    list_issues
    for a small repo) for anything already covering the same work — a stale or half-finished issue from earlier is worth linking to and updating rather than duplicating. Only skip this check if the user has made clear these are definitely new.
  5. Create the issues, parent first.
    • Parent (if any):
      issue_write
      method
      create
      , with a body naming the PR it's tracked in and a short description of the overall goal. A plain-text checklist of the sub-pieces is fine here even before the children exist — you can go back and turn it into real
      #
      -linked bullets once the children have numbers, but that's a nice-to-have, not required.
    • Children:
      issue_write
      method
      create
      with
      parent_issue_number
      set to the parent's number — this attaches the child to the parent in the same call; no separate linking step needed. (
      sub_issue_write
      is for re-parenting an issue that already exists — you don't need it for issues you're creating fresh in this workflow.)
    • Give each issue a real, specific body: what changed, which files or areas, and why — pulled from the actual commit message or diff for that piece of work, not written generically from the title alone.
    • Create children in the same order the corresponding commits landed, so the issue numbers read in a sensible sequence.
  6. Update the PR — title and body, in one call.
    • Title: short. When a parent epic exists, matching its title verbatim keeps the PR and its tracking issue recognizable as the same piece of work at a glance — an epic title that was itself kept short is usually reusable as-is. Otherwise, write a short, accurate title for the single issue's scope. Aim well under 70 characters.
    • Body: the default shape, whenever this skill is writing or rewriting a body from scratch, is three parts in this order:
      • A short Summary (1-2 sentences): what the PR fixes or adds, in plain terms — the kind of sentence someone skimming a PR list needs, not the mechanism.
      • A Details section: the fuller explanation — root cause (for a fix), the approach taken, what actually changed, and how it was verified — pulled from the real commits/diff for this PR, not written generically from the title alone.
      • An Issues section listing every issue created, one per line, in exactly this format:
        - Closes #{{issue-number}} -- {{issue-title}}
        The
        Closes
        keyword is deliberate, on every line including a parent epic's — GitHub auto-closes any issue referenced this way when the PR merges into the repo's default branch, so the list doubles as the mechanism that closes the issues, not just a description of them. Indent each level of child under its parent by two spaces — GitHub renders two-space-indented bullets as a nested list. A flat set of issues with no parent is just one un-indented list.
      This Summary/Details/Issues shape is the default, not a rigid template to impose everywhere: if the PR already has its own established, still-accurate structure (a repo convention like Summary/Key changes/Test plan, or anything else genuinely reflecting the PR's current state), preserve that structure and just add or refresh the Issues section within it, additively, rather than forcing the Summary/Details split on top of a body that already works. The one case that calls for a full rewrite either way: if the existing description is generic boilerplate that no longer reflects the PR's actual current state (common after several rounds of commits since it was first written) — then rewriting the whole body (into the default Summary/Details/ Issues shape, absent some other convention to follow) is the right call — just say that's what you're doing rather than silently overwriting something that looked deliberate.
    • Use
      update_pull_request
      with both
      title
      and
      body
      set in the same call.
  7. Verify — don't trust the write call's echo. After creating the issues and updating the PR, read them back:
    pull_request_read
    method
    get
    on the PR to confirm the title and body actually saved as given (GitHub's write endpoints occasionally normalize or truncate content silently), and spot-check the created issues if there's any doubt about the parent/child structure actually taking. Only report the work as done once you've confirmed it from a fresh read, not from memory of what you sent.
  1. 确定要为哪些工作创建 issue。 如果给出了 PR 编号,或者从上下文(当前分支的开放 PR)可以明显得知 PR 编号,就读取它——通过
    pull_request_read
    方法
    get
    获取其标题、正文和分支,并通过
    get_commits
    或本地
    git log
    /
    git diff
    对比 base branch,以确定实际改动内容。让每个 issue 都建立在真实、可验证的工作之上:一次 commit、一处 diff 或一个文件。如果用户描述的工作尚未体现在 commits 中,也仍然可以为其创建 issue,但必须明确说明这一点,而不能将其呈现为已经完成。如果尚无 PR 且范围也不明确,应先询问用户,而不是猜测要跟踪的内容。
  2. 确定结构:一个 issue,还是父级 epic 加子 issue?
    • 单一、原子化且范围清晰的变更——相当于一次 commit 的工作量,或一项连贯的工作——应使用 一个 issue。不要为了制造层级关系而硬造一个只有一个 issue 的 epic。
    • 多项确实彼此独立、但服务于同一总体目标的工作(通常是多个 commit,且每个 commit 都是一个自成体系的步骤),应使用 父级 epic issue,并为每个部分创建一个子 issue,通过 GitHub 真正的父/子 issue 关系关联——而不是只共享标签,或使用一个没有真实链接的 checklist。
    • 确定合理拆分方式的可靠方法:查看 branch/PR 的 commit history。通常每个范围紧凑的 commit(或者确实属于同一步骤的一小簇 commit)对应一个子 issue,这样每个 issue 都能单独关闭且有明确意义——在从头自行设计分组之前,先检查是否已有这种结构。
    • “适用时分组”同时包含两层含义:不要把不相关的工作强行归到一个父级下,也不要把明显相关、包含多个步骤的工作压平成一组没有分组的 issue。
  3. 创建任何内容前,检查 issue type 支持情况。 为目标 owner/repo 调用
    list_issue_types
    。如果仓库定义了 types(通常是 Feature/Bug/Task 之类),为每个待创建的 issue 选择最匹配的类型并传入。如果仓库未配置 issue types,则完全省略
    type
    字段,不要猜测一个不存在的值。
  4. 创建前先搜索,避免重复。 使用
    search_issues
    (或对于小型仓库使用
    list_issues
    )查找是否已有 issue 覆盖相同工作——早期留下但已过时或只完成一半的 issue,值得链接并更新,而不是重复创建。只有当用户明确表示这些肯定是全新工作时,才可以跳过此检查。
  5. 先创建父 issue,再创建子 issue。
    • 父 issue(如有):使用
      issue_write
      方法
      create
      ,正文应写明它所跟踪的 PR,并简要描述总体目标。即使子 issue 尚不存在,也可以先在父 issue 正文中使用纯文本 checklist 列出各个子部分——待子 issue 获得编号后,可以再回来将其改成真正带有
      #
      链接的项目符号,不过这只是锦上添花,并非必需。
    • 子 issue:使用
      issue_write
      方法
      create
      ,并设置
      parent_issue_number
      为父 issue 的编号——这样会在同一次调用中将子 issue 关联到父 issue,无需单独的链接步骤。(
      sub_issue_write
      用于为已经存在的 issue 重新设置父级;在此工作流中创建全新 issue 时不需要使用它。)
    • 为每个 issue 提供真实、具体的正文:改了什么、涉及哪些文件或区域,以及为什么改——这些内容应取自该部分工作对应的实际 commit message 或 diff,而不能仅根据标题泛泛而谈。
    • 按照对应 commits 落地的顺序创建子 issue,使 issue 编号读起来顺序合理。
  6. 一次调用中同时更新 PR 的标题和正文。
    • 标题:保持简短。当存在父级 epic 时,逐字沿用其标题可以让 PR 和跟踪 issue 让人一眼看出是同一项工作;一个本身足够简短的 epic 标题通常可以直接复用。否则,为单个 issue 的范围编写一个简短、准确的标题。尽量控制在 70 个字符以内。
    • 正文:当此 skill 从头编写或重写正文时,默认结构按以下顺序包含三个部分:
      • 简短的 摘要(Summary)(1-2 句话):用通俗语言说明 PR 修复或新增了什么——应是浏览 PR 列表的人一眼能理解的信息,而不是实现机制。
      • 详情(Details) 部分:更完整的说明——对于修复,说明 root cause;对于整体工作,说明采用的方法、实际改动内容,以及验证方式——所有内容都应来自该 PR 的真实 commits/diff,而不能仅根据标题泛泛而谈。
      • Issues 部分:每行列出一个已创建的 issue,严格使用以下格式:
        - Closes #{{issue-number}} -- {{issue-title}}
        这里使用
        Closes
        是有意为之,包括父级 epic 的每一行——当 PR 合并到仓库的默认分支时,GitHub 会自动关闭所有以这种方式引用的 issue,因此该列表不仅用于描述 issue,同时也充当关闭 issue 的机制。将每一层子 issue 在其父 issue 下缩进两个空格——GitHub 会把缩进两个空格的项目符号渲染为嵌套列表。如果没有父 issue 且 issue 集合是扁平的,则只需使用一个不缩进的列表。
      这个 Summary/Details/Issues 结构是默认方案,而不是必须到处套用的僵化模板:如果 PR 已有自己的既定结构且仍然准确(例如仓库约定的 Summary/Key changes/Test plan,或其他确实反映 PR 当前状态的格式),则保留该结构,只在其中增量添加或刷新 Issues 部分,而不要强行在其上再套用 Summary/Details 结构。唯一无论如何都应完整重写的情况是:现有描述只是通用样板,且已不再反映 PR 的实际当前状态(在最初编写后经历多轮 commits 时很常见)——此时应将整个正文重写为默认的 Summary/Details/Issues 结构(除非有其他应遵循的约定)——但要明确说明正在这样做,而不是默默覆盖一段看起来是刻意编写的正文。
    • 使用
      update_pull_request
      ,在同一次调用中同时设置
      title
      和
      body
      。
  7. 验证——不要相信写入调用返回的回显。 创建 issues 并更新 PR 后,将它们重新读取:对 PR 调用
    pull_request_read
    方法
    get
    ,确认标题和正文确实按提交内容保存(GitHub 的写入接口偶尔会在无提示的情况下规范化或截断内容);如果对父/子结构是否真正生效有任何疑虑,也应抽查已创建的 issues。只有通过重新读取确认后,才能报告工作已完成,而不是仅凭记忆中发送过的内容。

Format reference

格式参考

The default full body shape — Summary, then Details, then the Issues list (see workflow step 6):
undefined
默认完整正文结构——先 Summary,后 Details,再 Issues 列表(参见工作流第 6 步):
undefined

Summary

Summary

Fixes a sidebar bug where a row's reading-time estimate with more digits than the rest threw its part-number index out of column with every other row.
Fixes a sidebar bug where a row's reading-time estimate with more digits than the rest threw its part-number index out of column with every other row.

Details

Details

.n-meta
's auto-sized width let a wider time value shift that row's whole trailing block, including the index digits, independently of every other row. Fixed by giving the time value a fixed, right-aligned width instead of letting it size itself. Verified with new tests and by regenerating the two affected real editions.
.n-meta
's auto-sized width let a wider time value shift that row's whole trailing block, including the index digits, independently of every other row. Fixed by giving the time value a fixed, right-aligned width instead of letting it size itself. Verified with new tests and by regenerating the two affected real editions.

Issues

Issues

  • Closes #76 -- Fix sidebar reading-time column misalignment
    • Closes #77 -- Derive sidebar time-column width from reading_times.total
    • Closes #78 -- Update scrolls memory for sidebar alignment fix

The rest of these examples show just the `## Issues` fragment itself —
the part whose exact list/nesting format matters regardless of what
Summary/Details (or a repo's own alternate sections) look like above
it.

With a parent epic:
  • Closes #76 -- Fix sidebar reading-time column misalignment
    • Closes #77 -- Derive sidebar time-column width from reading_times.total
    • Closes #78 -- Update scrolls memory for sidebar alignment fix

以下其余示例只展示 `## Issues` 片段本身——无论上方的 Summary/Details(或仓库自己的替代章节)采用什么格式,真正需要严格遵循的都是这一部分所对应的列表/嵌套格式。

有父级 epic 时:

Issues

Issues

  • Closes #50 -- Add Stata skill (stata-recipes)
    • Closes #51 -- Create the initial stata-recipes skill
    • Closes #52 -- Expand stata-recipes: time-series/panel regression, unit-root tests
    • Closes #53 -- Restructure stata-recipes recipes into models/ and tests/ subfolders

Flat, no parent:
  • Closes #50 -- Add Stata skill (stata-recipes)
    • Closes #51 -- Create the initial stata-recipes skill
    • Closes #52 -- Expand stata-recipes: time-series/panel regression, unit-root tests
    • Closes #53 -- Restructure stata-recipes recipes into models/ and tests/ subfolders

扁平结构,无父 issue:

Issues

Issues

  • Closes #61 -- Fix broken link in README

Two levels of nesting (a parent whose children each have their own
children) follows the same two-spaces-per-level rule:
  • Closes #61 -- Fix broken link in README

两层嵌套(一个父 issue,其子 issue 各自还有子 issue)遵循同样的每层缩进两个空格规则:

Issues

Issues

  • Closes #70 -- Rewrite the onboarding flow
    • Closes #71 -- New signup form
      • Closes #72 -- Add email verification step
    • Closes #73 -- New welcome email
undefined
  • Closes #70 -- Rewrite the onboarding flow
    • Closes #71 -- New signup form
      • Closes #72 -- Add email verification step
    • Closes #73 -- New welcome email
undefined

What this doesn't do

此流程不做什么

  • Doesn't invent work that wasn't done or described — every issue traces back to a commit, a diff, or something the user explicitly asked to track.
  • Doesn't create labels, milestones, or projects — only issues (with a
    type
    , when the repository supports one) and the PR's own title and body.
  • Doesn't merge, approve, request review, or otherwise touch the PR's review state — title and description only.
  • Doesn't assume any one environment's house rules for GitHub posts (e.g. an attribution footer convention) apply everywhere — an issue body or PR description is content the workflow above writes, not a comment; follow whatever posting conventions the current environment or repository actually specifies for those, rather than a rule baked into this skill.
  • 不会虚构未完成或未描述的工作——每个 issue 都可追溯到一次 commit、一处 diff,或用户明确要求跟踪的某项内容。
  • 不会创建 labels、milestones 或 projects——只创建 issues(仓库支持时设置
    type
    ),并更新 PR 自身的标题和正文。
  • 不会 merge、approve、request review,也不会以其他方式触碰 PR 的 review state——只处理标题和描述。
  • 不会假定任何单一环境的 GitHub 发帖规则(例如 attribution footer 约定)适用于所有场景——issue 正文或 PR 描述是上述工作流写入的内容,而不是 comment;应遵循当前环境或仓库实际规定的内容发布约定,而不是套用此 skill 中硬编码的规则。

Development

开发

See
meta/MAINTAINERS.md
for layout and versioning notes. Not read as part of carrying out a live "file issues for this PR" request — don't act on it while answering one.
有关布局和版本控制的说明,请参阅
meta/MAINTAINERS.md
。执行实际的“为该 PR 创建 issues”请求时不需要读取此文件——回答此类请求时不要据此采取任何操作。