file-todos

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

File-Based Todo Tracking Skill

基于文件的待办事项跟踪Skill

Overview

概述

The

todos/

directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.

This skill should be used when:

Creating new todos from findings or feedback
Managing todo lifecycle (pending → ready → complete)
Triaging pending items for approval
Checking or managing dependencies
Converting PR comments or code findings into tracked work
Updating work logs during todo execution

todos/

目录包含一个基于文件的跟踪系统，用于管理代码审查反馈、技术债务、功能请求和工作项。每个待办事项都是一个带有YAML前置元数据和结构化章节的Markdown文件。

应在以下场景使用此Skill：

根据发现的问题或反馈创建新的待办事项
管理待办事项生命周期（pending → ready → complete）
对pending状态的项进行分类处理以获得批准
检查或管理依赖关系
将PR评论或代码问题转换为可跟踪的工作项
在待办事项执行期间更新工作日志

File Naming Convention

文件命名规范

Todo files follow this naming pattern:

{issue_id}-{status}-{priority}-{description}.md

Components:

issue_id: Sequential number (001, 002, 003...) - never reused
status:
```
pending
```
(needs triage),
```
ready
```
(approved),
```
complete
```
(done)
priority:
```
p1
```
(critical),
```
p2
```
(important),
```
p3
```
(nice-to-have)
description: kebab-case, brief description

Examples:

001-pending-p1-mailer-test.md
002-ready-p1-fix-n-plus-1.md
005-complete-p2-refactor-csv.md

待办事项文件遵循以下命名模式：

{issue_id}-{status}-{priority}-{description}.md

组成部分：

issue_id：连续编号（001、002、003...）- 绝不重复使用
status：
```
pending
```
（需要分类处理）、
```
ready
```
（已批准）、
```
complete
```
（已完成）
priority：
```
p1
```
（关键）、
```
p2
```
（重要）、
```
p3
```
（锦上添花）
description：短横线分隔的小写格式，简短描述

示例：

001-pending-p1-mailer-test.md
002-ready-p1-fix-n-plus-1.md
005-complete-p2-refactor-csv.md

File Structure

文件结构

Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at todo-template.md as a starting point when creating new todos.

Required sections:

Problem Statement - What is broken, missing, or needs improvement?
Findings - Investigation results, root cause, key discoveries
Proposed Solutions - Multiple options with pros/cons, effort, risk
Recommended Action - Clear plan (filled during triage)
Acceptance Criteria - Testable checklist items
Work Log - Chronological record with date, actions, learnings

Optional sections:

Technical Details - Affected files, related components, DB changes
Resources - Links to errors, tests, PRs, documentation
Notes - Additional context or decisions

YAML frontmatter fields:

yaml

---
status: ready              # pending | ready | complete
priority: p1              # p1 | p2 | p3
issue_id: "002"
tags: [rails, performance, database]
dependencies: ["001"]     # Issue IDs this is blocked by
---

每个待办事项都是一个带有YAML前置元数据和结构化章节的Markdown文件。创建新待办事项时，请以todo-template.md模板为起点。

必填章节：

问题陈述 - 什么功能损坏、缺失或需要改进？
调查结果 - 调查结果、根本原因、关键发现
提议的解决方案 - 多个选项，包含优缺点、工作量、风险
推荐行动 - 清晰的计划（在分类处理时填写）
验收标准 - 可测试的检查清单项
工作日志 - 按时间顺序记录的日期、操作、经验总结

可选章节：

技术细节 - 受影响的文件、相关组件、数据库变更
资源 - 错误、测试、PR、文档的链接
备注 - 额外的上下文或决策

YAML前置元数据字段：

yaml

---
status: ready              # pending | ready | complete
priority: p1              # p1 | p2 | p3
issue_id: "002"
tags: [rails, performance, database]
dependencies: ["001"]     # 此待办事项被编号为001的项阻塞
---

Common Workflows

常见工作流

Creating a New Todo

创建新待办事项

To create a new todo from findings or feedback:

Determine next issue ID:

ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1

Copy template:

cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md

Edit and fill required sections:
- Problem Statement
- Findings (if from investigation)
- Proposed Solutions (multiple options)
- Acceptance Criteria
- Add initial Work Log entry
Determine status:
```
pending
```
(needs triage) or
```
ready
```
(pre-approved)
Add relevant tags for filtering

When to create a todo:

Requires more than 15-20 minutes of work
Needs research, planning, or multiple approaches considered
Has dependencies on other work
Requires manager approval or prioritization
Part of larger feature or refactor
Technical debt needing documentation

When to act immediately instead:

Issue is trivial (< 15 minutes)
Complete context available now
No planning needed
User explicitly requests immediate action
Simple bug fix with obvious solution

根据发现的问题或反馈创建新待办事项：

确定下一个issue ID：

ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1

复制模板：

cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md

编辑并填写必填章节：
- 问题陈述
- 调查结果（如果来自调查）
- 提议的解决方案（多个选项）
- 验收标准
- 添加初始工作日志条目
确定状态：
```
pending
```
（需要分类处理）或
```
ready
```
（预先批准）
添加相关标签以便过滤

何时创建待办事项：

需要超过15-20分钟的工作
需要研究、规划或考虑多种方法
与其他工作存在依赖关系
需要经理批准或优先级排序
属于较大功能或重构的一部分
需要文档记录的技术债务

何时应立即处理而非创建待办事项：

问题微不足道（<15分钟）
当前具备完整上下文
无需规划
用户明确要求立即行动
有明显解决方案的简单bug修复

Triaging Pending Items

分类处理Pending状态的项

To triage pending todos:

List pending items:
```
ls todos/*-pending-*.md
```
For each todo:
- Read Problem Statement and Findings
- Review Proposed Solutions
- Make decision: approve, defer, or modify priority
Update approved todos:
- Rename file:
```
mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
```
- Update frontmatter:
```
status: pending
```
  →
```
status: ready
```
- Fill "Recommended Action" section with clear plan
- Adjust priority if different from initial assessment
Deferred todos stay in
```
pending
```
status

Use slash command:

/triage

for interactive approval workflow

分类处理pending状态的待办事项：

列出pending状态的项：
```
ls todos/*-pending-*.md
```
对每个待办事项：
- 阅读问题陈述和调查结果
- 审阅提议的解决方案
- 做出决策：批准、推迟或修改优先级
更新已批准的待办事项：
- 重命名文件：
```
mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
```
- 更新前置元数据：
```
status: pending
```
  →
```
status: ready
```
- 填写"推荐行动"章节，明确计划
- 如果与初始评估不同，调整优先级
被推迟的待办事项保持
```
pending
```
状态

使用斜杠命令：

/triage

用于交互式批准工作流

Managing Dependencies

管理依赖关系

To track dependencies:

yaml

dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
dependencies: []               # No blockers - can work immediately

To check what blocks a todo:

bash

grep "^dependencies:" todos/003-*.md

To find what a todo blocks:

bash

grep -l 'dependencies:.*"002"' todos/*.md

To verify blockers are complete before starting:

bash

for dep in 001 002 003; do
  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done

跟踪依赖关系：

yaml

dependencies: ["002", "005"]  # 此待办事项被编号为002和005的项阻塞
dependencies: []               # 无阻塞 - 可立即开展工作

检查哪些项阻塞了某个待办事项：

bash

grep "^dependencies:" todos/003-*.md

查找某个待办事项阻塞了哪些项：

bash

grep -l 'dependencies:.*"002"' todos/*.md

开始工作前验证阻塞项是否已完成：

bash

for dep in 001 002 003; do
  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done

Updating Work Logs

更新工作日志

When working on a todo, always add a work log entry:

markdown

undefined

处理待办事项时，务必添加工作日志条目：

markdown

undefined

YYYY-MM-DD - Session Title

YYYY-MM-DD - 会话标题

By: Claude Code / Developer Name

Actions:

Specific changes made (include file:line references)
Commands executed
Tests run
Results of investigation

Learnings:

What worked / what didn't
Patterns discovered
Key insights for future work


Work logs serve as:
- Historical record of investigation
- Documentation of approaches attempted
- Knowledge sharing for team
- Context for future similar work

作者： Claude Code / 开发者姓名

操作：

所做的具体更改（包含文件:行号引用）
执行的命令
运行的测试
调查结果

经验总结：

哪些方法有效/无效
发现的模式
对未来工作的关键见解


工作日志的作用：
- 调查的历史记录
- 尝试过的方法的文档记录
- 团队知识共享
- 未来类似工作的上下文参考

Completing a Todo

标记待办事项为已完成

To mark a todo as complete:

Verify all acceptance criteria checked off
Update Work Log with final session and results

Rename file:

mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md

Update frontmatter:
```
status: ready
```
→
```
status: complete
```

Check for unblocked work:

grep -l 'dependencies:.*"002"' todos/*-ready-*.md

Commit with issue reference:
```
feat: resolve issue 002
```

将待办事项标记为已完成：

验证所有验收标准都已勾选
更新工作日志，添加最终会话和结果

重命名文件：

mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md

更新前置元数据：
```
status: ready
```
→
```
status: complete
```

检查被解锁的工作：

grep -l 'dependencies:.*"002"' todos/*-ready-*.md

提交时引用issue：
```
feat: resolve issue 002
```

Integration with Development Workflows

与开发工作流的集成

Trigger	Flow	Tool
Code review	`/workflows:review` → Findings → `/triage` → Todos	Review agent + skill
PR comments	`/resolve_pr_parallel` → Individual fixes → Todos	gh CLI + skill
Code TODOs	`/resolve_todo_parallel` → Fixes + Complex todos	Agent + skill
Planning	Brainstorm → Create todo → Work → Complete	Skill
Feedback	Discussion → Create todo → Triage → Work	Skill + slash

触发条件	流程	工具
代码审查	`/workflows:review` → 调查结果 → `/triage` → 待办事项	审查Agent + Skill
PR评论	`/resolve_pr_parallel` → 单独修复 → 待办事项	gh CLI + Skill
代码TODOs	`/resolve_todo_parallel` → 修复 + 复杂待办事项	Agent + Skill
规划	头脑风暴 → 创建待办事项 → 执行 → 完成	Skill
反馈	讨论 → 创建待办事项 → 分类处理 → 执行	Skill + 斜杠命令

Quick Reference Commands

快速参考命令

Finding work:

bash

undefined

查找工作项：

bash

undefined

List highest priority unblocked work

列出优先级最高且无阻塞的工作项

grep -l 'dependencies: []' todos/-ready-p1-.md

List all pending items needing triage

列出所有需要分类处理的pending状态项

ls todos/-pending-.md

Find next issue ID

查找下一个issue ID

ls todos/ | grep -o '^[0-9]+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'

Count by status

按状态统计数量

for status in pending ready complete; do echo "$status: $(ls -1 todos/-$status-.md 2>/dev/null | wc -l)" done


**Dependency management:**
```bash

for status in pending ready complete; do echo "$status: $(ls -1 todos/-$status-.md 2>/dev/null | wc -l)" done


**依赖关系管理：**
```bash

What blocks this todo?

哪些项阻塞了这个待办事项？

grep "^dependencies:" todos/003-*.md

What does this todo block?

这个待办事项阻塞了哪些项？

grep -l 'dependencies:."002"' todos/.md


**Searching:**
```bash

grep -l 'dependencies:."002"' todos/.md


**搜索：**
```bash

Search by tag

按标签搜索

grep -l "tags:.rails" todos/.md

Search by priority

按优先级搜索

ls todos/-p1-.md

Full-text search

全文搜索

grep -r "payment" todos/

undefined

grep -r "payment" todos/

undefined

Key Distinctions

关键区别

File-todos system (this skill):

Markdown files in
```
todos/
```
directory
Development/project tracking
Standalone markdown files with YAML frontmatter
Used by humans and agents

Rails Todo model:

Database model in
```
app/models/todo.rb
```
User-facing feature in the application
Active Record CRUD operations
Different from this file-based system

TodoWrite tool:

In-memory task tracking during agent sessions
Temporary tracking for single conversation
Not persisted to disk
Different from both systems above

文件型待办事项系统（此Skill）：

位于
```
todos/
```
目录中的Markdown文件
用于开发/项目跟踪
带有YAML前置元数据的独立Markdown文件
供人类和Agent使用

Rails Todo模型：

位于
```
app/models/todo.rb
```
中的数据库模型
应用中的用户面向功能
Active Record增删改查操作
与此基于文件的系统不同

TodoWrite工具：

Agent会话期间的内存中任务跟踪
单一会话的临时跟踪
不持久化到磁盘
与上述两个系统均不同