xiduzo/wtf/wtf-reflect

WTF Reflect

Capture learnings from this session. Route them into the right steering document. Every hard-won insight belongs in a steering doc so it guides future work. This includes where the AI went wrong and where implementation was harder than expected.

This skill is the producer for the ## Hard-Won Lessons section of the four steering docs. See ../references/steering-doc-process.md for the producer/consumer model and how other skills load these docs.

Intervention tracker: The hooks/track-interventions.py hook runs on every UserPromptSubmit event. It increments a per-user counter file in $WTF_STATE_DIR when it detects correction or frustration language (e.g. "no,", "wrong", "actually", "stop that"). Default path: $XDG_STATE_HOME/wtf/interventions-<user>. Else use ~/.local/state/wtf/ or $TMPDIR/wtf/. 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/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 (per ../references/questioning-style.md):

• question: "No steering docs found. Would you like to create them first?"
• header: "No steering docs"
• options:
• Create them now → run the steer-* skills to create the docs
• Skip — just capture notes → 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

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

Q1 — What was harder than expected?

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "What was harder or more painful than it should have been in this session?"
• header: "Session friction"
• options:
• 2–3 inferred options based on what was worked on (e.g. "Debugging X took too long", "Claude kept misunderstanding Y")
• Nothing — skip — 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?

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "Did Claude keep making the same mistake you had to correct?"
• header: "AI mistakes"
• options:
• Yes — describe it → tell me what it kept doing
• No recurring mistakes → one-off issues only

If Yes → call AskUserQuestion (per ../references/questioning-style.md):

• 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 — What is the one rule this session taught you?

Call AskUserQuestion (per ../references/questioning-style.md):

• 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 rules inferred from the session
• Skip this one — nothing to add

4. Route each learning to the right steering doc

For each learning gathered, determine where it belongs:

For each target doc, follow the writer-side procedure in ../references/steering-doc-process.md (see "Hard-Won Lessons (writer-side, for wtf.reflect)"):

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 does not exist yet.
2. Read the current file.
3. Find 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. Insert it before the <!-- MANUAL ADDITIONS START --> marker if present.

Bullet format:

- **[Short label]** — [Concrete rule or observation]. *Learned [YYYY-MM-DD].*

Apply strict STE per ../references/ste-writing.md before you write any durable body (Hard-Won Lessons bullets). Keep the label short. Write the observation in STE.

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

Resolve the counter file using the same precedence the hook uses. Then truncate it:

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. 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."