# Issue tracker: Local Markdown

本仓库的事项和规格以 Markdown 文件保存在 `.scratch/`。

## 文件约定

- 每个功能一个目录：`.scratch/<feature-slug>/`。
- 规格文件：`.scratch/<feature-slug>/spec.md`。
- 实现事项：`.scratch/<feature-slug>/issues/<NN>-<slug>.md`，
  从 `01` 开始编号，每个事项一个文件。
- 分流状态写在事项文件顶部附近的 `Status:` 行；
  使用 `triage-labels.md` 中的标签字符串。
- 评论和讨论追加到文件底部的 `## Comments` 下。

## 发布和读取

技能要求“发布到 issue tracker”时，在对应功能目录中创建文件，
按需创建目录。

技能要求“获取相关 ticket”时，读取指定路径的事项文件。
仅提供编号时，在对应功能目录中定位。

## Wayfinding

供 `wayfinder` 使用，一个地图文件对应多个子事项文件。

- 地图：`.scratch/<effort>/map.md`，包含 Notes、
  Decisions-so-far 和 Fog。
- 子事项：`.scratch/<effort>/issues/<NN>-<slug>.md`，
  从 `01` 编号，正文记录待解决的问题。
- 类型：顶部的 `Type:` 行使用 research、prototype、grilling 或 task。
- 此流程的工作状态：`Status: open`、`Status: claimed`、
  `Status: resolved`。
- 依赖：顶部用 `Blocked by: NN, NN` 记录前置事项；
  所有前置事项均为 resolved 时解除阻塞。
- 选取：扫描当前 effort 的 issues 目录，按编号选择第一个
  open 且未被阻塞的事项。
- 领取：开始工作前写入 `Status: claimed` 并保存。
- 解决：在 `## Answer` 下追加结论，写入 `Status: resolved`，
  再向地图的 Decisions-so-far 追加结论摘要及事项链接。