engram-backlog-triage

适用场景

在以下情况下使用此技能：

• 对 Engram（或任何代码仓库）进行全面的待办事项审查
• 决定合并 / 请求修改 / 关闭 / 需要设计 / 批准问题
• 清理问题跟踪器中的噪声
• 确定下一步要处理的事项

---

维护者理念（Engram）

这些是不可妥协的产品价值。每项分流决策都必须符合这些价值。

原则	实际含义
零配置	安装后即可开箱即用。除安装外，无需必填标志、环境变量或其他设置。
本地优先	数据存储在 ~/.engram/engram.db。默认不依赖云服务。
单一二进制文件	只有一个 engram 二进制文件。无需守护进程、服务或其他进程。
终端优先	CLI 和 TUI 是主要的用户体验。不提供 Web 控制面板，也不使用 Electron。
精简适配器	插件脚本（Claude、OpenCode、Gemini、Codex）仅作为精简的衔接层——逻辑由 Go 核心负责。
问题优先	每个 PR 都必须关联一个带有 status:approved 标签的问题。没有已批准的问题，就不能提交 PR。
基于证据的评审	请求修改时提供具体、可执行的事项。不要只说“需要改进”。
严格控制范围	若没有充分理由，不接受扩大 Engram 涉及范围的功能。
小而专注的贡献	优先选择用 50 行代码解决一个问题的 PR，而不是用 500 行代码解决五个问题的 PR。
拒绝含糊不清或超出范围的工作	关闭范围蔓延的问题和 PR，避免 Engram 被改造成其他东西。

---

处理方式分类

为每个问题或 PR 恰好指定一种处理方式：

处理方式	使用时机
MERGE（合并）	PR 正确、范围明确、测试通过，且关联了已批准的问题。立即合并。
REQUEST CHANGES（请求修改）	PR 的思路正确，但需要进行具体修正。逐项列出。
CLOSE（关闭）	噪声、重复、含糊不清、超出范围、没有已批准的问题，或长期没有活动的过期事项。
NEEDS DESIGN（需要设计）	想法有效，但必须先做出架构决策，之后才适合提交 PR。先开启讨论或设计问题。
APPROVE ISSUE（批准问题）	问题有效、清晰、可复现/具体，且在范围内。添加 status:approved 标签。
REJECT ISSUE（拒绝问题）	含糊不清、重复、超出范围，或应该在 Discussions 中讨论。附上说明后关闭。

---

操作阶段

阶段 1 — 获取待办事项

# All open issues with labels and comments
gh issue list --repo <owner/repo> --state open \
  --json number,title,labels,author,comments,body \
  --limit 100

# All open PRs with labels and review state
gh pr list --repo <owner/repo> --state open \
  --json number,title,labels,author,body,reviews,commits \
  --limit 50

# Check a specific issue in detail
gh issue view <number> --repo <owner/repo> --json number,title,body,labels,comments

# Check a specific PR in detail
gh pr view <number> --repo <owner/repo> --json number,title,body,labels,files,reviews

阶段 2 — 对每个事项进行分类

针对每个问题，回答：

1. Is it a real bug with reproduction steps? → candidate for APPROVE ISSUE
2. Is it a clear feature with a problem statement? → candidate for APPROVE ISSUE
3. Is it vague, a question, or a discussion? → REJECT ISSUE (redirect to Discussions)
4. Is it a duplicate? → REJECT ISSUE (link original, close)
5. Does it break zero-config / local-first / single-binary? → REJECT ISSUE
6. Does it need architectural decision before a PR? → NEEDS DESIGN

针对每个 PR，回答：

1. Does it link a status:approved issue? → if not → CLOSE (process violation)
2. Does it have exactly one type:* label? → if not → REQUEST CHANGES
3. Do all 5 CI checks pass? → if not → REQUEST CHANGES (list failures)
4. Is the scope tight (one issue, minimal diff)? → if sprawling → REQUEST CHANGES
5. Does it follow conventional commits + branch naming? → if not → REQUEST CHANGES
6. Is the change correct and well-tested? → if yes → MERGE

阶段 3 — 从维护者评论中推断理念

查看问题评论中维护者的回复（关联身份为 MEMBER 或 OWNER）。提取：

• 维护者批准了什么，以及他们如何表述
• 维护者将哪些事项转移到了其他地方（例如，从 Questions 转到 Discussions）
• 维护者如何缩小范围（“最合适的做法：在 DOCS.md 中添加一个章节”）
• 维护者欢迎了哪些事项，哪些事项则暂缓处理（“我会保留这个问题，以便跟踪此事项”）

利用这些模式，根据维护者的实际立场校准分流决策，而不只是依据书面理念。

# Filter for maintainer responses
gh issue view <number> --repo <owner/repo> --json comments \
  --jq '.comments[] | select(.authorAssociation == "MEMBER" or .authorAssociation == "OWNER") | {author: .author.login, body: .body}'

阶段 4 — 确定优先级

在每个处置类别中对条目排序：

快速处理（立即行动）：

• 有明确复现步骤的真实 Bug，且尚无关联 PR
• 正确、范围明确，只需添加标签或进行小幅修复的 PR
• 准确且含义明确的文档 PR

流程阻塞项（修复流程）：

• 缺少 status:approved 关联的 PR（关闭并说明原因）
• 缺少 type:* 标签的 PR（请求修改）
• 等待超过 7 天且带有 status:needs-review 状态的问题

真实 Bug（高优先级问题）：

• 可复现的崩溃、数据丢失或核心工作流故障
• 收到多位不同用户确认评论的问题

架构提案（单独安排）：

• 标记为 NEEDS DESIGN 的问题
• 影响二进制文件接口、同步协议或插件契约的提案

噪声（立即关闭）：

• 没有复现步骤的问题
• 没有需求证据却会扩大范围的功能请求
• 应在 Discussions 中提出的问题
• 含糊不清的报告（“它无法正常工作”）

阶段 5 — 生成报告

输出结构化的分流报告：

## Triage Report — <repo> — <date>

### Summary
- Open issues: N | Open PRs: N
- To merge: N | To request changes: N | To close: N
- To approve: N | To reject: N | Needs design: N

### PRs

| # | Title | Disposition | Reason |
|---|-------|-------------|--------|
| 89 | fix(mcp): update config example | MERGE | Correct, scoped, CI pending only |
| 98 | feat(sync): selective export | REQUEST CHANGES | No approved issue linked |
| 80 | feat(nix): Introduce flake.nix | CLOSE | No approved issue; nix out of scope for single-binary |

### Issues

| # | Title | Disposition | Reason |
|---|-------|-------------|--------|
| 93 | Windows false positive (Defender) | APPROVE ISSUE | Real user-facing bug, 3 confirmations |
| 99 | FTS5 trigram SQL logic error | APPROVE ISSUE | Specific bug, reproducible |
| 104 | Project aliasing system | NEEDS DESIGN | Scope question: conflicts with local-first project name resolution |
| 97 | Auto-generate docs from memory | REJECT ISSUE | Vague scope, no concrete problem statement |
| 81 | Remove Projects / local-only notes | REJECT ISSUE | Ambiguous, belongs in Discussions |

### Suggested Comments

#### PR #N — REQUEST CHANGES
> Thanks for this! A few items before this can merge:
> - [ ] Link an approved issue (`Closes #N`) — no PR can merge without one
> - [ ] Add exactly one `type:*` label
> - [ ] Rebase on `main` to resolve the failing CI check

#### Issue #N — APPROVE ISSUE
> This is clear, reproducible, and in scope. Adding `status:approved` — feel free to open a PR linking this issue.

#### Issue #N — REJECT ISSUE
> Thanks for the report! This looks more like a question/discussion topic than a bug or feature request.
> Please continue the conversation in [Discussions](https://github.com/<owner/repo>/discussions).
> Closing this issue — feel free to re-open if you can reproduce it as a concrete bug with steps.

#### Issue #N — NEEDS DESIGN
> Good idea, but this touches the <area> architecture. Before a PR makes sense here,
> let's nail down the design. I'll leave this open for discussion — feel free to propose
> an approach in the comments.

---

快速操作命令

# Approve an issue (add status:approved)
gh issue edit <number> --repo <owner/repo> --add-label "status:approved"

# Add priority to an issue
gh issue edit <number> --repo <owner/repo> --add-label "priority:high"

# Close an issue with a comment
gh issue close <number> --repo <owner/repo> \
  --comment "Thanks! This looks like a discussion topic rather than a bug. Please continue in Discussions: https://github.com/<owner/repo>/discussions"

# Request changes on a PR
gh pr review <number> --repo <owner/repo> --request-changes \
  --body "Please link an approved issue (Closes #N) and add exactly one type:* label."

# Approve a PR
gh pr review <number> --repo <owner/repo> --approve \
  --body "Looks good — scoped, tested, and linked to the approved issue."

# Merge a PR (squash)
gh pr merge <number> --repo <owner/repo> --squash --delete-branch

# Add a label to a PR
gh pr edit <number> --repo <owner/repo> --add-label "type:bug"

# List issues needing review (no status:approved yet)
gh issue list --repo <owner/repo> --label "status:needs-review" --state open

---

可复用的提示词模板

复制此代码块，即可在任何仓库中应用分流工作流：

You are a maintainer triage agent. Your job is to audit the full open issue and PR backlog
for <owner/repo> and produce a disposition report.

## Maintainer Philosophy
<paste the philosophy table from this skill, adapted to the target repo>

## Steps
1. Fetch all open issues: `gh issue list --repo <owner/repo> --state open --json number,title,labels,author,comments,body --limit 100`
2. Fetch all open PRs: `gh pr list --repo <owner/repo> --state open --json number,title,labels,author,body,reviews --limit 50`
3. For each item, check for maintainer comments (authorAssociation: MEMBER or OWNER) to infer current stance.
4. Classify each item as: MERGE / REQUEST CHANGES / CLOSE / NEEDS DESIGN / APPROVE ISSUE / REJECT ISSUE
5. Prioritize within buckets: quick wins → process blockers → real bugs → architectural proposals → noise
6. Output a structured markdown report with a table per section (PRs, Issues) and suggested comment text for each action item.

## Constraints
- Never approve issues that are vague, duplicates, or belong in Discussions
- Never approve PRs without a linked status:approved issue
- Prefer closing noise over leaving it open and unresolved
- Be specific in REQUEST CHANGES — list each item as a checkbox
- Proposed comments must be warm but clear: acknowledge the contribution, explain the reason, offer a path forward

---

权衡与假设

• 理念是推断得出的，而非计算得出的。 维护者评论才是判断依据，书面理念仅供参考。如有冲突，以评论为准。
• PR 必须先有 Issue，这一点不可妥协。 未关联 status:approved Issue 的 PR 一律执行 CLOSE，而非 REQUEST CHANGES，因为贡献者完全跳过了流程。
• 噪声应予以关闭，而非置之不理。 保留没有可执行内容的开放 Issue，会让贡献者认为可以容忍低质量内容。
• NEEDS DESIGN 是有效且不会阻塞流程的操作。 它传达的是“想法不错，但时机不对”，而非拒绝贡献者。
• 此技能针对 Engram 的工作流。 将可复用提示词应用于其他仓库时，请调整理念表和标签系统。