# Learnings

Corrections, insights, and knowledge gaps captured during development.

**Categories**: correction | insight | knowledge_gap | best_practice

---

## [LRN-20260916-001] correction

**Logged**: 2026-09-16T08:10:00+08:00 (观测于 2026-08-27，回溯补录)
**Priority**: high
**Status**: promoted
**Area**: docs

### Summary
`TOOLS.md` / `MEMORY.md` 曾把 `send_weekly_report.py` 描述为「会同步元数据到 db」，实际该脚本从不写 SQLite。

### Details
盘点归档链路时逐条核对脚本行为，确认 `send_to_drafts()` 只有两条落盘动作：
- `archive_report()` → 写 Markdown 到 `weekly-reports/YYYY/`
- `sync_to_mysql()` → 写 MySQL `resume` 库

**没有任何 SQLite 写入**。原描述会让后续会话误判「SQLite 已自动入库」，从而漏跑 `sync_reports_db.py` / `import_md_to_db.py`，造成本地索引与 Markdown 静默不一致。

### Suggested Action
已修正 `TOOLS.md` 与 `MEMORY.md` 的表述，明确「脚本不写 SQLite，入库需手动执行」。

### Metadata
- Source: conversation
- Related Files: TOOLS.md, MEMORY.md, send_weekly_report.py
- Tags: 文档, 归档, 周报, sqlite
- Pattern-Key: docs.inaccurate-description
- Recurrence-Count: 1
- First-Seen: 2026-08-27
- Last-Seen: 2026-08-27
- **Promoted**: TOOLS.md, MEMORY.md

---

## [LRN-20260916-002] correction

**Logged**: 2026-09-16T08:10:00+08:00
**Priority**: medium
**Status**: resolved
**Area**: docs

### Summary
`AGENTS.md` 的技能小节指向 `skills/weekly-report-g5/SKILL.md`，该路径不存在；在用技能实际是 `skills/weekly-report/SKILL.md`。

### Details
2026-09-16 按 AGENTS.md 指引直接 `read` 该路径，返回 `ENOENT: no such file or directory`。核实后确认：
- 实际在用：`skills/weekly-report/SKILL.md`（description 已覆盖 G5/G6）
- `weekly-report-g5` 只存在于 Skill Workshop 的 proposal 目录，从未成为 live 技能

AGENTS.md 是每次会话必读文件，错误路径既浪费工具调用，也可能让后续会话判定「技能不存在」而重复造轮子。

### Suggested Action
把 AGENTS.md 技能小节的路径改为 `skills/weekly-report/SKILL.md`。

### Resolution
- **Resolved**: 2026-09-16T08:15:00Z
- **Notes**: 已修正 `AGENTS.md` 技能小节路径，并补登自我改进技能条目；同时清理了同文件第 252 行 OKR 小节与「## 技能」标题粘连的格式残留。

### Metadata
- Source: conversation
- Related Files: AGENTS.md, skills/weekly-report/SKILL.md
- Tags: 文档, 技能路径, 漂移
- Pattern-Key: docs.stale-path
- Recurrence-Count: 1
- First-Seen: 2026-09-16
- Last-Seen: 2026-09-16
- See Also: LRN-20260916-004

---

## [LRN-20260916-003] knowledge_gap

**Logged**: 2026-09-16T08:10:00+08:00
**Priority**: medium
**Status**: pending
**Area**: config

### Summary
GNU date 的 `monday this week` 返回的是**下周一**，不是本周一；用它推算周报日期范围会算出一周之后的区间。

### Details
2026-09-16（周三）实测：
- `date -d 'monday this week' +%F` → `2026-09-21`（下周一，错的）
- `date -d 'last monday' +%F` → `2026-09-14`（本周一，对的）

周期语义在 GNU date 里不直观，且不会报错——属于「静默算错」，比报错更危险。

### Suggested Action
周报日期范围以**用户提供的任务日期**为准，不用表达式推导；确需推导时只用 `last monday`。

### Metadata
- Source: conversation
- Related Files: send_weekly_report.py
- Tags: shell, date, 周报, 静默错误
- Pattern-Key: shell.date-week-start
- Recurrence-Count: 1
- First-Seen: 2026-09-16
- Last-Seen: 2026-09-16

---

## [LRN-20260916-004] correction

**Logged**: 2026-09-16T08:10:00+08:00
**Updated**: 2026-09-16T08:20:00+08:00
**Priority**: medium
**Status**: resolved
**Area**: config

### Summary
（本条已更正）我曾误判 Skill Workshop 中 `weekly-report-g5` 的两个提案为 pending；实际状态是 `stale` 与 `applied`，**均非待处理**。

### Details
首次复盘时，我只凭提案目录里 `PROPOSAL.md` 头部自带的 `status: proposal` 就断定二者「仍待处理」，并把「待处理提案数虚高」写进了改进周报。随后用权威入口核实：

- `skill_workshop list` → `[stale, create, clean]`（v1）、`[applied, update, clean]`（v2）
- `skill_workshop list --status pending` → **No skill proposals matched**

即：v1 已 stale（基线变动，无法再应用），v2 已 applied（内容确已并入在用技能）。**「虚高待办数」这一结论不成立**，是读错来源所致。

附带发现：这两个目录现存仅 `PROPOSAL.md`，原先的 `proposal.json` / `rollback.json` 已不在（2026-08-28 时还在），说明其间有自动化（skill-collection-review）做过迁移/清理。

### Suggested Action
判断提案状态**只用 `skill_workshop list`**，不要读 `PROPOSAL.md` 头部的 `status` 字段——那是提案正文自带的静态标记，不代表当前生命周期状态。同理，任何「状态类」结论都应以对应的工具/接口为准，而非文件表面内容。

### Resolution
- **Resolved**: 2026-09-16T08:20:00Z
- **Notes**: 已更正 `.learnings` 本条与 `2026-W38-改进周报.md`；经复核**无需清理提案**（本就不存在 pending，删除反而会丢掉 v2 已应用的历史记录）。

### Metadata
- Source: conversation
- Related Files: skill-workshop/proposals/, weekly-reports/2026/2026-W38-改进周报.md
- Tags: skill-workshop, 提案, 误判, 来源可靠性
- Pattern-Key: tooling.wrong-status-source
- Recurrence-Count: 1
- First-Seen: 2026-09-16
- Last-Seen: 2026-09-16
- See Also: LRN-20260916-002

---

## [LRN-20260916-005] knowledge_gap

**Logged**: 2026-09-16T08:10:00+08:00
**Priority**: low
**Status**: pending
**Area**: docs

### Summary
`sessions_search` 用中文错误关键词查询返回空，不适合当作「错误发现」入口。

### Details
2026-09-16 连续两次中文查询（`错误 失败 修正` / `报错 失败 修正 不是这样 应该 重新`）均返回 `results: []`，但同一会话 transcript 中确实存在对应内容（`sessions_history` 可正常读到）。说明该检索路径对中文召回不可靠，会给出「什么都没发生」的假信号。

### Suggested Action
错误复盘以 `.learnings/` 记录为主数据源，配合 transcript / 日志直读；`sessions_search` 仅作辅助，空结果不当作「无此事」。

### Metadata
- Source: conversation
- Related Files: .learnings/
- Tags: 检索, 召回, 中文
- Pattern-Key: tooling.empty-search-result
- Recurrence-Count: 1
- First-Seen: 2026-09-16
- Last-Seen: 2026-09-16

---