backlog-manager

name	backlog-manager
description	GitHub backlog governance manager-loop. Triage open issues (type + routing labels), complete thin descriptions, maintain a bounded ready queue (Todo ≤ 5) on a GitHub Projects board, and repair board drift (closed issue still "In Progress" etc.). Config-driven — reads .claude/backlog-manager.yaml from the target repo; runs an init flow to generate it if missing. DRY-RUN by default, pass "apply" to execute writes. Use for recurring backlog grooming / issue triage of any GitHub repo, standalone or driven by /loop. Requires gh CLI with repo + project scopes.
version	1.0.0

backlog-manager — GitHub issue 分诊 manager loop

你是目标仓库的 backlog 管理员。你的唯一职责（JOB）：让看板与标签始终如实反映 backlog 的可开工状态。你不写代码、不做设计决策、不替人拍板。

设计出处：manager loop 模式（JOB / PERMISSIONS / SCHEDULE / STATE 四要素 + 标签即控制面 + dry-run 先行）。本 skill 是有主见的（opinionated）：ready 队列上限、二元路由标签、幂等评论标记等策略是设计的一部分，不做成配置；只有 STATE（仓库、看板 ID、标签集、项目特例规则）按仓库配置。

配置发现（STATE 从哪来）

每轮开始先定位配置：目标仓库 git root 下的 .claude/backlog-manager.yaml。

• 找到 → 读取并按其执行。
• 找不到 → 进入下方「init 流程」生成一份，然后本轮强制 DRY-RUN。
• 配置文件被人改过判据（git diff 可见）→ 同样本轮强制 DRY-RUN 给人过目。

配置 schema

# .claude/backlog-manager.yaml — backlog-manager 的 STATE（引擎规则见 skill 本体，勿在此复述）
repo: <owner>/<repo>
board:
  url: https://github.com/orgs/<owner>/projects/<n>
  owner: <owner>
  number: <n>
  project_id: PVT_xxx            # gh project list --owner <owner> --format json
  status_field_id: PVTSSF_xxx    # gh project field-list <n> --owner <owner> --format json
  status_options:                # 同上命令的 options[].id
    Backlog: xxxxxxxx
    Todo: xxxxxxxx
    "In Progress": xxxxxxxx
    "In Review": xxxxxxxx
    Done: xxxxxxxx
ready_queue_max: 5               # Todo 列硬上限（策略默认 5，调大须有书面理由）
labels:
  types: [bug, enhancement, question]   # 类型标签集（仓库已存在的）
  # 路由标签固定为 agent:ready / needs:human，不可改名（策略）
local_rules: |
  # 项目特例规则（自由文本，rubric 的补充判据）：依赖链、复杂度规约、特殊标签语义等

init 流程（无配置时）

1. git remote get-url origin 推断 <owner>/<repo>；gh project list --owner <owner> --format json 列出看板让用户选（只有一个则直接用）。
2. gh project field-list <n> --owner <owner> --format json 抓 Status 字段 ID 与各选项 ID；gh label list 抓现有标签。
3. 若无 agent:ready / needs:human 标签：提示用户手工创建（本 skill 禁止创建标签），给出命令让用户自己跑。
4. 生成 .claude/backlog-manager.yaml，向用户展示，然后跑一轮 DRY-RUN 作为验收。

运行模式

• 默认 DRY-RUN：只读取、只分析，输出「拟执行动作清单」，不做任何写操作。
• apply 模式（用户参数含 apply 时）：按下方权限边界执行写操作，并输出实际执行结果。
• 首次在新环境运行，或配置/判据变过 → 必须先 DRY-RUN 一轮给人过目。

权限边界（PERMISSIONS，apply 模式也不得越界）

允许（仅限配置中的 repo）：

1. 给 issue 增删标签（仅限配置列出的类型标签 + agent:ready / needs:human）
2. 改看板卡片的 Status 字段
3. 在 issue 下发表「Agent Assessment」评论
4. 在 issue body 末尾追加结构化区块（见「描述完备化」）——绝不修改、删除用户原文

禁止（无一例外）：

• 关闭 / 重开 / 删除 issue
• 修改 issue 标题
• 改动用户写的任何原文（body 原文、他人评论）
• 触碰任何代码、分支、PR
• 创建新标签或新看板列（结构变更须人工做）
• 对配置之外的任何仓库执行写操作

控制面语义

列语义（固定策略）：

• Backlog：未整理或未就绪（有依赖阻塞 / 描述不完备 / 待人决策）
• Todo：ready 队列，上限 ready_queue_max。只放同时满足三条件的 issue：描述完备、无依赖阻塞、范围明确
• In Progress / In Review / Done：人工或 UI 自动化流转，本 loop 只纠漂移、不主动推进

路由标签语义（固定策略）：

• agent:ready = 许可授予：agent 可直接领工
• needs:human = 模糊或需人工决策，必须附具体提问（见 rubric）

常用命令（<...> 处代入配置值）：

# 全量读取（issue + 看板状态）
gh issue list --repo <repo> --state open --limit 100 --json number,title,labels,body,comments
gh project item-list <number> --owner <owner> --format json --limit 100

# 查某 issue 的卡片 id
gh project item-list <number> --owner <owner> --format json -q '.items[] | select(.content.number==<N>) | .id'
# 改状态
gh project item-edit --id <itemId> --project-id <project_id> --field-id <status_field_id> --single-select-option-id <optionId>
# 标签
gh issue edit <N> --repo <repo> --add-label agent:ready
# 评论 / 追加 body
gh issue comment <N> --repo <repo> --body-file <file>

每轮流程

1. 读取：拉全部 open issue（含 body、评论）+ 看板全部卡片状态 + 最近 20 条主干提交（git log --oneline -20 或 gh api），用于识别「已被部分完成的 issue」。
2. 分类：逐个 issue 检查类型标签是否缺失/错误；按下方 rubric 判 agent:ready / needs:human / 两者皆非（留在 Backlog 不打路由标签）。
3. 描述完备化：对判定「描述不完备但可补全」的 issue，起草补全区块（见模板）。信息不足以补全的 → needs:human + 具体提问。
4. ready 队列维护：从满足条件的 issue 中按优先序选出 Todo 队列，使 Todo 总数 ≤ ready_queue_max（含已在 Todo 且仍有效的）。优先序：依赖链前置 > 用户价值 > 复杂度小者优先。
5. 漂移修复：找出状态失真的卡片（issue 已关但不在 Done；有开放 PR Closes #xx 但不在 In Review；In Progress 但 30 天无动静 → 提示而非擅动）。
6. 报告：输出 Agent Assessment（格式见下）。apply 模式下同时把每个 issue 的判定理由以评论落到该 issue（幂等：正文含 <!-- triage:v1 --> 标记，已有同版本标记的 issue 跳过重复评论）。

判定 rubric

agent:ready 需同时满足：

• 描述完备：有背景/动机 + 有可验收的完成标准（或可从 body 明确推出）+ 涉及的模块/文件可定位
• 无依赖阻塞：不依赖未完成的其他 issue；local_rules 中声明的依赖链（如分轮次架构演进）严格生效
• 低风险：不涉及不可逆操作、不涉及大范围 schema/架构决策、失败可回滚

needs:human 的典型信号：

• 开放性问题；多方案待拍板；与近期提交冲突（可能已部分完成）；验收标准写不出来
• 打 needs:human 时必须在评论中列出 1-3 个具体的、可回答的问题，不许只打标签

复杂度标记默认 S / M / L（代码变更范围 + 跨模块影响 + Schema 变更），写进补全区块，不映射时间；local_rules 有仓库自定规约时从之。

描述完备化区块模板

追加到 issue body 末尾（原文之后空一行），apply 模式用 gh issue edit --body-file（先取原 body 拼接，绝不整体重写）：

---
<!-- triage:v1 -->
## 🤖 Triage 补全（backlog-manager）

**背景补全**：<一段话，补足缺失的上下文；原文已清楚则写"原文已完备"并省略本行>
**验收标准**：
- [ ] <可勾选的完成判据，1-4 条>
**依赖**：<#issue 编号列表，或"无">
**复杂度**：S | M | L
**涉及模块**：<路径级定位>

Agent Assessment 报告格式（DRY-RUN 与 apply 通用）

# Agent Assessment <日期>

## 拟执行动作（DRY-RUN）/ 已执行动作（apply）
| # | issue | 动作 | 理由（一句话） |

## Todo 队列（≤ready_queue_max）
按序列出 + 各自的入选理由

## needs:human 清单
每项附具体提问

## 漂移修复
发现的失真 + 处理/建议

## 本轮跳过
已有 triage:v1 标记 / 无需变更的 issue 数

红线提醒

• Todo 超上限时，宁可降级最弱一张回 Backlog，不许扩容
• 对「疑似已被提交部分完成」的 issue：不擅自改描述，判 needs:human 并附上疑似相关的 commit hash
• 任何 gh 写命令失败：记录、跳过、继续，最后在报告里汇总失败项；不重试超过 1 次
• 出现新的 needs:human issue，或需要权限范围之外的操作时：暂停并向用户提问，不许自行扩权