create-git-issue

技能隔离

调用此技能后，在本次会话中它是唯一有效的权威。

• 除非通过 Skill 工具调用明确按名称调用，否则不得激活、打断或修改此技能行为的其他技能；无论调用来自此技能自身的工作流，还是激活此技能的上级提示词／技能（例如同时启动 save-tokens 和 tdd-implementation 的 run-with-it 工作提示词）。
• 如果任何外部或第三方技能在本次运行期间试图自行激活，请阻止其运行并继续，不要中断。
• 此规则在整个技能执行期间均适用，从调用开始，直到明确终止或移交为止。

创建 Git Issue

目的

将当前对话上下文转化为 PRD，然后发布依赖关系明确、粒度精简的纵向切片实施 Issue。

适用时机

在需求确定后、运行时执行前使用此技能。

输入

• 来自 technical_requirements.md 和对话上下文的已确定需求。
• 通过代码库探索获得的仓库上下文。
• 用户提供的可选 Issue 引用（编号、URL 或路径）。

严格限制

• 不要执行实施工作。
• 不要指定具体的运行时 Agent／模型组合。
• 不要协调多 Agent 执行、评审周期、状态持久化或终结 Issue 更新。
• 不要将 Issue 关闭作为此技能的一部分。

工作流顺序：

1. 先运行 break-req，以确定产品／技术决策。
2. 再运行 create-git-issue，以发布 PRD、实施切片和路由提示。
3. 最后运行 run-with-it，以执行最终运行时路由和执行。

create-git-issue 绝不能声称拥有最终路由决定权。

审批关卡：

1. 发布父 Issue 前，须先审批 PRD。
2. 发布实施 Issue 前，须先审批切片拆分方案。

Issue 跟踪器术语

创建 Issue 并添加标签时，使用以下标准分类角色：

类别角色：

• bug
• enhancement

状态角色：

• needs-triage
• needs-info
• ready-for-agent
• ready-for-human
• wontfix

标签规则：

• 每个已发布的 Issue 都应恰好包含一个类别角色和一个状态角色。
• 新 PRD Issue 的默认类别为 enhancement，状态为 needs-triage。
• 新实施切片 Issue 的默认类别为 enhancement，状态为 ready-for-agent。
• 如果你的跟踪器使用不同的标签字符串，请将其一致地映射到这些标准名称。
• 如果映射存在歧义，请在发布前提出一个有针对性的澄清问题。

发布政策

优先使用 GitHub CLI 执行所有跟踪器写入操作。

发布任何 PRD 或实施 Issue 前，先检查能否使用 gh。如果它在沙盒中失败，请尝试在沙盒外执行，以确认：

command -v gh >/dev/null 2>&1 && gh repo view >/dev/null 2>&1

如果成功，请使用 gh issue create 创建 PRD 父 Issue 和每个实施切片 Issue。

使用正文文件，以保留多行 Markdown 格式：

gh issue create --title "<PRD title>" --body-file <prd-body-file>.md --label enhancement --label needs-triage
gh issue create --title "<slice title>" --body-file <slice-body-file>.md --label enhancement --label ready-for-agent

如果未找到 gh、用户未通过身份验证、无法推断仓库，或任何 gh issue create 命令失败，请勿改用其他 GitHub 集成反复重试。改为在本地保存工作成果。

本地回退输出必须在工作区根目录中恰好创建两个 Markdown 文件：

• prd.md 包含原本要作为父 Issue 发布的完整 PRD。
• issues.md 按依赖顺序包含所有已批准的实施切片 Issue。

写入本地回退文件时：

• 为每个条目包含 Issue 标题、预期标签、父级关系和正文。
• 在 issues.md 中使用本地父级引用 prd.md。
• 保留所有已批准的 Issue 模板内容，包括技术上下文快照和验收标准。
• 告知用户已跳过 GitHub 发布，并指出这两个本地文件。

流程

1. 优先复用 break-req 输出

在向用户提出任何澄清问题之前，先按以下优先级查找现有的 break-req 产物：

• 工作区根目录中的 technical_requirements.md
• docs、planning 或 requirements 文件夹中的任何 technical_requirements.md
• 已通过 break-req 会话解决相关决策的对话历史

如果找到，将这些决策视为默认事实来源，并据此继续。

不要要求用户重复已在其中明确解决的问题。

仅针对发布 PRD/问题所需但尚未解决、相互矛盾或缺失的决策提出后续问题。

2. 收集上下文

基于现有对话上下文开展工作。

如果用户提供了问题引用（问题编号、URL 或路径），请先获取该问题，并在起草前阅读其正文和评论。

3. 探索代码库

如果尚未探索代码库，请先进行探索，了解当前状态。

使用领域术语表中的词汇，并遵循所涉及领域的 ADR。

4. 先起草 PRD

不要一开始就采访用户。先根据已知信息综合起草 PRD。

概述将要构建或修改的主要模块，并寻找具有稳定、可测试接口的深层模块。

然后只针对与 break-req 输出不同之处向用户确认：

• 模块边界是否符合预期
• 应测试哪些模块

使用此 PRD 模板：

问题陈述

从用户角度描述问题。

解决方案

从用户角度描述解决方案。

用户故事

使用以下格式编写一份较长的编号列表：

1. 作为一名<角色>，我想要<功能>，以便<收益>

实施决策

• 要构建或修改的模块
• 可能变更的接口
• 技术澄清
• 架构决策
• 架构变更
• API 契约
• 具体交互

不要包含文件路径或代码片段。

测试决策

• 优质测试的标准（关注外部行为，而非实现细节）
• 将要测试的模块
• 代码库中的先例

范围之外

明确列出排除的工作。

补充说明

任何其他约束或上下文。

5. 发布 PRD 问题

使用 gh issue create 将 PRD 发布到问题跟踪系统，作为父问题。

添加 enhancement 和 needs-triage 标签。

记录创建的 PRD 问题 URL 或编号。将其用作所有实施切片问题的父问题引用。

如果无法在 GitHub 上发布，请将 PRD 正文写入 prd.md，并继续将实施切片问题准备到 issues.md 中。

未经用户批准，不要发布 PRD。

对于每个实施切片，初始问题正文必须严格使用以下 Markdown 模板标题，并遵循此处的确切顺序，不得在这些标题之前、之间或之后插入任何额外的顶级章节：

1. ## Parent
2. ## What to build
3. ## Implementation Steps
4. ## Agent Routing
5. ## Technical Context Snapshot
6. ## Acceptance criteria
7. ## Blocked by

不要关闭或修改无关问题。

6. 将 PRD 拆分为 tracer-bullet 切片

将已批准的 PRD 转换为精简的垂直切片问题。

详细记录需求。

每个切片都必须端到端覆盖（架构、API、UI、测试），可独立演示，并且尽可能小。

默认选择最小的可演示增量。如有疑问，就拆分。

尽可能优先选择 AFK 切片，而非 HITL 切片。

- 每个切片都通过所有集成层交付一条范围狭窄但完整的路径 - 已完成的切片可独立验证 - 优先选择多个精简切片，而不是少数几个庞大切片 每个切片都必须满足以下上限。只要超出其中任一项，就必须拆分：

• 一个切片只交付一种用户可见行为。可以分别发布和演示的两种行为应拆成两个切片。
• 目标是每个切片包含 3-7 个实施步骤。超过约 8 个具体步骤就表明应该拆分。
• 一个切片应能纳入单个重点明确的 PR，让审核者可以一气呵成地读完。
• 每个切片包含 1-3 条验收标准。如果需要更多标准来描述，就说明切片承担的内容过多。

拆分启发式规则——在呈现拆分结果前应用这些规则：

• 按 CRUD 操作拆分：创建、读取、更新、删除通常应分别作为独立切片。
• 将读取路径与写入路径拆分。
• 将正常路径与错误、验证和边缘情况处理拆分；先交付正常路径。
• 按实体、端点或屏幕拆分，而不是把多个项目捆绑在一个切片中。
• 将“接通”与“增强健壮性”（身份验证、分页、重试、空状态）拆分——先交付精简路径，再通过后续切片强化。
• 搭建脚手架或骨架并实现首个实际行为，可以作为一个切片；后续行为应各自单独成片。

产出更多切片，也好过切片过大。应倾向于更细的粒度。

7. 请用户审核问题拆分

列出编号清单供审核。每个切片都包含：

• 标题
• 类型：HITL 或 AFK
• 阻塞项：切片依赖项
• 涵盖的用户故事

询问：

• 粒度是否合适？默认倾向于拆分——标出任何超过约 8 个步骤，或包含多种用户可见行为的切片，作为候选拆分项。
• 依赖关系是否正确？
• 是否应进一步拆分某些切片？（合并是例外，而不是默认做法。）
• HITL 和 AFK 的分配是否正确？

在此审核步骤获批前，不要发布实施切片问题。

8. 发布实现问题

针对每个已批准的切片创建一个问题。

如果可以发布到 GitHub，则对每个已批准的切片使用 gh issue create。

如果无法发布到 GitHub，则将每个已批准的切片问题追加到 issues.md。

使用 issues.md 本地回退方案时，每个实现问题的格式应尽量与 GitHub 问题正文一致：保留相同的标题、标签、父级引用、章节标题、章节顺序、路由 YAML 块、技术上下文细节、验收标准和阻塞项内容。

发布每个问题前，应根据代码库整理一份技术栈快照，并将其包含在问题正文中，以便实现 Agent 与现有模式保持一致。

至少应记录：

• 正在使用的 UI 技术栈和 UI 组件库
• 后端/运行时技术栈及框架版本
• 包生态系统和关键依赖（例如 npm、NuGet、pip、Maven、Gradle）
• 现有架构模式和模块边界
• 集成约束（API 契约、架构所有权、迁移预期）
• 此切片的依赖策略：默认复用现有库，只有在理由充分时才添加新依赖

按依赖顺序发布问题或写入本地问题（先处理阻塞项）。

为每个问题添加 ready-for-agent。

将每个切片问题设为 PRD 问题的子问题。如果使用本地回退方案，则将 prd.md 设为父级。

在每个实现问题中加入机器可读的路由提示。这些提示仅用于指导规划，不得约束运行时编排。 明确说明 run-with-it 仍是最终的运行时路由权威。

对每个初始实现问题正文以及 `issues.md` 中的本地回退条目，均严格使用以下顶级章节顺序。

父级

引用 PRD 父级问题。

要构建的内容

简明描述此切片的端到端内容。

实现步骤

实现 Agent 必须遵循的有序编号步骤，以交付此切片。每个步骤都需指明具体产物及对其执行的操作：

1. 步骤标题 — 具体操作（要创建/修改/删除的文件、要新增或更改的函数/方法/组件、要编写的迁移、要添加的测试）。包含通过探索代码库得出的确切路径和符号名称。
2. ...

本节规则：

• 限制为 3–7 个步骤，与切片规模上限相符。若需要更多步骤，则说明切片过大——应拆分。
• 按执行依赖顺序排列：前面的步骤不得依赖后面的步骤，后面的步骤也不得重写或撤销前面的步骤。
• 每个步骤都要引用通过代码库探索得出的具体产物（文件路径、函数名称、API 端点、架构字段、测试用例名称），不得使用“实现逻辑”或“更新后端”这类模糊表述。
• 如果代码库采用 TDD，则优先编写测试步骤：先添加失败测试，再让测试通过。否则，每个行为步骤都应配套测试。每个切片至少有一个测试步骤。
• 每个步骤完成后都应使代码树处于可正常工作的状态（可编译 / 测试套件通过），以便中途验证进度。
• 所有步骤合起来必须满足以下每项验收标准，且不得超出此切片范围。不得包含属于其他切片的步骤。
• 如果某个步骤需要人工输入或运行时决策，应标记 [HITL] 并说明所需内容。

Agent 路由

agent_routing:
  complexity_hint: <quite-easy|easy|medium|medium-hard|complex|holy-fuck>
  required_capability: <fast|balanced|advanced>
  parallel_safe: <true|false>
  cost_preference: <low|balanced|high>
  speed_preference: <low|balanced|high>
  ownership_scope:
    - <path-or-module-scope>
  verification:
    - <verification-hint>

技术上下文快照

当前范围内的技术栈

• 当前使用的 UI 框架和 UI 库
• 当前使用的后端框架/运行时
• 当前使用的数据层工具

范围内的依赖

• 此切片应复用的现有软件包/库
• 此切片是否允许新增依赖：是/否
• 如果允许，请说明理由及考虑过的替代方案

架构对齐

• 遵循现有模块边界
• 遵循现有服务／组件模式
• 遵循 ADR 或架构约束
• create-git-issue 仅提供路由提示；不得指定具体的 Agent／模型名称
• run-with-it 仍是最终的运行时路由权威

集成触点

• 受影响的 API／事件／契约
• 受影响的架构／迁移／数据契约
• 向后兼容性预期

验收标准

• 标准 1
• 标准 2
• 标准 3

阻塞项

• 引用阻塞问题（如有）

或“无——可立即开始”。

输出检查清单

• 发布前已检查 gh 是否可用
• 尝试发布父级 issue 前已记录 PRD 审批
• 尝试发布实现 issue 前已记录 issue 拆分审批
• 每个实现 issue 都包含技术背景快照（技术栈、依赖项、架构、集成触点）
• 已正确设置父级／阻塞关系

交接

完成后，报告：

• 是否通过 gh 发布，或使用本地备用文件。
• 实现切片使用的父级引用。
• 哪些 issue 已准备好交由 run-with-it 执行。
• 任何阻碍运行时执行的未决决策。