39 lines
2.0 KiB
Markdown
39 lines
2.0 KiB
Markdown
# 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。
|