wtf.reflect
This skill should be used when a developer wants to capture learnings from a session — what was harder than expected, what Claude got wrong, implementation gotchas — and save them into the steering docs. For example "let's reflect", "that was painful, save this", "log this lesson", or "update the steering docs with what went wrong". Also triggered by the intervention tracker after repeated corrections. Routes each learning into the right steering doc (TECH, QA, DESIGN, or VISION) under a "Hard-Won Lessons" section.
How do I install this agent skill?
npx skills add https://github.com/xiduzo/wtf --skill wtfreflectIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The wtf.reflect skill captures user session learnings and records them in project steering documents. Its primary security concern is the indirect prompt injection surface, where unvalidated user feedback is stored in files that guide future agent behavior. The skill also executes local shell commands for state management and version control.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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.mdinstead
- Create them now → run the
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:
| 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 |
| Does not clearly fit one doc | TECH.md (default) |
For each target doc, follow the writer-side procedure in ../references/steering-doc-process.md (see "Hard-Won Lessons (writer-side, for wtf.reflect)"):
- 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 does not exist yet. - Read the current file.
- Find 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. 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."
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/xiduzo/wtf/wtf.reflect">View wtf.reflect on skillZs</a>