---
name: 05-learn
description: "极简知识复盘与避坑指南。在工作流闭环后，甄别并沉淀非平凡的高价值问题解决方案至 docs/solutions/。"
---

# 05-learn: 极简知识复盘与经验沉淀

在开发与审查完毕（`04-review` 完成）后，使用本技能进行轻量化复盘，形成项目的长期记忆与避坑指南。

## 价值门禁（先判断，后落笔）

**宁可留白，绝不制造文档垃圾。**

### ❌ 不值得记录的情况（符合任意一条即终止，不建文件）
- **低级失误**：手误拼写错误、少导了一个包、改了个变量名。
- **常识性知识**：官方文档第一页就能查到的普通 API 语法。
- **项目强耦合机械改动**：日常业务文案调整、简单的格式排版。
- **无根因分析**：代码改好了但不知道为什么好，无法给未来提供指导。

### ✅ 值得记录的情况（全部满足才落笔）
1. **非平凡 (Non-trivial)**：经过多轮排查、深挖源码或日志才定位的问题。
2. **具复发性 (Reusable)**：未来在本项目或类似项目中极可能再次遇到的隐患或坑点。
3. **有洞察力 (Insightful)**：能清晰指出根本诱因，并给出正确的防范范式。

## 执行流程

1. **评估价值**：
   - 回顾本次开发过程，自问：“本次是否有耗时深查、值得下次提前规避的技术坑？”
   - **若无**：直接输出一句话总结（例如：`本次任务均为常规特性开发，无特殊避坑经验需持久化。`），**结束流程**。
   - **若有**：进入第 2 步。
2. **编写极简避坑卡片**：
   - 调用 `artifact_helper({ repoRoot: ".", artifactType: "solution", topic: "<topic-name>", ensureDir: true })` 获取路径。
   - 写入 `docs/solutions/YYYY-MM-DD-<topic>.md`，内容仅包含 3 个核心要素：
     ```markdown
     # [问题简述] 避坑指南

     ## 1. 踩坑现象 (Symptom)
     出现何种报错、异常行为或静默失效。

     ## 2. 根本诱因 (Root Cause)
     深层机制是什么（如 Windows 路径转义、生命周期竞争等）。

     ## 3. 正确解法与防范 (Fix & Prevention)
     给出最小标准代码范式，说明如何一劳永逸预防。
     ```
3. **全流程终结 (Terminus)**：
   - 输出完整的项目开发闭环总结：
     - 需求产物 (`docs/brainstorms/`)
     - 计划产物 (`docs/plans/`)
     - 审查与测试证据 (`04-review`)
     - 沉淀经验 (`docs/solutions/`，如有)
   - 工作流完成。