Menu
Issue / Bug standard handling flow — dual platform (GitHub + TAPD) with 5-scenario handoff discipline, doc-first approach
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
流程编排引擎。推进 task.json.flow 步骤（init/check/complete/reset）并维护任务级事件流 task.json.events（emit/check/recent）。触发关键词：flow advance、推进流程、当前步骤、初始化流程、emit event、查事件、task.json.events、flow-engine。
TAPD 统一入口 skill。工单拉取、共识管理、子任务回填、事件驱动同步。触发关键词：tapd、初始化、ticket sync、共识、Wiki 评审、子任务、工时回填、QA 通过、QA 打回、TAPD 事件、契约推送、同步工单、拉工单。
产出结构化 handoff 工件，让新 session 无痕接续当前任务。ctx-guard 阻断或主动切换 session 时使用。触发关键词：context reset、上下文重置、新开 session、切换 session、handoff。
运行架构适应度函数检查代码结构、契约、依赖方向。在代码修改前后使用，确保不引入架构违规。触发关键词：fitness、架构检查、适应度、lint、代码质量检查。
工作流熵管理。清理 stale TAPD cache、孤立 _index 条目、过期 task report。每日定时或手动触发。触发关键词：gc、垃圾回收、清理、cleanup、定时清理。
Git 操作统一入口。分支生命周期（create/merge/cleanup）、worktree（create/remove）、提交推送（commit-push）。按 docs/git-brance-spec.md + Conventional Commits 中文规范执行。触发关键词：创建分支、合并到 dev、合并到 uat、删除分支、清理分支、git push、commit、推送代码、worktree、提交代码。
Baseado na classificação ocupacional SOC
| name | issue |
| description | Issue / Bug standard handling flow — dual platform (GitHub + TAPD) with 5-scenario handoff discipline, doc-first approach |
| disable-model-invocation | true |
| installed-from | agent-dev-standard@cf04193 |
| installed-on | "2026-05-29T00:00:00.000Z" |
按 issue 处理协议（参考 protocols/issue-process.md）处理指定 issue / bug。本 skill 支持 GitHub Issue（原生）+ TAPD Bug（2026-05-20 加 / 见 §TAPD 平台分支段）双平台。
协作流纪律: 任何 handoff 必须显式判定 S1-S5 五场景之一(详见 rules/core/issue-handling.md Iron Law: NO HANDOFF WITHOUT EXPLICIT SCENARIO + COMMENT FIRST)。
$ARGUMENTS：issue 编号（如 123）或 list执行前读取项目 CLAUDE.md 中的 ## Issue 配置 段，获取以下信息：
| 项 | 含义 |
|---|---|
issue_platform | 平台维度（github / tapd / 双平台项目可 github+tapd / 决定走哪条分支 / 默认 github） |
issue_repo | GitHub 平台:Issue 仓库（owner/repo） |
tapd_workspace_id | TAPD 平台:workspace 数字 ID |
tapd_ticket_prefix | TAPD 平台:ticket URL 前缀（可选，用于 comment 渲染） |
doc_repo | 共享文档仓库本地路径（用于文档同步） |
adr_path | ADR 文件目录 |
code_path | 代码根目录 |
compile_cmd | 项目编译命令（如 mvn compile -q / npm run build 等） |
role | 当前角色（默认 be，可为 fe / qa / sa）必须 lowercase(对齐 labels.yml / 见 §Step -1 normalize) |
如果配置不存在，提示用户先运行 /install 或手动指定。
list 时拉取 issue 原文 + 所有 comments
完整展示 issue 内容
S/M/L 分级（在填自检表前先判断，决定后续每步深度）：
| 级别 | 判定特征 |
|---|---|
| S | 单文件改动 / 无接口变更 / 无状态机影响 / 无歧义，可直接修 |
| M | 单模块改动 / 可能有接口变更 / 状态机简单涉及 / 基本明确 |
| L | 跨模块 / 接口或数据模型变更 / 需求有歧义 / 架构决策或 Gap |
输出格式：分级：S / M / L，理由：<一句话>
问题定性自检表（硬门禁，不得跳过）
执行硬约束：
Comment template（depth 按 S/M/L 调整内容详尽度）：
## Step 0 — 问题定性自检表
**分级：** S / M / L
**理由：** <一句话>
### 需求前提
- [ ] 共识文档有明确定义 → 引用章节号
- [ ] 共识文档有提及但模糊 → 引用 + 标注模糊点
- [ ] 共识文档未提及 → 标注 **"需求空白"**
### 影响范围
- [ ] 只影响当前接口 → 列出接口
- [ ] 影响同模块其他接口 → 列出关联接口
- [ ] 跨模块 → 列出受影响模块
### 修复前提
- [ ] 不需要需求决策，代码逻辑明确有错 → 可直接修
- [ ] 存在 ≥ 2 种合理实现 → 列出选项，等用户拍板
- [ ] 需求本身未定义 → 标注 **"需 PM 确认"**，先建 Gap Issue
### 架构师视角 3 维
**架构影响：**
- [ ] 无影响（纯实现细节）
- [ ] 消除约束（改善）：<一句话>
- [ ] 新增约束（需评估）：<一句话>
**技术债维度：**
- [ ] 消除债：<具体哪条>
- [ ] 无关
- [ ] 新增债（需标注）：<什么债 / 为什么接受>
**长期演化：**
- [ ] 让未来简单（复用性增）
- [ ] 无影响
- [ ] 让未来复杂：<为什么接受 / 是否走 LMP>
### LMP 升级判定
任一维度勾"新增约束 / 新增债 / 让未来复杂" → **强制升级 LMP**（即使代码改动小）
### 场景判定（S1-S5 / 2026-05-20 加 / 详见 `rules/core/issue-handling.md`）
按 `rules/core/issue-handling.md` §二.2 算法判定本次处理对应场景:
- [ ] **S1 修完→回测**(BE 完整修复 / 推 QA / pending-verify)
- [ ] **S2 部分修→转 FE**(BE 完成本端 / 需 FE 继续 / pending-collaboration)
- [ ] **S3 修前需 PM**(评估发现需 PM 拍板才能动 / pending-decision)
- [ ] **S4 部分修后需 PM**(BE 修一部分 / 剩余需 PM 拍板 / pending-decision)
- [ ] **S5 不需修→回 QA**(判定非 bug / 不修 / closed-no-action)
**判定结果显式标记:** comment 第一行标 `[S{N}] <场景中文标识>`,后续 §3.1 4 字段 + §3.2 场景特定字段均按场景填写。
**平台映射:** S1-S5 在 GitHub 上的字段表达见 `docs/concepts/platform-mapping-github-issue.md`;在 TAPD 上的字段表达见 `docs/concepts/platform-mapping-tapd-bug.md`(+ MCP 操作规约 `protocols/tapd-bug-operations.md`)。
**场景 → 阶段二分支映射(2026-05-20 加 / F-3 + F-4 follow-up):**
- S1 修完→QA / 纯实现 → `pm-reviewed` 分支
- S2 部分修→FE / 跨端协作 → `cross-role-handoff` 分支(新增 / 见阶段二)
- S3 修前需 PM → `raised` 或 `pm-reviewed`(取决于是否已有 PM 决策 / 通常 `raised` 等 PM 回复)
- S4 部分修后需 PM → `raised`(写 BE 部分实施 + 剩余决策选项 / 等 PM 回复)
- S5 判定不修 → `纯文档类` 分支(comment 含判定理由 + 切 confirmed / 见阶段二)
执行步骤：
gh issue comment <N> -F <tmpfile> 贴上述 template comment（占位符填好）意图回读 — 用自己的话复述理解：
【我理解的目标】…
【我理解的约束】…
【我不确定的地方】…
判断当前状态，给出执行层处理建议：
硬性停止 — 展示以上全部内容后，必须停下来等待用户确认。禁止自行进入阶段二。用户未回复 = 未确认。
根据 issue 状态分支：
raised（产品经理尚未回复）[role]-reviewedneeds-pm → 同步录入 <project>/docs/problems/needs-pm-queue.md 的 Open 段pm-reviewed（执行层可实现）按以下步骤顺序执行：
Step -1 — role 字段大小写 normalize（2026-05-25 加 / Issue #11 KR-FB-002）
CLAUDE.md role: 字段在 Step 1~6 多处用于 label 拼接（[role]-in-progress / [role]-confirmed 等）。labels.yml 定义的 state labels 全部 lowercase（be-in-progress / fe-confirmed 等）。若 role: BE（大写）则拼出 BE-in-progress 在 gh issue edit --add-label 时失败（label 不存在）。
进入 Step 0 前必须 normalize role:
# 从 CLAUDE.md 读 role 后立即 lowercase
role=$(echo "$role" | tr '[:upper:]' '[:lower:]')
约束: CLAUDE.md.template 已示例 role: be（lowercase）+ 加注释"必须 lowercase / 对齐 labels.yml"。如 role 仍出现大写 → 强制 normalize 后用 / 不报错。
Step 0 — 在 Issue 贴执行清单 comment（硬性前置，不得跳过）
用户确认方案后，第一个动作是在 Issue 贴一条清单 comment，作为本次执行的唯一追踪源：
## 执行清单（[role]）
- [ ] 标 `[role]-in-progress` + comment "开始实现"
- [ ] 文档先行（标记待实现，同步共享仓库）
- [ ] Step 3.5 — 测试计划（产出物级 / 测试骨架 FAIL 锁定 / dogfood）
- [ ] 实现
- [ ] 编译门禁（项目 CLAUDE.md 指定的 compile_cmd）
- [ ] 测试
- [ ] 6a — 模块文档 / api-spec / 追溯链更新，同步共享仓库
- [ ] 6b — problem-registry 同步
- [ ] 6b — Issue comment（commit hash + 文档链接 + 摘要）
- [ ] 6b — label **保持 `[role]-in-progress`**（不在收尾时切），注明 "工作完成 — 等 /release 发版"
- [ ] 6b — 等 `/release` 发版成功后由 release skill 批量切 `[role]-in-progress` → `[role]-confirmed` + comment 嵌入「可关闭」
贴出后每完成一步立即更新对应 checkbox（[ ] → [x]）。清单是执行的唯一追踪源，不靠记忆。
标 [role]-in-progress（硬门禁）
gh issue view <N> --json labels 验证含 [role]-in-progress labelgh issue edit <N> --add-label [role]-in-progress + comment "开始实现"（不填 ETA）文档先行 — 判断是否触发 ADR（架构调整 / 技术选型 / 明显取舍）；更新 / 创建相关文档，标记"待实现"，同步共享仓库并推送
文档先行豁免规则（2026-05-25 加 / Issue #11 KR-FB-003）: 满足全部条件可豁免，需在 comment 明示理由 + 字段:
豁免 comment 必填字段:
实现 — 确认分支状态（工作区干净、基准分支正确）；实现代码 / 文档改动；遵循 rules/core/research-first.md 和 rules/core/incremental-verification.md
commit message 关键词禁用清单（硬门禁 / 2026-05-25 加 / Issue #11 KR-FB-005）:
GitHub 默认行为:含以下关键词 + #N 的 commit push 到 default branch 时 auto-close issue #N。agent 写出 closes #N → push → GitHub 替 agent 关 issue = agent 间接 close / 违反 SKILL.md 约束(closed 只由人工触发)。
❌ 禁用 commit message 含(case-insensitive):
closes / close / closed / closing
fixes / fix / fixed / fixing
resolves / resolve / resolved / resolving
✅ 推荐 commit message 引用 Issue:
<type>: <subject>
refs #<N> # 或 related #<N> / see #<N> / cf #<N>
真实影响: auto-close 会让 /release Step 6.3 (V2 算法 list --state open)扑空 / [role]-confirmed label 切换跳过 / 需 gh issue reopen <N> 恢复 / 与 /release 核心承诺("[role]-confirmed 由 release 切")矛盾。
机器化辅助(可选 / 推荐): install/modules/05-core-hooks.sh 可注入 commit-msg hook 拦截 auto-close 关键词 + #N 引用组合。
编译门禁（硬门禁） — 跑 <compile_cmd>（项目 CLAUDE.md 指定），失败 → 修 → retry（max 2 次），仍失败 → 停下来上报用户
测试 — 按改动类型执行最低测试要求
收尾 6a —
收尾 6b —
同步 problem-registry（如有对应 P-xxx 条目，更新状态为 resolved）
needs-pm-queue 状态同步（如 Issue 曾入 Open 段）
写 Issue comment（commit hash + 共享仓库文档链接 + 摘要）
文档同步声明强制三选一（防止 50% 缺失率）：
commit hash 格式：用 commit: `<hash>` 格式（前缀 commit: + 反引号包裹），机器可解析，供 /release 反查是否已部署
commit: `9818485`commit: \\\9818485\``（反斜杠转义后落库变字面量，regex 不命中）gh issue comment <N> --body-file <path> 改走外部文件commit hash 动态捕获 + 占位禁止（硬门禁 / 2026-05-25 加 / Issue #8）：
# 1) 先 commit + push（不在此步嵌 hash）
git commit -m "<message>"
git push origin <branch>
# 2) 捕获真实 hash（commit 完成后）
ACTUAL_HASH=$(git rev-parse --short HEAD)
# 3) 用变量插入 comment（heredoc 中用 ${ACTUAL_HASH}）
gh issue comment <N> --body "$(cat <<INNER
...
commit: \`${ACTUAL_HASH}\`
...
INNER
)"
commit: \a1b2c3d`/commit: `TODO`/commit: ``）— 占位忘改 = 错误 hash 永久落库 = audit / /release` 反查拿到无效 hashgit cat-file -e ${ACTUAL_HASH} || { echo "hash invalid"; exit 1; } 双保险存在性校验comment 落库后自检（强制）：写 comment 后立即 grep 验证可识别：
gh issue view <N> --comments | grep -oE 'commit:\s*`[a-f0-9]{7,40}`'
命中 = 合规（≥ 1 行输出）；空输出 = 格式不合规，立即重写 comment
label 保持 [role]-in-progress 不变（不在收尾时切；由 /release 发版成功后批量切 [role]-confirmed）
注明 "工作完成 — 等 /release 发版"（6a 全部完成 + 三选一已填后；「可关闭」由 /release Step 6b.1 切 label 时同步嵌入）
closed issue ↔ commit/release 关联 4 字段（硬约束 / 2026-05-25 加 / Issue close-association 范式 v0 §3.5）:
适用: Standard 项目无 deploy 概念但 closed issue 仍需可追溯 → Close comment 必含 4 字段(D self-contained 快照层)+ CHANGELOG/release-log [Unreleased] 段累积(E 聚合层 SemVer)。
流程(close 前硬门禁):
code@<hash> / docs@<hash>)code/CHANGELOG.md [Unreleased] § Changed / Added / Fixed 段 append entry "YYYY-MM-DD — <总结> (#) / commit: "docs/docs/release-log.md [Unreleased] 段 append / 若无设计层改动 → 显式标"不涉及"(不能省略字段)helper 命令(可选 / 提示 EL 填):
# 1) 查最近 commit
git log --oneline -- <file> | head -3
# 2) grep CHANGELOG 当前 Unreleased entry
sed -n '/^## \[Unreleased\]/,/^## \[/p' code/CHANGELOG.md | head -30
# 3) grep release-log 当前 Unreleased entry
sed -n '/^## \[Unreleased\]/,/^## \[/p' docs/docs/release-log.md | head -30
硬门禁: 4 字段任一未填 / 不允许 close issue。closed 由人工触发(agent 不主动 close)/ comment 中注明「可关闭」时必含 4 字段。
反模式:
cross-role-handoff(S2 / 部分修 → 转 FE / 或反向 FE → BE 等 / 2026-05-20 加 / F-3 follow-up)按 S2 场景处理跨端协作:
docs/concepts/platform-mapping-github-issue.md §3.3 / docs/concepts/platform-mapping-tapd-bug.md §3.4):
needs-fe(对称 needs-pm)+ assignee 转 FE 负责人 / [role]-in-progress 保持(反映 BE 端完成 + FE 待接手)current_owner 单值替换为 FE Dev / v_status 不变(参考 protocols/tapd-bug-operations.md IC-3 替换模式)@<FE-user> 请按 FE 接手边界继续 / TAPD 用 @{中文名}(FE) 文字标识)适用以下 2 种场景:
[role]-confirmed + comment 嵌入「可关闭」
Status: dogfood (2026-05-26 起 / #17 接纳). 详
rules/core/stage-gate.md。G4 测试骨架 Gate 由下方 §Step 3.5 覆盖。dogfood 期 LMP L 必走 / M 推荐 / S 豁免。跨家族 ≥ 2 项目实证后升 active。
位置: 介于 spec-to-code-flow 节点切换之间(feature 级,非 Issue 级)。/issue 触达单 Issue 时,若该 Issue 属于 feature 级开发流程,本 skill 须先确认上游 Gate 已 PASS。
| Gate | 触发位置 | 消费方动作 | 产出物 | 用户确认 |
|---|---|---|---|---|
| G1 — 理解 | 共识文档 → 模块清单 之后 | 阅读共识文档 / 形成 AI 理解清单 / 用户确认 | AI 理解清单(复述 + 推断项) | gh issue comment "G1 PASS" + stage-state 记录 |
| G2 — 架构 | 模块清单 → 架构 之后 | 阅读模块清单 / 形成架构视图 + 用例切片 / 用户确认 | 架构视图 + 用例切片 | 同上 "G2 PASS" |
| G3 — 计划 | 架构 → 接口/数据模型 + 测试计划 之后 | 阅读架构 + AC / 形成依赖图 + AC 映射 + 风险标注 / 用户确认 | 用例依赖图 + AC 映射 + 风险标注 | 同上 "G3 PASS"(G3 之后立即触发下方 §Step 3.5 测试骨架生成 = G4) |
Gate 顺序约束(硬): G1 → G2 → G3 → G4(Step 3.5 骨架生成)→ /issue 主体(实现)。前一 Gate 未 PASS 不允许进下一 Gate。
rule 对偶: 本段是 rules/core/stage-gate.md 的 SKILL 落地。rule 定义"为什么 / 是什么 / 约束 / 风险点 v1 OPEN",SKILL 定义"怎么在 /issue 流程中执行"。
Status: dogfood (2026-05-26 起 / #15 接纳). 详
rules/core/test-skeleton-lock.md。dogfood 期 LMP L 必走 / M 推荐 / S 豁免(详 rule §风险 15.1)。跨家族 ≥ 2 项目实证后升 active。
位置: 在 §执行清单 #2(文档先行)之后、#3(实现)之前触发。
产出物: 测试骨架文件集 + 覆盖率映射表
3.5.1 从本 Issue 的 AC 清单生成测试块(每 AC 一个,断言全 FAIL)
3.5.2 生成覆盖率映射表(AC ID ↔ 骨架文件 ↔ 测试块 ↔ 状态)
3.5.3 git commit 锁定(基线建立)
3.5.4 硬门禁:进入 Step 4(实现)前 git status 必须 clean;Step 4 完成时 git diff <pre-implementation-commit> -- <skeleton-files> 不能有命中
rule 对偶: 本 Step 是 rules/core/test-skeleton-lock.md 的 SKILL 落地。rule 定义"为什么 / 是什么 / 约束",SKILL 定义"怎么执行"。
closed 只由人工触发，agent 不主动 close，完成后 comment 中注明「可关闭」rules/core/large-module.md：涉及较大改动时先呈现方案，等用户确认rules/extension/adr-discipline.md（按需启用）：架构级决策在编码前生成 ADRissue_platform: tapd 时走此路径)| 路径 | GitHub Issue(现行) | TAPD Bug(新加) |
|---|---|---|
| 拉取 issue | gh issue view <N> --comments | tapd:get_bug + comment 历史(workspace_id 必带) |
| Step 0 自检表 | 共用(平台无关 / S 场景判定 + LMP / 见上) | 共用 |
| 字段操作 | gh issue edit + label / assignee | tapd:update_bug(v_status + current_owner 双字段铁律) |
| 收尾 comment | markdown 格式 | TAPD 富文本(简化 / 详见 docs/concepts/platform-mapping-tapd-bug.md §三.1 格式差异表) |
/release 联动切 [role]-confirmed | ✅(GitHub label) | ❌(TAPD 状态机不切 confirmed / Dev 最远到待测试/ 由 QA 接手) |
进入实施前 / 已通过 Step 0 自检表 + 场景判定(S1-S5):
Step 0 — TAPD MCP 调用强制前置(get_bug)
任何 update_bug 之前 must 先 get_bug 读现状(current_owner / reporter / fixer):
tapd:get_bug
workspace_id: "{tapd_workspace_id}"
options:
id: "{bug_id}"
fields: "id,status,current_owner,reporter,fixer"
详见 protocols/tapd-bug-operations.md IC-2。
Step 1 — 按场景执行字段操作 + comment
按 rules/core/issue-handling.md §二.2 判定的场景,comment 先,字段操作后(COMMENT FIRST 铁律):
| 场景 | comment 模板 | 字段操作 | current_owner 模式 |
|---|---|---|---|
| S1 修完→QA | platform-mapping-tapd-bug.md §三.3 | v_status: 待测试 + current_owner 追加 reporter | 追加(分号) |
| S2 部分修→FE | §三.4 | v_status 不变 + current_owner → FE Dev | 替换 |
| S3 修前需 PM | §三.5 | v_status 不变 + current_owner → PM | 替换 |
| S4 部分修后 PM | §三.6 | v_status 不变 + current_owner → PM | 替换 |
| S5 不需修→QA | §三.7 | v_status: 待测试 + current_owner 追加 reporter | 追加(同 S1 / 区别在 comment 内容) |
Step 2 — 7 硬约束 self-check
update_bug 调用前后必跑(见 protocols/tapd-bug-operations.md §二):
get_bug 已前置current_owner 追加 vs 替换正确(对照场景表)status: resolved 解读为"已解决"待测试时 / 走 protocols/tapd-worktime-integration.md)Step 3 — TAPD 收尾(6a / 6b)
[role]-confirmed 切换概念(TAPD 走自己的 v_status / 不复制 GitHub label 体系)rules/core/issue-handling.md §二 5 场景在 GitHub 上需要扩展 label 体系覆盖 S2:
| label(GitHub 侧新增 / 待落地) | 用途 |
|---|---|
needs-fe | S2 转 FE 标记(对称现有 needs-pm) |
needs-be | 反向 / FE 转 BE 标记 |
needs-qa | S1 / S5 推 QA 的辅助标记(可选 / 不强求) |
当前状态: label 仅在 SKILL.md / rule 描述层落地,GitHub repo labels.yml 配置同步留后续(/install skill 升级时同步 + 涉及 GitHub repo admin 操作)。
同一 Bug 在 GitHub Issue 和 TAPD Bug 上分别有 ticket 时:
| 关联 | 关系 |
|---|---|
Layer 1 docs/concepts/issue-handoff-flow.md | 5 场景概念层 / 本 skill 是其平台落地 |
Layer 2 docs/concepts/platform-mapping-github-issue.md | GitHub 字段映射 / comment 模板源 |
Layer 2 docs/concepts/platform-mapping-tapd-bug.md | TAPD 字段映射 / comment 模板源 |
rules/core/issue-handling.md | 5 场景纪律(Iron Law + Red Flags + 借口对照)/ 本 skill 是其执行层落地 |
protocols/tapd-bug-operations.md | TAPD 字段层 7 硬约束 / 本 skill TAPD 分支段直接引用 |
protocols/tapd-worktime-integration.md | TAPD 工时集成 / 本 skill IC-7 引用工时填写时点 |
PM 规范 SSOT docs/requirements/2026-05-20-tapd-bug-handoff-flow/source/pm-tapd-ticket-spec-v1.5.md | TAPD 字段规范权威源 / 通过 Layer 2 文档间接引用 |
参考 protocols/issue-process.md —— 本 skill 是 issue-process 协议的执行层 skill。状态机定义 / 5 维度审查由 protocol 描述，本 skill 实施 PDCA。
参考 protocols/tapd-bug-operations.md —— TAPD 平台分支段直接引用其 7 硬约束。