ongoing-task

---
name: ongoing-task
description: >
  Persist the current session's work as a resumable "task journal", or resume and
  continue iterating from an existing one. Use whenever the user wants to capture a
  long-running / multi-session effort so a future session continues without
  re-deriving — triggers include "save this as an ongoing task", "resume <name>",
  "继续这个任务", "把当前进展沉淀成长期任务", "下次接着做", "迭代任务", "/ongoing-task".
---

# ongoing-task — 长期任务沉淀与续作

把"当前会话的工作"沉淀成一份**可长期迭代的任务日志**，或从一份日志**恢复并继续迭代**。

核心目的：**让"未来的我"（可能几天后、全新会话、没有任何上下文）只读这份文档，就能不重新热身地继续干活。** 一切取舍围绕这个。

## 何时用

- 任务不是一锤子买卖，而是「看数据/现状 → 得结论 → 做改动 → 过段时间再看是否改善 → 再迭代」的循环。
- 用户说"把这个存成长期任务 / 下次接着做 / 继续 X 任务 / 沉淀一下 / 迭代"。
- 一项跨会话的分析、监控、重构、迁移、内容/SEO 计划等。

## 用法

```
/ongoing-task save <name>     # 把当前工作沉淀/更新成任务日志 <dir>/<name>.md
/ongoing-task resume <name>   # 读取该日志，复述现状，然后继续执行"下一步"
/ongoing-task list            # 列出所有任务日志 + 状态 + 最近更新
/ongoing-task                 # 无参数：上下文明显对应某份日志则 resume；否则问用户意图
```

`<name>` 用 kebab-case 战线名、不带日期（日期放文档内迭代日志）：`web-performance`、`signup-funnel`。

## 任务日志放哪（按当前项目自适应）

1. 项目已有 `claudedocs/` → 用 `claudedocs/ongoing-tasks/`。
2. 否则有 `docs/` → 用 `docs/ongoing-tasks/`。
3. 否则在仓库根建 `ongoing-tasks/`。
4. 不在 git 仓库 → 问用户放哪。

**不要**在该目录里生成 README —— 用法/模板的唯一真相源是本 skill，任务日志文件本身自带标题与说明、足以自解释。目录里只放任务日志（+ 复杂任务的支撑文档）。

## 文档模板（单一真相源）

每份任务日志遵循此结构。**重心是后三节**：当前结论（免得重新推导）、下一步（可直接执行）、迭代日志（留痕）；外加复现/取数方式（换个会话也能拿到同样数据）。

```markdown
# <任务名>

> **状态**: 🟢 进行中 | ⏸️ 暂停 | ✅ 已完成
> **最近更新**: YYYY-MM-DD
> **一句话**: 这个任务到底在追什么

## 🎯 目标
长期想达成什么。可量化的成功标准是什么。

## 🧭 复现 / 取数方式
- 数据源、工具、命令、查询模板（尽量可直接复制运行）
- 认证 / 访问限制（哪些数据拿不到、为什么）
- ⚠️ 密钥/token 绝不写进文档（这是会进 git 的文件）；写"问用户"或指向密钥位置

## 📚 支撑文档（可选，复杂任务才有）
- 表格列出本任务依赖的其它文档（PRD / 回归基准 / 详细迭代日志 / 调研），各一句话作用 + 何时看
- 用相对路径链接；本日志只做"控制塔"，细节留在支撑文档里、不重复

## 📌 当前结论（最新认知）
- 已确认的事实（带数字 / 证据）
- 已排除的假设（避免重复验证）

## ⚠️ 教训 / 陷阱
- 踩过的坑、被推翻的判断、反直觉的发现，下次别重复

## 🔧 已做的改动
- 日期 · 文件 · 改了什么 · 为什么 · 验证状态（已验证 / 待部署后验证）

## 🔜 下一步（可直接执行）
- [ ] 具体到「跑哪条查询 / 验证哪个数字 / 改哪个文件」
- [ ] 每项尽量带"成功标准"（什么数值算达标）

## 📜 迭代日志（倒序，最新在上）
### YYYY-MM-DD — 这次做了什么
看了什么数据 → 发现 → 决策。
```

## 两种形态：单文件 vs 索引型（叠加多文档）

- **单文件**：任务不复杂，一个 `.md` 装下全部（如 `web-performance.md`）。
- **索引型（推荐用于复杂任务）**：任务天然横跨多份文档（PRD、回归基准、详细迭代日志、调研报告）。这时主日志 `<name>.md` 当**控制塔/入口**——只放：目标、当前结论、下一步、📚 支撑文档链接；繁重细节（完整迭代记录、SQL Playbook、回归样本）留在各自的支撑文档里，主日志只链接、不复制。
  - 例：`key-items.md`（控制塔）→ 链接 `PRD-key-items-*.md`（设计）+ `keyitem-iteration-log.md`（每轮数据闭环 + 可复用查询）+ `keyitem-regression-*.md`（AI 质量基准）。
  - 好处：避免重复与漂移，单一真相源清晰；resume 时先读控制塔，需要细节再钻支撑文档。

## save 模式：怎么写出一份好日志

1. **定位文件** `<dir>/<name>.md`。存在就**更新**（不是覆盖重写）；不存在就按模板新建。
2. **从当前会话萃取**，逐节填充/更新：
   - 🎯 目标：新建时定，之后基本不动。
   - 🧭 复现/取数：把这次用的数据源/工具/命令/查询，写成**下次能直接复制运行**的形式；标注访问限制。**密钥不入文档。**
   - 📌 当前结论：并入本次确认的事实（带证据）；与旧结论冲突时**更新**旧的，并在迭代日志说明为何改判。
   - ⚠️ 教训/陷阱：这次踩的坑、被推翻的判断、反直觉发现 —— 文档最值钱的部分之一。
   - 🔧 已做的改动：日期·文件·改了什么·为什么·验证状态。
   - 🔜 下一步：本次结束时**最该做的事**，具体到查询/字段/文件，带成功标准。这是下次 resume 的入口。
   - 📜 迭代日志：最上面加一条 `### YYYY-MM-DD — 标题`，三两句"看了什么→发现→决策"。
3. **日期用绝对日期**（看环境里的今天），别写"昨天/上周"。状态与"最近更新"同步刷新。
4. 写完**一句话汇报**：沉淀到哪个文件、下一步是什么。
5. 若发现值得**跨会话自动记住**的原子事实，顺手也写进全局记忆（若该环境有 memory 机制），与任务日志互补。

## resume 模式：怎么续作

1. **完整读** `<dir>/<name>.md`（不要只扫一眼）。
2. **先复述**给用户：目标 / 当前结论 / 上次的下一步。让用户确认起点没跑偏。
3. **校验现状仍成立**：文档点名的文件/字段/查询可能已变。动手前先快速核对关键前提（改动是否已部署、查询字段是否还在），别拿过期结论硬推。
4. **执行"🔜 下一步"**。完成后**立刻按 save 模式写回**（更新结论/改动/下一步 + 加迭代日志条目），保持文档始终是最新可续作状态。
5. 一轮做完问用户是否满意 / 继续。**反复迭代直到用户满意**，每轮都更新文档。

## list 模式

扫 `<dir>/*.md`（跳过 `README.md`），每个列出：文件名、状态、最近更新、一句话目标。按最近更新倒序。

## 注意

- 这是个人迭代工作流，动作要省心：save 时不必逐字征求，按规则写好再汇报即可。
- 任务做完把状态改 ✅，但**不删文件**——历史结论仍有参考价值。
- 一个任务一个文件；别把多条不相关战线塞进一份。
- 本 skill 自身是公开、可迭代的：装在 `~/.claude/skills/ongoing-task/`，可作为独立 git 仓库发布到 GitHub 持续改进（见同目录 README）。