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 wtf.reflect. Step 6 of this skill resets the counter to zero. No manual tracking is needed — the hook handles it.
Process
1. Check which steering docs exist
ls docs/steering/ 2>/dev/nullBuild 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 wtf.steer-tech. Note that wtf.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).
2. Orient to the session
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.
3. Gather learnings — one question at a time
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"}
4. Route each learning to the right steering doc
For each learning gathered, determine where it belongs:
| Learning type | Target 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:
- If the target doc does not exist (from the map built in step 1) → use
docs/steering/LEARNINGS.mdinstead. Create it with a# Overflow Learningsheading if it doesn't exist yet. - Read the current file.
- Look for a
## Hard-Won Lessonssection. - If it exists → append the new bullet(s) under it.
- 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.*5. Write the updated steering docs
Write each modified doc. Then commit using today's date:
git add docs/steering/
git commit -m "docs(steering): add hard-won lessons from $(date +%Y-%m-%d) session"6. Reset the intervention counter
echo "0" > /tmp/wtf.interventions-$(whoami)-$(basename "$(git rev-parse --show-toplevel 2>/dev/null)")7. Close the loop
Print a brief summary:
- Which docs were updated
- How many learnings were captured
- Remind the user: "These rules will guide every future session automatically."