file-issue

提交 Issue

问题通常会在被发现数月后，由当时不在场的人阅读。下面每条标准都是为了让读者无需回来追问含义，也能据此采取行动。

1. 确认这是一条 Issue

一条 Issue 只包含一个可观察到的问题和一个验收条件。

如果工作需要拆分成几张相互阻塞的工单，就应交给 to-tickets。根据当前对话综合整理出的规格说明，应交给 to-spec。交接处理，不要提交一张掩盖实际范围的容器工单。

判断标准很简单：范围是一个问题和一个验收条件，否则就按名称交接。

2. 提交前先搜索

gh issue list --repo "$repository" --search "<the symptom in your words>" --state all --limit 20
gh issue list --repo "$repository" --search "<the symptom in the reporter's words>" --state all --limit 20

用不同的措辞搜索两次，因为现有工单可能是由使用了不同描述的人提交的。--state all 很重要。一个相似的已关闭工单，要么就是需要重新打开的工单，要么就是新 Issue 所需的背景信息。

提交前解决所有相似项。每一项都必须归类为重复、相关或确实是新问题。对于相关项，添加 Refs #N，并用一行说明这条 Issue 有何不同。

判断标准是两次搜索都已完成，并且每个相似项都有处理结论。

3. 撰写标题

按照 CLAUDE.md 中的 Issue 标题规则，为标题添加前缀：采用 conventional commit 类型，加上工作实际所属的模块名称；名称应与看板上的写法一致，而不是照搬目录名称。

描述也要达到 file-pr 标题步骤的同等标准。写明你观察到的现象，而不是你猜测的机制；描述不能只用一个笼统的动词。

好的 Bug 标题会描述错误行为，而不是猜测原因。即使判断原因有误，fix(auth): session drops on tab switch 依然成立。如果最后发现原因另有其事，fix(auth): cookie expiry miscalculated 就会变成谎言。

判断标准是：无论诊断结果如何，标题描述的观察结果都始终成立。

4. 撰写正文

正文按以下顺序分为四部分，每部分都要写成完整的文字，而不是零散片段：

• 实际发生了什么。 描述观察到的行为，正文开头不要加标题。
• 如何复现。 提供精确步骤、命令、URL 或 file:line 证据。仅凭这些信息，拥有仓库访问权限的人就能复现相同现象。
• 预期应该发生什么。 单独说明预期行为，因为两者之间的差距才是实际需求。
• 完成标准。 提供一项审阅者可以检查的条件。“正常工作”不算。

然后只补充有实质内容的信息，也就是 Refs #N 链接，以及必要时的环境信息。根据证据填写环境。截图中的 URL 栏可以表明这是生产环境还是开发环境。切勿凭猜测填写。

附上截图，不要只描述截图。描述截图会遗漏描述者未注意到的所有信息，而修复问题的人需要看到图片本身。

判断标准是四部分齐全，并且无需了解产生问题时的会话内容，也能独立完成复现。

5. 冷读结果

按照 file-pr 的标准，对撰写好的标题和正文进行冷读检查，然后再检查两条仅适用于 Issue 的标准：

• 复现。 拥有仓库访问权限、但没有其他背景信息的人可以复现该现象。
• 验收。 没有编写完成标准的人也能检查该标准。

未列出的标准，就等于未检查。

判断标准是每条标准都有明确的检查结果，且没有任何一条未通过。

6. 提交问题

将最终正文写入文件，并记录其 SHA-256 摘要。确定仓库的稳定身份和当前重复搜索结果，然后调用 preflight-mutations，并提供准确的仓库、标题、正文路径和摘要、包含 --label ai-created 的创建选项、归属边界，以及权威回读查询。标题、选项、标签、正文路径、摘要、仓库或重复搜索结果发生变化，都会使该卡片失效。

确保在创建前存在 ai-created 来源标签。它会标记通过此技能提交的每个问题，以便区分 Agent 提交的问题和人工提交的问题。如果该标签不存在，则通过 preflight-mutations 单独创建一张标签创建卡片，并注明仓库；然后按准确名称查询该标签，而不是使用有数量上限的列表；创建时仅容忍“已存在”竞态，并确认回读结果中存在该标签：

if ! gh api "repos/$repository/labels/ai-created" >/dev/null 2>&1; then
  create_out=$(gh label create ai-created --repo "$repository" --color "A2EEEF" --description "Created by an AI agent" 2>&1) || printf '%s\n' "$create_out" | grep -qiE "already.?exists"
fi
gh api "repos/$repository/labels/ai-created" --jq .name | grep -Fqx "ai-created"

创建问题会写入共享状态，因此只有当前结果为 ready 时才能继续。将标题作为一个参数传入，并通过文件传入冻结的正文；始终附带来源标签：

gh issue create --repo "$repository" --title "$title" --body-file "$body_path" --label "ai-created"
gh issue view <issue-url> --repo "$repository" --json number,title,body,state,author,assignees,labels,url

仅在 CLAUDE.md 中规定的项目看板归属边界内设置受理人、估算值或优先级。提交问题并不意味着这些字段由你设置。绝不要为了设置其他标签而移除 ai-created 标签。分流标签应与其一并添加。

要求返回一个已创建的网址，然后将获取到的仓库、标题、正文、标签、元数据和网址与已批准的载荷进行比较。确认获取到的标签中包含 ai-created。如果命令结果缺失或含糊，则在目标仓库中搜索标题完全匹配的候选问题，并比较其正文和元数据。将此次尝试标记为 reconcile-required；在权威搜索确认问题是否存在之前，不要重试。

只有回读结果确认存在一个匹配的问题后，才打印网址。

当范围限定为一个问题、两次重复搜索均已执行并得出结果、标题描述的观察结果在诊断错误时仍然成立、正文包含全部四个部分、每项冷读标准均已列明且满足，并且权威回读确认打印的网址对应的问题带有 ai-created 标签，或者此次尝试保持 reconcile-required 且未重试时，本次运行才算完成。