ring-health-docs/agents/issue-tracker.md

Issue tracker: Local Markdown

本工作区的 issue 与 spec 以 markdown 文件形式存放。

位置：工作区根目录的 .scratch/（即 d:\cherry\.scratch\），不在各个 repos/* 内部。 这样三个仓库的 issue 集中一处，不会因为切换仓库而丢失上下文。

Conventions

• 一个特性一个目录：.scratch/<feature-slug>/
• Spec 是 .scratch/<feature-slug>/spec.md
• 实施工单每个一张文件：.scratch/<feature-slug>/issues/<NN>-<slug>.md，从 01 开始编号， 不要写成一个合并的 tickets 文件
• 分诊状态记录为文件靠上的 Status: 行（取值见 triage-labels.md）
• 评论与讨论历史追加到文件底部的 ## Comments 标题下
• .scratch/ 不纳入版本控制；需要长期留存的结论要回写到 docs/（ring-health-docs 仓库）

When a skill says "publish to the issue tracker"

在 .scratch/<feature-slug>/ 下新建文件（目录不存在就创建）。

When a skill says "fetch the relevant ticket"

读取对应路径的文件。用户通常会直接给出路径或工单编号。

Wayfinding operations

供 /wayfinder 使用。地图是一份文件，每个工单是它的一个子文件。

• Map：.scratch/<effort>/map.md（正文为 Notes / Decisions-so-far / Fog）。
• Child ticket：.scratch/<effort>/issues/NN-<slug>.md，从 01 开始编号，正文写问题。 Type: 行记录工单类型（research/prototype/grilling/task）； Status: 行记录 claimed/resolved。
• Blocking：靠上的 Blocked by: NN, NN 行。当它列出的每个文件都是 resolved 时，该工单解除阻塞。
• Frontier：扫描 .scratch/<effort>/issues/，找未关闭、未阻塞、未被认领的文件；编号最小的优先。
• Claim：动手前先置 Status: claimed 并保存。
• Resolve：在 ## Answer 标题下追加答案，置 Status: resolved， 然后把一条上下文指针（要点 + 链接）追加到 map.md 的 Decisions-so-far。