Back to Details

wtf.reflect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

WTF Reflect

WTF Reflect

Capture learnings from this session and route them into the right steering document. Every hard-won insight — especially about where the AI went wrong or where implementation was harder than expected — belongs in a steering doc so it guides future work automatically.
Intervention tracker: The 
hooks/track-interventions.sh
hook runs automatically on every 
UserPromptSubmit
event and increments 
/tmp/wtf-interventions-$(whoami)-$(basename "$(git rev-parse --show-toplevel 2>/dev/null)")
when it detects correction or frustration language (e.g. "no,", "wrong", "actually", "stop that"). When the counter reaches 3, the hook prints a reminder at the end of the session to run 
reflect
. Step 6 of this skill resets the counter to zero. No manual tracking is needed — the hook handles it.
记录本次会话中的经验，并将其归类到对应的指导文档中。每一个来之不易的见解——尤其是关于AI出错的地方或是实现难度远超预期的内容——都应存入指导文档，以便自动为后续工作提供指引。
干预追踪器： 
hooks/track-interventions.sh
钩子会在每次 
UserPromptSubmit
事件时自动运行，当检测到修正或沮丧类语言（如“不对”“错了”“实际上”“别那样做”）时，会增加 
/tmp/wtf-interventions-$(whoami)-$(basename "$(git rev-parse --show-toplevel 2>/dev/null)")
的计数。当计数达到3时，钩子会在会话结束时提醒用户运行 
reflect
。本Skill的第6步会将计数重置为0。无需手动追踪——钩子会自动处理。

Process

流程

1. Check which steering docs exist

1. 检查现有指导文档

bash
ls docs/steering/ 2>/dev/null
Build a map of which of the four docs are present: 
TECH.md
, 
QA.md
, 
DESIGN.md
, 
VISION.md
.
If none exist, call 
AskUserQuestion
with:
  • question
    : "No steering docs found. Would you like to create them first?"
  • header
    : "No steering docs"
  • options
    : 
    [{label: "Create them now", description: "Run the steer-* skills to set up the docs"}, {label: "Skip — just capture notes", description: "Save all learnings to docs/steering/LEARNINGS.md instead"}]
If Create them now → invoke 
steer-tech
. Note that 
steer-tech
will offer to chain to the other steer-* skills at the end — let the user complete that flow, then return here. When control returns, re-run the 
ls
check to see which docs now exist. If Skip → set all four doc paths to the fallback: 
docs/steering/LEARNINGS.md
.
If some exist but not all → continue. In step 4, route learnings for a missing doc to 
docs/steering/LEARNINGS.md
as a per-doc fallback (create the file if needed).
bash
ls docs/steering/ 2>/dev/null
构建一个包含四个文档（
TECH.md
、
QA.md
、
DESIGN.md
、
VISION.md
）存在情况的映射表。
若不存在任何文档，调用 
AskUserQuestion
，参数如下：
  • question
    : "未找到指导文档。是否要先创建它们？"
  • header
    : "无指导文档"
  • options
    : 
    [{label: "立即创建", description: "运行steer-*系列Skill来设置文档"}, {label: "跳过——仅记录笔记", description: "将所有经验保存到docs/steering/LEARNINGS.md中"}]
如果选择立即创建 → 调用 
steer-tech
。注意
steer-tech
在结束时会提供链式调用其他steer-*系列Skill的选项——让用户完成该流程后再返回此处。返回后，重新运行
ls
命令检查现在存在哪些文档。 如果选择跳过 → 将四个文档的路径都设置为备用路径：
docs/steering/LEARNINGS.md
。
若部分存在但非全部 → 继续执行。在第4步中，将对应缺失文档的经验路由到
docs/steering/LEARNINGS.md
作为该文档的备用路径（若文件不存在则创建）。

2. Orient to the session

2. 梳理会话内容

Briefly scan context to understand what was worked on:
  • Recent git commits: 
    git log --oneline -10
  • Any failing/passing tests, PRs, or issues mentioned in conversation
  • Do NOT dump this at the user — use it only to pre-fill questions.
简要扫描上下文以了解本次工作内容：
  • 最近的git提交记录：
    git log --oneline -10
  • 会话中提到的任何失败/通过的测试、PR或问题
  • 不要将这些内容直接展示给用户——仅用于预先填充问题。

3. Gather learnings — one question at a time

3. 收集经验——逐个提问

Use 
AskUserQuestion
for each question. Only ask questions that aren't already answered by context.
Q1 — What was harder than expected?
  • question
    : "What was harder or more painful than it should have been in this session?"
  • header
    : "Session friction"
  • options
    : pre-fill with 2–3 inferred options based on what was worked on (e.g. "Debugging X took too long", "Claude kept misunderstanding Y"), plus 
    {label: "Something else", description: "I'll type it"}
    and 
    {label: "Nothing — skip", description: "Session went smoothly"}
If Nothing — skip → skip to step 6 (reset counter) and exit with: "Great session — nothing to capture."
Q2 — Did Claude make a recurring mistake?
  • question
    : "Did Claude keep making the same mistake you had to correct?"
  • header
    : "AI mistakes"
  • options
    : 
    [{label: "Yes — describe it", description: "I'll tell you what it kept doing"}, {label: "No recurring mistakes", description: "One-off issues only"}]
If Yes → call 
AskUserQuestion
with:
  • question
    : "Describe the mistake briefly. What rule would prevent it next time?"
  • header
    : "AI mistake — the rule"
  • options
    : 
    [{label: "I'll type the rule", description: "Free text"}, {label: "Skip", description: "Hard to articulate right now"}]
Q3 — What is the one rule this session taught you?
  • 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
    : pre-fill with 1–2 rules inferred from the session, plus 
    {label: "I'll write it", description: "Free text"}
    and 
    {label: "Skip this one", description: "Nothing to add"}
对每个问题使用
AskUserQuestion
。仅询问上下文未给出答案的问题。
问题1 — 哪些内容比预期更难？
  • question
    : "本次会话中，哪些内容比预期更困难或更棘手？"
  • header
    : "会话难点"
  • options
    : 根据工作内容预先填充2-3个选项（如“调试X耗时过长”“Claude一直误解Y”），再加上
    {label: "其他内容", description: "我会手动输入"}
    和
    {label: "没有——跳过", description: "会话进展顺利"}
如果选择没有——跳过 → 跳至第6步（重置计数）并退出，提示："会话进展顺利——无内容需要记录。"
问题2 — Claude是否反复犯同样的错误？
  • question
    : "Claude是否一直犯你不得不纠正的同一个错误？"
  • header
    : "AI错误"
  • options
    : 
    [{label: "是——描述错误", description: "我会告诉你它一直犯的错误"}, {label: "无重复错误", description: "仅存在一次性问题"}]
如果选择是 → 调用
AskUserQuestion
，参数如下：
  • question
    : "简要描述该错误。什么规则可以避免下次再犯？"
  • header
    : "AI错误——对应规则"
  • options
    : 
    [{label: "我会输入规则", description: "自由文本"}, {label: "跳过", description: "目前难以清晰表述"}]
问题3 — 本次会话教会了你哪一条规则？
  • question
    : "如果要写一条规则来避免今天最浪费时间的情况，那会是什么？"
  • header
    : "经验总结"
  • options
    : 根据会话内容预先填充1-2条规则，再加上
    {label: "我会编写规则", description: "自由文本"}
    和
    {label: "跳过此问题", description: "无内容可添加"}

4. Route each learning to the right steering doc

4. 将每条经验路由到对应的指导文档

For each learning gathered, determine where it belongs:
Learning typeTarget doc
Architecture pattern, implementation gotcha, AI coding mistake
TECH.md
Test failure pattern, flaky test cause, QA gap
QA.md
Design inconsistency, component misuse, style mistake
DESIGN.md
Scope confusion, priority conflict, domain language drift
VISION.md
Doesn't clearly fit one doc
TECH.md
(default)
For each target doc:
  1. If the target doc does not exist (from the map built in step 1) → use 
    docs/steering/LEARNINGS.md
    instead. Create it with a 
    # Overflow Learnings
    heading if it doesn't exist yet.
  2. Read the current file.
  3. Look for a 
    ## Hard-Won Lessons
    section.
  4. If it exists → append the new bullet(s) under it.
  5. If it does not exist → append the section at the end of the file, inserting it before the 
    <!-- MANUAL ADDITIONS START -->
    marker if present.
Bullet format:
- **[Short label]** — [Concrete rule or observation]. *Learned [YYYY-MM-DD].*
Example:
- **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.*
对于收集到的每条经验，确定其归属：
经验类型目标文档
架构模式、实现陷阱、AI编码错误
TECH.md
测试失败模式、不稳定测试原因、QA缺口
QA.md
设计不一致、组件误用、样式错误
DESIGN.md
范围混淆、优先级冲突、领域语言偏差
VISION.md
无法明确归类到某一文档
TECH.md
（默认）
对于每个目标文档：
  1. 若目标文档不存在（根据第1步构建的映射表） → 使用
    docs/steering/LEARNINGS.md
    作为替代。若该文件不存在，则创建并添加
    # 溢出经验
    标题。
  2. 读取当前文件内容。
  3. 查找
    ## 来之不易的经验
    章节。
  4. 若存在 → 在该章节下添加新的项目符号。
  5. 若不存在 → 在文件末尾添加该章节，若存在
    <!-- MANUAL ADDITIONS START -->
    标记，则插入到该标记之前。
项目符号格式：
- **[简短标签]** — [具体规则或观察结果]。*学习于[YYYY-MM-DD]。*
示例：
- **测试中不要模拟认证中间件** — 三个测试在使用模拟时通过，但在CI环境中对接真实服务时失败。始终对接真实依赖。*学习于2026-03-24。*

5. Write the updated steering docs

5. 写入更新后的指导文档

Write each modified doc. Then commit using today's date:
bash
git add docs/steering/
git commit -m "docs(steering): add hard-won lessons from $(date +%Y-%m-%d) session"
写入每个修改后的文档。然后使用当天日期提交：
bash
git add docs/steering/
git commit -m "docs(steering): add hard-won lessons from $(date +%Y-%m-%d) session"

6. Reset the intervention counter

6. 重置干预计数器

bash
echo "0" > /tmp/wtf-interventions-$(whoami)-$(basename "$(git rev-parse --show-toplevel 2>/dev/null)")
bash
echo "0" > /tmp/wtf-interventions-$(whoami)-$(basename "$(git rev-parse --show-toplevel 2>/dev/null)")

7. Close the loop

7. 收尾总结

Print a brief summary:
  • Which docs were updated
  • How many learnings were captured
  • Remind the user: "These rules will guide every future session automatically."
打印简要总结：
  • 更新了哪些文档
  • 记录了多少条经验
  • 提醒用户："这些规则将自动指导未来的每一次会话。"