droboticflow/docs/agents/issue-tracker.md

44 lines
2.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Issue tracker: Local Markdown
Issues and specs live as Markdown files in `.scratch/`.
## Conventions
- One feature per directory: `.scratch/<feature-slug>/`.
- Spec: `.scratch/<feature-slug>/spec.md`.
- One file per implementation ticket:
`.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`.
- Record triage state as a `Status:` line near the top.
Use the role strings in `triage-labels.md`.
- Append discussion under `## Comments`.
## Publish and fetch
To publish a spec or ticket to the local tracker (whether invoked by a skill or directly),
create the corresponding file under `.scratch/<feature-slug>/`, creating directories as needed.
To fetch a ticket, read the referenced Markdown file under `.scratch/<feature-slug>/`.
## Wayfinding operations
- Map: `.scratch/<effort>/map.md`, with Notes, Decisions-so-far, and Fog.
- Child ticket: `.scratch/<effort>/issues/NN-<slug>.md`.
- Record ticket type with `Type: research`, `prototype`, `grilling`, or `task`.
- Record dependencies with `Blocked by: NN, NN`.
- A ticket is unblocked when every listed dependency is resolved.
- Select open, unblocked, unclaimed tickets in numeric order.
- Claim a ticket by saving `Status: claimed` before starting work.
- Resolve it by appending `## Answer`, setting `Status: resolved`,
and adding a summary and link to the map's Decisions-so-far section.
The `claimed` and `resolved` statuses describe wayfinding execution;
they are separate from the five triage roles.
## 多代理同分支协作(2026-10-14 复盘沉淀)
一次特性中三个修复代理被误判死亡后"复活",同一 worktree 出现三写者;以下协议让下次不再临场发明:
1. **判死先验尸**:`send_message` 返回 "not found" 只算**未知**,不等于死亡。宣布同分支代理死亡前,必查其 worktree:`git log`(有无新提交)、`git status`(有无在途编辑)、文件 mtime、`ps`(go test / vite 等门禁进程)。探针失灵而代理存活的案例已发生两次。
2. **车道分工**:同分支多代理必须在票面 Comments 写"车道认领"——每道声明**文件域**(文件路径清单)、认领注记先落提交。共享文件规则:先落者赢,后到者 rebase 保双意图;跑门禁要干净树时用 stash(挂名 `lane-<x>`),跑完弹回。
3. **协调走票面**:子代理间 send_message 不可靠;票文件是唯一可靠信道。协调者指令(分工令/追问/背书)一律写进 `## Comments` 并提交,代理开工前先读票尾。