peri: Skill for Claude Code

Learn From History

把历史学习当成一个可观测改进环，而不是经验摘抄：固定输入，分层下钻证据，定位最窄变更面，为每项建议同时声明预测收益与回归风险，再由后续历史验证。

默认审计当前项目最近 7 个自然日期（含今天），不跨项目。报告和 decision manifest 是审计产物，不构成编辑授权；不自动修改或回滚规则、skill、代码。

本流程采用 Agentic Harness Engineering 的三层可观测思想，并适配为有人确认的项目审计：

1. 组件可观测：每个失败模式只归属一个首选变更面；
2. 经验可观测：最终概览可下钻到 unit finding，再到固定 snapshot 的原始 thread；
3. 决策可观测：每个变更建议都是带收益预测、回归风险和验收条件的可证伪契约。

事实源

• 运行编排与 unit prompt：scripts/run_history.py
• 提取逻辑：scripts/extract_daily.py
• run 与 decision manifest 校验：scripts/validate_run.py
• unit 报告格式：references/analysis-template.md
• 跨轮决策账本：spec/reviews/history-learn-YYYY-MM-DD.json

extract_range.py 仅保留手工范围导出的兼容用途，不是主路径。

流程

1. 创建 snapshot run

从环境中的 Working directory 取得项目根，显式传入 --cwd：

python3 .claude/skills/learn-from-history/scripts/run_history.py \
  --days 7 \
  --cwd <工作目录>

只有用户明确要求跨项目时才使用 --all：

python3 .claude/skills/learn-from-history/scripts/run_history.py --days 7 --all

脚本创建权限为 0700 的唯一目录：

/tmp/learn-from-history/<run_id>/
  manifest.json
  snapshot/threads.db
  extracted/<day>/*.txt
  prompts/unit-NNN.txt
  summaries/

它通过 SQLite backup 固定本次审计的数据边界，提取物权限为 0600。manifest.json 是本次运行的唯一输入清单，记录 snapshot digest、repository_root、日期、thread、消息数、输入 digest、降级统计和分析单元。

完成标准：命令 exit 0，manifest status=ready 或 status=empty。任一日期失败时命令必须 exit 非零；不得分析部分成功结果。empty 时报告近期无记录并结束。

2. 检查 manifest

Read manifest.json，核对：

• project_filter 或 all_projects 与用户范围一致；
• window.active_days、totals.thread_count、totals.message_count；
• totals.truncations 与 totals.parse_failures；
• 每个 unit 的输入、消息数、prompt、summary 和 sidecar 路径。

本流程按 thread 的 updated_at 日期归档完整 thread，不按消息切断因果链。报告中写清该语义。

不要扫描 run 目录猜测输入，也不要读取其他 run 的同名文件。

3. 执行分析单元

每个 unit 的完整任务已经写入 prompts/unit-NNN.txt。派发 general-purpose agent 时，把该 prompt 文件内容作为任务；子 agent 自己直接 Read/Write，不得再次调用 Agent，不得修改仓库。

调度规则：

• 1 个 unit：同步执行；
• 2 个以上独立 unit：可后台并行，最多 3 个；
• 超过 3 个：分批启动，当前批次全部收到终态后再启动下一批；
• agent 失败时优先 resume 原 child thread，不创建重复任务；
• background 的 started/completed 通知不是通过证据，不轮询未完成结果。