grove-issues

Grove Issues

将零散的想法整理成清晰的问题待办列表。你会收到一份杂乱的 TODO 列表，并将其整理成标签规范、结构清晰的 GitHub 问题，可直接添加到 Lattice 看板。

何时激活

• 用户在一条消息中提供一批 TODO、任务或想法
• 用户明确调用 /grove-issues
• 用户说类似“为这些创建问题”或“把这些整理成工单”的话
• 用户粘贴了一份希望纳入跟踪的事项列表

---

工作流程

Brain Dump → Parse → Deduplicate → Create Issues → Label → Report

第 1 步：解析零散的想法

将用户的消息拆分成独立且可执行的问题。每个问题应代表一项工作。如果某个 TODO 范围太广，就将其拆分。如果两个 TODO 内容相同，就将它们合并。

解析提示：

• 编号列表 → 每项对应一个问题
• 项目符号列表 → 每个项目符号对应一个问题
• 由换行分隔的段落 → 每段对应一个问题
• 由逗号分隔的事项 → 每项对应一个问题
• 意识流式表达 → 自行判断并按逻辑边界拆分

第 2 步：检查重复项

创建任何问题前，先搜索现有的未关闭问题，检查是否有重叠：

gh issue list --state open --limit 100 --json number,title | jq -r '.[].title'

如果某个 TODO 与现有问题高度匹配，就跳过，并在报告中注明现有问题编号。不要创建重复项。

第 3 步：确定标签

每个问题最多添加 3 个标签：

组件标签（选择 1-3 个）

标签	适用场景
lattice	框架、单体仓库、共享基础设施、引擎包
heartwood	身份验证、会话、OAuth、身份
arbor	管理面板、后端 API、管理仪表盘
amber	图片、CDN、R2 存储、JXL、媒体流水线
clearing	状态页、运行状况监控、正常运行时间
shade	AI 爬虫防护、机器人防御、速率限制
plant	定价、计费、LemonSqueezy、店面、注册
ivy	电子邮件、Resend、通知、消息传递
foliage	主题、设计令牌、按租户自定义
curio	博物馆展品、内容展示、留言簿
meadow	社交功能、社区动态
forests	森林页面、社区林地、房产展示
vine	内容关系、页边注、连接
graft	功能开关、渐进式发布、A/B 测试
petal	内容审核、CSAM 检测、PhotoDNA
lumen	AI 助手、大模型路由、AI 网关
mycelium	MCP 服务、服务间网络
patina	备份、冷存储、数据保留
landing	落地页、营销页面、知识库

模式标签（选择 0-2 个，可与组件标签并用）

模式是可复用的架构解决方案。问题涉及实现或扩展某个模式时，添加相应标签。

标签	适用场景
pattern:firefly	短暂存在的服务基础设施（ignite、illuminate、fade 生命周期）
pattern:loom	Durable Objects 协调（SessionDO、TenantDO、PostDO）
pattern:prism	玻璃拟态设计系统、季节性主题、UI 图层
pattern:sentinel	负载测试、规模验证、逐步升压测试
pattern:songbird	提示词注入防护（canary、kestrel、robin 层）
pattern:threshold	速率限制、滥用防范、分级响应

类型标签（必须恰好选择 1 个）

标签	适用场景
bug	功能损坏或行为异常
feature	尚不存在的新功能
enhancement	改进现有功能
security	安全问题、漏洞、安全加固
documentation	文档、指南、帮助文章

优先级（仅在用户明确说明时设置）

不要猜测优先级。只有用户明确表示某事项紧急、关键或优先级较低时，才设置优先级。

第 4 步：编写问题正文

每个问题都使用此模板：

## Summary
[1-3 sentences describing what needs to be done and why]

## Acceptance Criteria
- [ ] [Specific, verifiable criterion]
- [ ] [Another criterion]
- [ ] [Keep to 3-6 items]

## Context
- [Relevant technical context]
- [Dependencies or related issues if known]
- [Any constraints mentioned by the user]

写作指南：

• 摘要应以通俗语言回答“是什么”和“为什么”——非工程师也应能看懂第一句话
• 验收标准应使用复选框条目，并且可以验证是否已完成
• 上下文为可选项，但很有帮助——技术细节（文件路径、模式、缩写）适合写在这里
• 正文总长度控制在 20 行以内。简洁胜过面面俱到。
• 不要用套话填充内容。如果没有有用的上下文，就跳过该部分。

第 5 步：创建问题

gh issue create \
  --title "Title in imperative mood" \
  --body "$(cat <<'EOF'
## Summary
...

## Acceptance Criteria
- [ ] ...

## Context
- ...
EOF
)" \
  --label "component1,type1"

标题指南：

• 先用通俗语言——面向浏览项目看板的项目负责人，而不是实现者
• 使用祈使语气：“Add X”，而不是“Adding X”或“X should be added”
• 格式：Service: what happens in plain english（例如，“Plant: fix broken image on pricing page”）
• 尽可能控制在 60 个字符以内
• 不要添加 [FEATURE] 或 [BUG] 前缀（分类由标签处理）
• 不要使用 Grove 服务名称以外的行话或缩写——标题中不要出现 HMR、PKCE、DO、SSR、CSRF 等。请展开说明，或改用通俗语言表达。（技术细节应放在正文中。）
• **自检：**阅读每个标题并问自己：“如果看板上还有 100 个其他问题，不点进去，我能立刻理解这个标题吗？” 如果不能，就重写。

好标题与坏标题示例：

不好（充斥行话）	好（通俗易懂）
Hybrid dev mode: HMR + service binding fidelity	Dev mode: support live reload alongside real service bindings
Thorn behavioral: finish remaining wiring	Thorn: connect remaining rate-limit and label checks
Graduate Reeds (comments) out of greenhouse	Reeds: make comments a full production feature
Implement Queen coordinator Durable Object	Queen: build the coordinator that manages background workers

第 6 步：汇报结果

创建所有问题后，向用户提供一张摘要表：

Created X issues:

| # | Title | Labels |
|---|-------|--------|
| #531 | Add glass overlay to Forest page | forests, enhancement |
| #532 | Fix tooltip positioning on mobile | lattice, bug |
...

Skipped (duplicates of existing issues):
- "Cache purge tool" → already tracked in #527

---

边界情况

模糊的 TODO

如果 TODO 太模糊，无法据此创建一个好问题（“修好那个东西”“让它变得更好”），请向用户澄清，而不是创建一个糟糕的问题。将模糊的事项归类后一次性询问。

超大批次（20+）

对于超大批次，请分批创建问题，每批 10 个，以避免触发速率限制。批次之间暂停一下。

优先级混杂

如果用户将某些事项标记为紧急／优先处理，将其他事项标记为待办，请在上下文中注明，但除非用户明确使用优先级相关措辞，否则不要应用优先级标签。

临时构想中的实现细节

如果用户说明了如何实现（而不只是要做什么），请将这些细节记录在“上下文”部分。验收标准仍应关注结果，而不是实现方式。

---

反模式

不要这样做：

• 不要创建只有标题、没有正文的问题
• 不要添加超过 3 个组件标签（如果涉及所有内容，可能应该使用 lattice）
• 不要猜测无法验证的验收标准。“运行良好”不是标准，“在移动视口中正确呈现”才是。
• 不要为已经完成的事项创建问题
• 不要用“代码有完善的文档”或“测试通过”等通用标准来凑数
• 除非用户明确表示某事项至关重要／紧急，否则不要添加 priority-critical

---

示例

用户说：

好的，我需要：修复定价页面上的损坏图片，为知识库添加深色模式切换开关，为 blog-engine 接入新的健康检查端点，之后还应该考虑为 meadow 添加 RSS 订阅源

你创建：

1. “修复定价页面上的损坏图片” — plant、bug
2. “为知识库添加深色模式切换开关” — landing、enhancement
3. “将 blog-engine 的健康检查端点接入 Clearing” — clearing、feature
4. “为 Meadow 添加 RSS 订阅源支持” — meadow、feature

每个问题都应包含恰当的摘要、验收标准和上下文。

---

清爽的待办列表让人心境平和。把混乱变清晰。