# Issue 跟踪：本地 Markdown

本仓库的 issue 和规格说明以 Markdown 文件存放在 `.scratch/` 中。

## 约定

- 每个功能使用一个目录：`.scratch/<feature-slug>/`
- 规格说明文件为 `.scratch/<feature-slug>/spec.md`
- 实现 issue 每个 ticket 使用一个文件：`.scratch/<feature-slug>/issues/<NN>-<slug>.md`，从 `01` 开始编号；不要合并为单个 tickets 文件
- triage 状态记录在 issue 文件顶部附近的 `Status:` 行中（角色字符串见 `triage-labels.md`）
- 评论和对话历史追加到文件底部的 `## Comments` 标题下

## 技能要求“发布到 issue 跟踪系统”时

在 `.scratch/<feature-slug>/` 下创建文件；目录不存在时一并创建。

## 技能要求“获取相关 ticket”时

读取引用的文件路径。用户通常会直接提供路径或 issue 编号。

## Wayfinder 导航操作

Wayfinder 使用一个 map 文件和每个 ticket 对应的子文件。

- **Map**：`.scratch/<effort>/map.md`，正文包含 Notes、Decisions-so-far 和 Fog
- **子 ticket**：`.scratch/<effort>/issues/NN-<slug>.md`，从 `01` 开始编号；正文中的 `Type:` 行记录 ticket 类型（`research`/`prototype`/`grilling`/`task`），`Status:` 行记录 `claimed`/`resolved`
- **阻塞关系**：文件顶部附近的 `Blocked by: NN, NN` 行记录依赖。列出的所有文件都为 `resolved` 时，ticket 才算解除阻塞
- **前沿 ticket**：扫描 `.scratch/<effort>/issues/`，查找未关闭、未阻塞且未认领的 ticket；优先选择编号最小者
- **认领**：设置 `Status: claimed` 并保存
- **解决**：在 `## Answer` 标题下追加答案，设置 `Status: resolved`，然后在 `map.md` 的 Decisions-so-far 中追加上下文指针（摘要和链接）