<!-- PROJECT_PLAN 模板 — 实现计划。复制为项目根 PROJECT_PLAN.md 或放 docs/。
     方法借自 superpowers/writing-plans：任务粒度 2–5 分钟、含精确路径+完整动作+验证步骤，
     写到"无项目上下文者也能照做"的程度。每项是可勾选 checkbox，做完即勾。 -->

# {{项目名称}} — 实现计划

> 设计获批后再写本计划。读者设定为"热心但无判断、无项目上下文"的执行者。
> 原则：TDD（先写测试）、YAGNI（不做没要求的）、DRY（不重复）。

## No-Placeholders 规则（强制）

- 计划里**不留** `{{占位}}`、`TODO`、`见上文`、`类似地`、`等等`。每个任务自带：精确文件路径 + 完整命令/代码 + 可观察的验证结果（具体数字/状态码/文件名）。
- 任务粒度 **2–5 分钟**。超过就拆分。
- 每个任务必须可独立验证：写清"跑什么命令、期望看到什么输出"。
- 失败的尝试要记到下方「失败尝试」节，不要默默删掉——这是最有价值的信息。

## 目标与验收

| 项 | 内容 |
|----|------|
| 目标（一句话） | {{完成后能做到的一件具体事}} |
| 验收标准 | {{可观察：如 `pytest` 全绿、`dvc repro` 无变更、指标 ≥ X}} |
| 非目标（YAGNI） | {{明确不做的范围，防止蔓延}} |

## 前置条件（Setup Required）

- [ ] 环境就绪：`poetry install` 或 `conda env create -f environment.yml`，验证 `python -c "import {{module}}"` 无报错。
- [ ] 数据就绪：`dvc pull` 后 `data/raw/` 存在 {{具体文件名}}；校验 `ls data/raw/` 含该文件。
- [ ] 需要的 env var / 密钥：{{KEY 名，不写值}}。

## 任务清单（垂直切片，按依赖排序）

> 每条是一条端到端可独立认领的路径（借 to-issues 垂直切片），不是横向按层切。

### 切片 1 — {{端到端能跑通的最小路径}}
- [ ] 1.1 在 `src/{{file}}.py` 新增函数 `{{fn(args) -> ret}}`：{{它做什么}}。
- [ ] 1.2 在 `tests/test_{{file}}.py` 写 `test_{{case}}`，断言 {{具体输入→具体输出}}。
- [ ] 1.3 验证：`poetry run pytest tests/test_{{file}}.py -q` → 期望 `1 passed`。

### 切片 2 — {{下一条独立路径}}
- [ ] 2.1 {{动作 + 精确路径}}。
- [ ] 2.2 验证：{{命令 + 期望输出}}。

## 失败尝试（边做边记，强制）

| 尝试 | 为何失败 | 结论/改用方案 |
|------|----------|---------------|
| {{做了什么}} | {{真实报错/原因}} | {{下一步}} |

## 关键决策（含理由）

| 决策 | 选项 | 选择 | 理由 |
|------|------|------|------|
| {{如建模框架}} | {{A / B}} | {{B}} | {{为什么}} |

## 阻塞与假设

- 假设：{{你默认成立、但未验证的前提}}。
- 阻塞：{{卡住的点 + 需要谁/什么来解}}。
