议题追踪器：GitHub¶

本仓库的议题和 PRD 以 GitHub 议题的形式存放在 debpalash/VoiceStudio 上。所有操作都使用 gh CLI。

约定¶

• 创建议题：gh issue create --title "..." --body "..."。多行正文请使用 heredoc。
• 查看议题：gh issue view <number> --comments，使用 jq 过滤评论，并同时获取标签。
• 列出议题：gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]' 并配合适当的 --label 和 --state 过滤器。
• 评论议题：gh issue comment <number> --body "..."
• 添加/移除标签：gh issue edit <number> --add-label "..." / --remove-label "..."
• 关闭：gh issue close <number> --comment "..."

通过 git remote -v 推断仓库——在克隆内部运行时，gh 会自动执行此操作。

将拉取请求作为分类入口¶

PR 作为请求入口：否。 （如果本仓库将外部 PR 视为功能请求，请设置为 yes；/triage 会读取此标志。）

当设置为 yes 时，PR 会像议题一样经历相同的标签和状态，使用 gh pr 对应的命令：

• 查看 PR：使用 gh pr view <number> --comments 查看评论，以及 gh pr diff <number> 查看 diff。
• 列出供分类的外部 PR：gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments，然后仅保留 authorAssociation 为 CONTRIBUTOR、FIRST_TIME_CONTRIBUTOR 或 NONE 的 PR（丢弃 OWNER/MEMBER/COLLABORATOR）。
• 评论/添加标签/关闭：gh pr comment、gh pr edit --add-label/--remove-label、gh pr close。

GitHub 在议题和 PR 之间共享同一个编号空间，因此一个单独的 #42 可能是其中任一种——请使用 gh pr view 42 解析，若失败则回退到 gh issue view 42。

覆盖通用流程的仓库规则¶

这些规则来自 CLAUDE.md，适用于技能在此处打开或合并的任何内容：

• 合并前收集机器人评审。 CodeRabbit 和 Greptile 会自动评审每个 PR。阅读它们的内联评论——通过 gh api repos/debpalash/VoiceStudio/pulls/<n>/comments 并按机器人登录名过滤——然后在合并前进行分类。切勿在存在未读的 Critical/P1 时合并。这适用于技能打开的 PR，而不仅仅是人类提交的 PR。
• 切勿在存在未解决已知发现时合并。 在 PR 分支上修复它们；不要先合并再修复，也不要将其作为评论留给其他人。
• 每次合并都要把关，要求“Tests (backend + frontend)”检查通过且 PR 为 MERGEABLE。
• 始终向 gh pr merge --squash 传入显式的 --body。 如果让其自动生成，会复制每条提交信息，包括任何 agent 的 Co-authored-by: 或“Generated with”行，而本仓库禁止这些内容（参见 CLAUDE.md 中的归属规则）。
• 实现任何社区报告的修复之前，先检查开放的 PR 队列——可能已有贡献者提交过。

当技能说“发布到议题追踪器”时¶

创建一个 GitHub 议题。

当技能说“获取相关工单”时¶

运行 gh issue view <number> --comments。

寻路操作¶

由 /wayfinder 使用。地图（map） 是一个单独的议题，其子议题作为工单。

• 地图（Map）：一个带有 wayfinder:map 标签的单独议题，包含 Notes / Decisions-so-far / Fog 正文。gh issue create --label wayfinder:map。
• 子工单（Child ticket）：一个作为 GitHub 子议题链接到地图的议题（在子议题端点上使用 gh api）。在未启用子议题的情况下，将子议题添加到地图正文的任务列表中，并在子议题正文顶部加上 Part of #<map>。标签：wayfinder:<type>（research/prototype/grilling/task）。一旦被认领，该工单会分配给主导开发者。
• 阻塞（Blocking）：GitHub 的原生议题依赖——即规范的、UI 可见的表示。使用 gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id> 添加一条边，其中 <blocker-db-id> 是阻塞者的数字数据库 ID（gh api repos/<owner>/<repo>/issues/<n> --jq .id，不是 #number 或 node_id）。GitHub 会报告 issue_dependencies_summary.blocked_by（仅包括未关闭的阻塞者——即实时闸门）。在依赖不可用时，回退到在子工单正文顶部添加一行 Blocked by: #<n>, #<n>。当所有阻塞者都关闭时，工单即解除阻塞。
• 前沿查询（Frontier query）：列出地图的未关闭子议题（gh issue list --state open，限定在地图的子议题/任务列表范围内），丢弃任何带有未关闭阻塞者（issue_dependencies_summary.blocked_by > 0，或 Blocked by 行中的未关闭议题）或已指派负责人的子议题；按地图顺序取第一个。
• 认领（Claim）：gh issue edit <n> --add-assignee @me——会话中的第一次写入。
• 解决（Resolve）：gh issue comment <n> --body "<answer>"，然后 gh issue close <n>，再向地图的 Decisions-so-far 追加一个上下文指针（gist + 链接）。