Local-Cursor/internal/skills/builtin/fd-engineering/references/todo.md

# Hierarchical TODO protocol

Use for planning, multi-step work, and resumption. The effective protocol plan and its TODO are authoritative; no host task board or plan generator is required. Persist complex work in the single record described in [task-record.md](task-record.md). A short task can keep its plan and steps in conversation.

## Structure and identifiers

Group work by outcome or work package, then subtasks and independently verifiable actions as useful. Do not force three levels or split every edit into a new item. Each executable leaf needs an action, expected result, and verification method; note dependencies when order alone is insufficient. Parent items state the outcome and any additional acceptance condition. For new features prefer a first parent representing the smallest usable user path through the required layers, with build/integration/validation children, then expand variants. A component milestone alone is not proof that the user path works.

Use stable identifiers such as 1, 1.1, and 1.1.1 for dependencies, checks, and revisions. Add a new unused child/sibling ID rather than renumbering existing references. A materially changed or superseded item retains its history and replacement mapping; adding detail is not permission to expand scope. Keep the current item and next action identifiable.

## States and completion

Write task records and status labels in Chinese. Only 完成 uses a checked box.

| State | Meaning |
|---|---|
| 待办 | Not started; dependencies or approval may still be pending |
| 进行中 | Work is actively underway |
| 待验证 | Work produced a result, but its required checks are incomplete or stale |
| 完成 | Expected result and applicable acceptance/checks are supported by actual evidence |
| 失败 | An attempted action or check failed; retain result and next diagnostic/fix |
| 受阻 | A required condition/capability is missing; record it and the resume trigger |
| 取消 | Deliberately removed or superseded with reason and acceptance impact recorded |

A parent is complete only when every still-required child is complete and its own acceptance is met. Failed, blocked, unrun, or pending-verification children cannot count as complete. Do not calculate completion merely from box counts. Summarize the actual limiting child in the parent status; a mixed subtree need not share one state.

Cancellation is unchecked and is not success. If it removes approved scope or a required acceptance/check, record and obtain approval of the affected revision before treating that child as no longer required. Never drop checks, cancel failed work, or change history to manufacture completion.

## Progress and evidence

After a meaningful work unit, record real changes/checks and update the related leaf, affected parents, current pointer, and next action. Keep updates concise; no per-edit timestamps or repeated full checklists are required. After approval, continue through available dependencies and checks without asking whether every step succeeded.

Reference actual commands/results or artifact evidence from verification entries. Code generation alone is not verified behavior. A failed check stays failed until a meaningful fix and successful rerun; unavailable checks remain unverified with impact, not completed. Required manual acceptance remains pending unless the effective plan legitimately changes.

If later edits invalidate a prior check, retain the old evidence and mark affected items 待验证 until rerun. On resumption reconcile files, dependencies, approval, recent revisions, and evidence before trusting completed boxes. Do not mark unknown prior work complete or blindly restart all finished work.

## Example record

This illustrates a mixed incomplete subtree, not actual executed work.

~~~markdown
- [ ] 1 缓存修复与验收 — 进行中；验收：离线可读且写入失败不丢失旧值
  - [x] 1.1 核对现有读写路径 — 完成；证据：研究 R1 的文件与调用链
  - [ ] 1.2 修复原子写入 — 待验证
    - 行动：沿用现有文件替换能力修改写入路径
    - 预期：写入失败仍可读取旧值；依赖：1.1
    - 验证：运行对应回归用例；当前证据：V1 仅记录改动，检查尚未运行
  - [ ] 1.3 验证目标环境 — 受阻；依赖：1.2；缺少测试设备，到位后恢复

当前步骤：1.2
下一步：运行约定回归；不能因 1.1 完成就勾选父任务 1
~~~

## Revisions and closure

Routine in-scope implementation details need no new approval. Preserve the approved plan and append substantive revisions, affected IDs, reason, impact, replacement, and approval; use [workflow.md](workflow.md) for the boundary.

Close against acceptance as complete, partial, or blocked with evidence and remaining IDs. Review findings and UI/UX preview cleanup can be TODO items when relevant; opening a file, generating a plan, or reaching the final response does not itself close the task.