# 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。