SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场wtf.reflect

wtf.reflect

办公与效率

查看项目

更新于 10-16 02:15

技能介绍

用途

wtf.reflect 用于在一次开发会话结束后捕获经验教训，并将它们路由到正确的 steering 文档中，让每条来之不易的洞察都能指导未来的工作。适用时机包括：开发者想记录一次艰难会话的收获、记录 Claude 出错的地方、保存实现中的坑点等。

本技能是四份 steering 文档中“## Hard-Won Lessons”章节的生产者。关于生产者/消费者模型以及其他技能如何加载这些文档，见 ../references/steering-doc-process.md。

干预追踪机制

hooks/track-interventions.py 钩子在每次 UserPromptSubmit 事件时运行。当它检测到修正或不满语气（例如 "no,"、"wrong"、"actually"、"stop that"）时，会递增 $WTF_STATE_DIR 中按用户区分的计数器文件。默认路径为 $XDG_STATE_HOME/wtf/interventions-<user>，否则使用 ~/.local/state/wtf/ 或 $TMPDIR/wtf/。当计数器达到 3 时，钩子会在会话结束时打印提醒，让用户运行 wtf.reflect。本技能第 6 步会把计数器重置为零。无需手动追踪，钩子会处理。

流程

1. 检查存在哪些 steering 文档

运行 ls docs/steering/ 2>/dev/null，建立四份文档的存在映射：TECH.md、QA.md、DESIGN.md、VISION.md。

如果一份都不存在，调用 AskUserQuestion（按 ../references/questioning-style.md）：

  • question: "No steering docs found. Would you like to create them first?"
  • header: "No steering docs"
  • options:
    • Create them now → 运行 steer-* 技能来创建文档
    • Skip — just capture notes → 把所有经验保存到 docs/steering/LEARNINGS.md

若选择 Create them now → 调用 wtf.steer-tech。注意 wtf.steer-tech 会在结尾提供链接到其他 steer-* 技能；让用户完成该流程后返回此处，并重新运行 ls 检查以确认现在存在哪些文档。

若选择 Skip → 把四份文档路径全部设为回退：docs/steering/LEARNINGS.md。

如果部分存在但不全 → 继续。在第 4 步中，把缺失文档对应的经验路由到 docs/steering/LEARNINGS.md 作为按文档的回退（需要时创建该文件）。

2. 了解会话情况

扫描上下文以理解本次做了什么：最近的 git 提交（git log --oneline -10）、对话中提到的失败/通过的测试、PR 或 issue。不要把这些直接倒给用户，仅用于预填问题。

3. 收集经验

Q1 — 什么比预期更难？

调用 AskUserQuestion：

  • question: "What was harder or more painful than it should have been in this session?"
  • header: "Session friction"
  • options:
    • 2–3 个基于工作内容推断的选项（例如 "Debugging X took too long"、"Claude kept misunderstanding Y"）
    • Nothing — skip — session went smoothly

若选择 Nothing — skip → 跳到第 6 步（重置计数器）并以 "Great session — nothing to capture." 退出。

Q2 — Claude 是否犯了反复出现的错误？

调用 AskUserQuestion：

  • question: "Did Claude keep making the same mistake you had to correct?"
  • header: "AI mistakes"
  • options:
    • Yes — describe it → 告诉它反复做了什么
    • No recurring mistakes → 只有一次性问题

若选 Yes → 调用 AskUserQuestion：

  • question: "Describe the mistake briefly. What rule would prevent it next time?"
  • header: "AI mistake — the rule"
  • options:
    • Skip — hard to articulate right now

Q3 — 这次会话教给你的一条规则是什么？

调用 AskUserQuestion：

  • question: "If you had to write one rule that would have prevented the most wasted time today, what would it be?"
  • header: "The lesson"
  • options:
    • 1–2 条从会话中推断的规则
    • Skip this one — nothing to add

4. 把每条经验路由到正确的 steering 文档

路由规则：

经验类型 目标文档
架构模式、实现坑点、AI 编码错误 TECH.md
测试失败模式、flaky 测试原因、QA 缺口 QA.md
设计不一致、组件误用、样式错误 DESIGN.md
范围混淆、优先级冲突、领域语言漂移 VISION.md
无法明确归入单一文档 TECH.md（默认）

对每个目标文档，遵循 ../references/steering-doc-process.md 中的写入方流程（见 "Hard-Won Lessons (writer-side, for wtf.reflect)"）：

  • 若目标文档不存在（依第 1 步的映射）→ 改用 docs/steering/LEARNINGS.md；若尚不存在，用 # Overflow Learnings 标题创建。
  • 读取当前文件。
  • 查找 ## Hard-Won Lessons 章节。
  • 若存在 → 在其下追加新条目；若不存在 → 在文件末尾追加该章节。如存在 <!-- MANUAL ADDITIONS START --> 标记，则插入到该标记之前。
  • 条目格式：- **[Short label]** — [Concrete rule or observation]. *Learned [YYYY-MM-DD].*
  • 在写入任何持久正文（Hard-Won Lessons 条目）前，按 ../references/ste-writing.md 应用严格的 STE。标签要短，观察用 STE 书写。

示例：

- **Don't mock the auth middleware in tests** — Three tests passed with mocks but failed in CI against the real service. Always integrate against real dependencies. *Learned 2026-03-24.*

5. 写入更新后的 steering 文档

写入每个修改过的文档，然后用当天日期提交：

git add docs/steering/
git commit -m "docs(steering): add hard-won lessons from $(date +%Y-%m-%d) session"

6. 重置干预计数器

用与钩子相同的优先级解析计数器文件，然后清空它：

USER_ID="${USER:-${USERNAME:-user}}"
STATE_DIR="${WTF_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/wtf}"
[ -d "$STATE_DIR" ] || STATE_DIR="${TMPDIR:-/tmp}/wtf"
mkdir -p "$STATE_DIR" 2>/dev/null
echo "0" > "$STATE_DIR/interventions-$USER_ID"

7. 闭环

打印简要总结：更新了哪些文档、捕获了多少条经验，并提醒用户："这些规则将自动指导未来的每一次会话。"

适用场景

  • 一次调试或实现难度超出预期的会话结束后。
  • 发现 AI 助手反复犯同一类错误、需要固化一条纠正规则时。
  • 积累了实现层面的坑点、测试问题、设计不一致或范围/优先级混淆，希望归档到对应 steering 文档时。

限制

  • 本技能依赖 steering 文档体系（TECH.md、QA.md、DESIGN.md、VISION.md）及 ../references/ 下的流程文件；这些文件暂未提供完整内容。
  • 干预计数依赖 hooks/track-interventions.py 钩子，钩子未运行时不会自动计数。
  • 文档未说明支持的平台、收费模式或价格，均暂未提供。