| name | drec |
| description | Session 记录写入方法论——文件格式模板、踩坑经验四段式记录、时间戳获取规则、最低合法答案、归档聚合指引、Stop hook 检测正则。触发场景：(1) 写 session 记录，(2) 记录踩坑经验，(3) Session 结束前整理，(4) 用户说"记录"、"recording"、"踩坑"。铁律：必须 date 命令获取时间戳。 |
| allowed-tools | ["Bash","Read","Write","Edit"] |
| effort | low |
| hooks | {"Stop":[{"hooks":[{"type":"command","command":"python3 ${CLAUDE_SKILL_DIR}/../hooks/scripts/stop_integrity.py 2>/dev/null || true"}]}],"SubagentStop":[{"hooks":[{"type":"command","command":"python3 ${CLAUDE_SKILL_DIR}/../hooks/scripts/subagent_stop.py 2>/dev/null || true"}]}]} |
diwu-record
Session 记录写入规范：每次 session 结束前的必做事项。
时间戳规则（铁律）
写入 Session 标题前必须先运行命令获取真实时间戳：
date '+%Y-%m-%d %H:%M:%S'
- 禁止手写日期或写"（续）"等占位符
- 正确：先运行 date → 得到
2026-04-18 16:49:42 → 写 ## Session 2026-04-18 16:49:42
- 错误：
## Session 2026-02-26 （续）
Session 文件格式模板
## Session YYYY-MM-DD HH:MM:SS
### Task#N: [标题] → [状态]
**实施内容**: - [工作项]
**验收验证**: - [x] [acceptance] ([方法])
**提交**: commit [hash]
### 下一步: [计划]
### 本次踩坑/经验
- [类别] 现象 → 根因 → 误判 → 正确做法
### 错误追踪表（可选）
| 时间戳 | 工具 | 错误摘要 | 尝试 | 解决方式 | 类别 |
禁止 YAML front matter：Session 文件禁止以 --- 开头。--- 在 Markdown 中是 front matter 语法，渲染器会将包裹内容当作元数据隐藏。
- 正例：文件第一行就是
## Session 2026-04-14 18:44:09
- 反例：开头写
--- 再跟 ## Session ...
本次踩坑/经验（必填）
约束级别：必填，不可省略。每个 session 必须显式写入此字段。
四段式格式模板
### 本次踩坑/经验
- [类别] 现象描述 → 根因分析 → 错误判断 → 正确做法
类别标签（六类泛化模式对齐）：
环境漂移 / 数据缺口 / 读层现象 / 路由护栏契约 / 验证误读 / 分层未拆清 / 其他
示例
### 本次踩坑/经验
- [环境漂移] 本地测试通过但 CI 超时 → CI 环境缺少代理配置导致网络超时 → 误判为代码性能问题 → 应先检查 CI 环境变量和网络配置再定位代码
- [验证误读] 单元测试全部 PASS 但功能不工作 → 测试 mock 了关键依赖导致假阳性 → 误判为已完成 → 应补充集成测试或端到端验证
最低合法答案（无显著误判时使用）
### 本次踩坑/经验
本轮无显著误判，实施路径符合预期。
注意：最低合法答案仅用于确实无踩坑的 session。任何判断偏差、意外阻塞、返工或环境问题都必须按四段式记录。
Stop hook 检测正则
Stop hook 用以下正则检测必填字段是否存在：
PITFALL_PATTERN = re.compile(
r'^###\s*本次踩坑[\/]?经验\s*\n'
r'(.*\n)*'
r'.+',
re.MULTILINE
)
PITFALL_MINIMAL_PATTERN = re.compile(
r'###\s*本次踩坑[\/]?.*经验.*无显著误判.*符合预期',
re.DOTALL
)
匹配语义：
- 正常踩坑记录：标题存在 + 后续有四段式内容 → PASS
- 最低合法答案：包含"无显著误判"且包含"符合预期" → PASS
- 缺失：文件中不存在标题 → FAIL（触发 Stop hook 告警）
归档聚合指引
归档时（recording/ 文件数超阈值），扫描所有即将归档的 session 文件中的 ### 本次踩坑/经验 段落，按类别聚类后追加到 project-pitfalls.md。每条必须标注具体 session 文件名作为来源（如 session-2026-04-18-213522.md），禁止写归档文件名或占位符；归档文件内按 ## Source: 分隔符追踪所属 session。
工具失败处理协议（3-Strike）
当同一工具连续失败时，Hook 自动追踪并注入分级提示：
| 尝试 | 策略 | 注入内容 |
|---|
| 1/3 | 诊断并修复根因 | 温和提醒：诊断根因，如有踩坑考虑记录 |
| 2/3 | 更换根本不同的方法 | 强烈建议：换工具/换文件/换策略 |
| 3+/3 | 广泛重新思考或升级用户 | 阻止继续：质疑假设，考虑升级 |
状态持久化：/tmp/diwu_ctx_<pid>_errtrack JSON 文件，冷却窗口默认 60 秒。
结构化错误追踪表（可选）
复杂 session（多次工具失败、多轮纠偏）中，建议在踩坑记录后追加表格：
### 错误追踪表（可选）
| 时间戳 | 工具 | 错误摘要 | 尝试 | 解决方式 | 类别 |
|--------|------|---------|------|---------|------|
| 01:30:05 | Bash | npm install E403 | 2 | 使用镜像源 | 环境漂移 |
Checkpoint 记录机制
大任务实施过程中记录中间进度：
### Checkpoint @ 步骤3/8
进度: 完成 auth 模块重构，payment 模块进行中
已修改: src/auth.ts(+120/-80), src/models/user.ts(+15/-5)
下一步: 步骤4 payment 模块重构 → 步骤5 集成测试
回滚方式: git checkout -- src/auth.ts src/models/user.ts
或 git reset --soft HEAD~1（如已提交）
CONTINUOUS_MODE_COMPLETE 格式
CONTINUOUS MODE COMPLETE - 所有可执行任务已完成
已完成: Task#A, Task#B | 剩余: Task#X(InDraft), Task#Y(BLOCKED)
本轮连续完成 N 个任务
