exp-writer

name	exp-writer
description	将当前任务上下文整理为结构化经验贴并保存到指定目录。用于“写复盘、整理经验、沉淀踩坑、归档知识”等请求。输出标准 frontmatter 与固定章节，自动生成唯一 ID 与文件名，默认保存到 ./knowledge/exp。

Exp Writer

按以下流程执行，确保经验贴可复用、可检索、可持续维护。

1. 收集上下文证据

从当前会话与工作区提取：

• 背景目标
• 现象与影响
• 排查/思路时间线（观察 -> 假设 -> 验证 -> 结论）
• 根因与决策理由（为什么选当前方案）
• 解决方案与关键改动
• 验证结果
• 后续行动项

信息不足时标注 待补充，不要编造。

2. 生成标准文档结构（Obsidian 友好）

输出 Markdown，格式为 YAML frontmatter + 固定章节正文。

2.1 Frontmatter 字段

必填字段：

• id（唯一主键，格式：exp-YYYYMMDD-xxxx）
• title
• date
• doc_type（postmortem | howto | reference）
• status（draft | reviewed | published | deprecated）
• owner
• tags
• summary
• impact
• service（服务名）
• module（模块名）
• env（prod | staging | test | dev）
• version（受影响版本）
• problem_signature（对象，包含 error_code/keyword/log/trigger 四个子字段）
• root_cause
• decision_rationale（选择当前方案的理由）
• actions（列表，元素结构：owner/due/item/status）
• evidence_links（列表）
• applies_to（适用范围）
• not_applies_to（不适用范围）
• verification_steps（列表，验证步骤）
• success_criteria（列表，成功判定标准）

可选字段：

• reviewer
• severity（low | medium | high）
• repo
• paths
• last_verified_at
• review_date
• visibility（team | internal | restricted）

2.2 正文章节

1. 背景与目标
2. 现象与影响
3. 排查/思路时间线（观察 -> 假设 -> 验证 -> 结论）
4. 根因分析
5. 方案对比与决策理由
6. 最终方案
7. 验证与结果
8. 踩坑与反模式
9. Action Items（doc_type=postmortem 必填，其他类型可写 无）
10. 关联资料

2.3 最终方案写法（第 6 节）

第 6 节固定包含以下小节，避免 AI 二次猜测：

• changes：改了什么（代码/配置/数据）
• prerequisites：前置条件（依赖、权限、开关）
• rollback：失败时如何回滚

3. 唯一性与命名规则

文件名格式：

• YYYY-MM-DD-<topic-slug>-<shortid>.md

示例：

• 2026-03-03-cache-invalidation-a7k2.md

规则：

• 标题允许重复，但文件名必须唯一。
• 若目标目录存在同名文件，重新生成 shortid。
• 去重主键使用 id，不要使用 title。

4. 落盘规则

• 用户提供 target_dir 时，保存到该路径。
• 未提供时，默认保存到 ./knowledge/exp/（建议该目录位于 Obsidian Vault 内）。
• 不覆盖已有文件，冲突时自动生成新文件名。

5. 质量门槛

发布前检查：

• 有明确结论（前 3 段可读懂）
• 有问题指纹（标题包含 [模块/系统] + 关键词）
• tags 包含模块或场景信息，至少 2 个标签
• service/module/env/version 非空，且与正文一致
• problem_signature.error_code/keyword/log/trigger 至少 1 个非空，且包含关键报错或关键现象
• 有可复现证据（命令/路径/链接）
• verification_steps 为可执行步骤列表（命令级或操作级）
• success_criteria 为量化判定列表（阈值/状态/数量）
• doc_type=postmortem 时有可执行行动项（负责人 + 截止日期）
• 无敏感信息泄露（密钥/账号/隐私已脱敏）
• status=published 前至少一次 review，且必须满足：
  • problem_signature 至少 1 个子字段非空
  • decision_rationale 非空
  • verification_steps 至少 1 条
  • success_criteria 至少 1 条
  • evidence_links 至少 1 条

6. 最小脚本建议

仅保留一个基础脚本：

• scripts/new_post.sh：创建文档、填充元数据、生成唯一 id 与文件名。

模板文件：

• assets/post-template.md：标准 frontmatter 与固定章节骨架。