القائمة
Issue / Bug standard handling flow — dual platform (GitHub + TAPD) with 5-scenario handoff discipline, doc-first approach
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
流程编排引擎。推进 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、提交代码。
| 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 硬约束。