superpowers-issue-bridge

Superpowers Issue Bridge

适用场景

Superpowers 的 brainstorming 就是对话。对于尚无意图议题的工作，它可以有两种结束方式，由用户选择：

• 立即构建 — brainstorming 按照惯例继续：先设计，再制定计划、编写代码并创建拉取请求。不涉及议题。
• 先跟踪 — brainstorm-to-issue 会创建一个意图议题，然后会话到此结束。之后由用户或基于该议题工作的 Agent 来完成构建。

此桥接负责处理选择前后的环节：提供选项、从已有议题开始 brainstorming、将规格和计划追溯到议题，以及将完成的工作关联到议题。

步骤 1 之前 — 阅读跟踪器配置

阅读 docs/agents/issue-tracker.md。其中的 Backend、Location、Reading 和 Linking 部分说明议题存放在哪里、如何读取，以及拉取请求会写入什么内容来关闭或引用议题。

• GitHub，但没有 Reading 或 Linking 部分（配置文件是在这些部分出现之前编写的）：使用 GitHub 惯例 — #<number>、gh issue view、Closes #<number>、Relates to #<number>、gh issue close。
• **其他任何不包含这些部分的后端：**询问用户如何读取和关联其议题。
• **没有配置文件：**询问议题存放在哪里，不要想当然地认为它位于此检出的 GitHub 仓库中。

以下示例使用 GitHub 语法；请替换为跟踪器自身的语法。

步骤 1 — 查找意图议题

• 用户提到了某个议题（“实现 #42”、“构建 PROJ-123”）。
• 当前分支名包含议题引用（例如 feat/42-claims-status）。向用户确认 — 分支名中的数字不一定是议题。
• 否则，询问是否存在议题。不要因为用户没有提到就假定不存在，也不要猜测引用。

议题存在 → 步骤 3。不存在 → 步骤 2。

步骤 2 — 暂无议题：提供立即构建或先跟踪的选项

让 brainstorming 按照惯例从开场开始：探索项目、判定工作类型，并询问用于澄清问题的提问。理解问题之后，在 brainstorming 提出方案（架构路径）或展示简短设计（范围明确的路径）之前，单独提出这个问题：

“你想现在构建，还是先将其作为意图议题进行跟踪？”

• 立即构建 — brainstorming 按原计划继续。没有议题时，步骤 3–5 不适用。
• 先跟踪 — 根据目前的对话调用 brainstorm-to-issue。用户明确做出的每项决定都要写入议题的 Constraints 部分。议题创建后，会话即告结束：不编写规格、不调用 writing-plans、不写代码。用户的选择取代 brainstorming 通常的下一步。

如果答案已知，则跳过提问：

• 用户已经说明了选择：“就修复它”或“现在就构建”表示立即构建；“创建议题”或“先跟踪”表示先跟踪。
• Brainstorming 将工作判定为 spike。spike 以得出答案结束，而不是形成跟踪中的工作；用户之后可以为发现的问题创建议题。

步骤 3 — 从议题开始 brainstorming

使用跟踪器的 Reading 方法读取议题 — 在 GitHub 上使用 gh issue view <number> --repo <owner/repo> --json title,body,url。

将其中的 Problem / Proposed outcome / Affected users and systems / Constraints / Open questions 作为已解答的信息传递给 brainstorming：

• 不要再次询问议题中已说明的内容。
• 将 Constraints 视为已确定：其中包含用户已经做出的决定。只有用户要求时，才重新讨论其中的决定。
• 询问议题未涵盖的内容。在架构路径中，这包括替代方案、范围外边界和边缘情况；在范围明确的路径中，只询问简短设计所需的问题。
• 将 Open questions 保留为仍待回答的问题，除非对话已经解决这些问题。

步骤 4 — 将规范和计划追溯到议题

此步骤适用于头脑风暴的架构路径，这是唯一会写入文件的路径。撰写规范时（默认位于 docs/superpowers/specs/），请在标题正下方添加此行：

Intent-Issue: #<number> — <url>

writing-plans 撰写计划时（默认位于 docs/superpowers/plans/），请原样保留此行，并将其放在计划标题中的 **Spec:** 行之后。如果意图是本地 Markdown 文件，则用文件路径替换 #<number> — <url>。

Spike 和有界路径不会撰写规范或计划。不要为了放置此行而创建文件——第 5 步中的链接就是追溯记录。

步骤 5 — 将已完成的工作关联回议题

工作会在 finishing-a-development-branch 阶段落地—— subagent-driven-development 和 executing-plans 最终都会进入该阶段。用户选定其中一个选项后，只需询问一次：这项工作是否完全解决了意图议题，还是只完成了部分内容？ 然后按跟踪器的「关联」部分执行：

选择的选项	完全解决	部分解决
推送并创建 PR	在 PR 正文中添加完成引用（Closes #<number>）。	在 PR 正文中添加部分解决引用（Relates to #<number>）。
在本地合并	没有 PR 承载引用，因此不会自动关闭议题。告知用户，并提出在推送合并后手动关闭议题（gh issue close <number> --comment "Resolved in <sha>"）。	推送合并后，提出在议题中评论并注明合并提交（gh issue comment <number> --body "Progress in <sha>"）。
保持现状	暂无内容可关联。	暂无内容可关联。

如果「关联」部分中的「完成 PR」为 None——例如本地 Markdown，或不会通过集成关闭议题的 Jira 或 Trello 看板——那么 PR 不会关闭任何议题。无论如何，都要写入部分解决引用。对于完全解决议题的工作，告知用户 PR 合并时该议题不会关闭，并说明他们应在合并后执行的手动关闭步骤。

手动关闭或评论会更改跟踪器：只有得到用户同意后才能执行。

在无人值守运行中——调度器在没有人可询问的情况下处理议题——应根据实施者的报告来判断：如果议题要求的内容仍可通过更改此仓库来完成，则视为部分解决。此处无法通过任何更改完成的事项——例如由所有者进行配置或生产环境运行、手动检查、在其他仓库中开展的工作，或由其他议题跟踪的工作——属于后续事项：将其列在 PR 正文中，且不因此将当前工作视为部分解决。在 PR 正文中说明判断结果及理由，并在运行结束时向用户询问每项部分解决的工作。

不要默认关闭议题。意图议题通常比单个 PR 涉及的范围更大，过早关闭会破坏此设置旨在保护的审计记录。

不要做的事

• 不要将此桥接逻辑合并到 Superpowers 自身的技能文件中——应将其保留为独立技能，以免 Superpowers 更新时覆盖它。
• 不要再次询问用户意图议题中已有答案的问题，也不要自行重新打开其中的 Constraints。
• 用户选择先跟踪后，不要撰写规范、运行 writing-plans 或开始编写代码。
• 不要仅为放置 Intent-Issue: 行而创建规范或计划文件。
• 不要假定是「完全解决」或「部分解决」——每个 PR 或合并都只询问一次。
• 不要捏造议题引用。如果找不到或无法确认议题引用，就在不猜测的情况下继续。
• 对于非 GitHub 跟踪器，不要使用 GitHub 的 #<number> 或 Closes 语法。
• 未经用户同意，不要关闭或评论议题。