cs-learn 用于把工程实践中踩过的坑和发现的好做法沉淀为可检索的 learning 文档，避免团队重复解决同一问题。它分两条轨道：pitfall 记录问题、根因与解法；knowledge 记录最佳实践、工作流改进与可复用模式。两者都写入 .codestable/compound/，文件命名 YYYY-MM-DD-learning-{slug}.md，frontmatter 带 doc_type: learning。
触发方式包括：完成 feature 工作流时由 cs-feat-accept 询问、完成 issue 工作流时由 cs-issue-fix 询问、用户主动说“沉淀知识”“learning”“把这次经验记下来”，以及不在 feature/issue 内但耗时较久的一次性难题。推荐只需一句话，用户拒绝即跳过。
工作流分阶段：识别来源（自动提取来源类型、关联产物并粗分轨道，不明确时问用户）；查重叠与意图分流（含“改/更新/补充”或指向旧文档则走更新，否则用搜索工具查相近旧文档并列出候选）；提炼要点（一次一个问题，坑点轨道问现象、无效解法、根因发现方式、能否更早发现，知识轨道问适用情境、不这样做的后果、反例）；起草并交用户 review；归档（新建或写回原文件并更新 updated 日期）；可发现性检查（若发现项目硬约束，提示用 cs-note 追加到 .codestable/attention.md，不擅自修改）。
启动前需先读取 .codestable/attention.md，缺失则视为骨架不完整，提示补齐或运行 cs-onboard。搜索可用 python .codestable/tools/search-yaml.py，支持按 doc_type、track、severity、component、tags 等过滤。限制：learning 不放进 features/ 或 issues/，spec 也不放进 compound/；只读写 doc_type: learning 的文档。frontmatter、正文模板与完整示例见同目录 reference.md，搜索语法见 .codestable/reference/tools.md。