/learning-opportunity

Source: ~/.claude/skills/learning-opportunity/SKILL.md 
 
 name: learning-opportunity
description: Self-improving feedback loop. When something goes wrong, analyze root cause, patch the system, and ensure it never happens again.
argument-hint: "[describe what went wrong]" 
 Learning Opportunity 
 Turn every mistake into a permanent system improvement. 
 Instructions 
 You are analyzing a mistake or failure and patching the system so it never recurs. 
 Principle: AI bez enforcement-a ne radi. Markdown rules = suggestions. Hooks/scripts = enforcement. Always prefer deterministic fixes over documentation fixes. 
 Step 1: Identify the Failure 
 If argument provided, use it. Otherwise, ask: 
 
 What went wrong? 
 When did it happen? 
 What was the expected vs actual outcome? 
 
 Classify the failure type: 
 
 HALLUCINATION — AI invented something that doesn't exist (tool, path, port, import) 
 PROCESS_SKIP — AI skipped a required step (no boot, no backup, no task) 
 WRONG_OUTPUT — AI produced incorrect content (wrong data, bad code, broken logic) 
 KNOWLEDGE_GAP — AI didn't know something it should have known 
 REPEAT_MISTAKE — Same error as a previous session (worst category) 
 
 Step 2: Root Cause Analysis 
 Trace the failure through GOTCHA layers: 
 
 
 Goals — Was there a spec/rule that should have prevented this? 
 # Check existing rules
ls ~/system/rules/
grep -r "relevant keyword" ~/system/rules/
 
 
 
 Tools — Did a tool fail or was a phantom tool used? 
 # Check manifest
grep "relevant tool" ~/system/tools/manifest.md
 
 
 
 Context — Was the context missing or wrong? 
 # Check HiveMind for prior knowledge
node ~/system/agents/hivemind/hivemind.js query "relevant keyword"
 
 
 
 Hooks — Should an enforcement hook have caught this? 
 # Check existing hooks
ls ~/.claude/hooks/
 
 
 
 Memory — Was this a known issue that was forgotten? 
 # Check memory files
grep "relevant keyword" ~/.claude/projects/-Users-makinja/memory/MEMORY.md
 
 
 
 Document: Which layer failed? Why? 
 Step 3: Determine Fix Type 
 Choose the STRONGEST fix available (top = strongest): 
 
 
 
 Priority 
 Fix Type 
 When to Use 
 
 
 
 
 1 
 Hook (Python enforcement) 
 Hallucinations, phantom tools, security violations 
 
 
 2 
 Tool update (deterministic code) 
 Missing validation, wrong behavior 
 
 
 3 
 Rule addition (~/system/rules/) 
 New process requirement, agent behavior 
 
 
 4 
 CLAUDE.md update 
 Missing instruction, wrong priority 
 
 
 5 
 Memory update 
 Lesson learned, context for future 
 
 
 
 NEVER use only option 5 alone. Memory without enforcement = ZAKON #1 violation. 
 Step 4: Apply the Patch 
 Based on fix type, apply changes: 
 If HALLUCINATION → Update hallucination-detector.py 
 # Read current blocklist
grep -A 50 "PHANTOM_TOOLS" ~/.claude/hooks/hallucination-detector.py
 
 Add the hallucinated item to the appropriate blocklist (PHANTOM_TOOLS, KNOWN_PORTS, etc.) 
 If PROCESS_SKIP → Update/create enforcement hook 
 Check if gotcha-enforcer.py can be extended, or create new hook. 
 If WRONG_OUTPUT → Update tool or add validation 
 Fix the tool that produced wrong output. Add input validation. 
 If KNOWLEDGE_GAP → Add to context + memory 
 # Add to HiveMind
node ~/system/agents/hivemind/hivemind.js post john lesson "description"
 
 If REPEAT_MISTAKE → Escalate enforcement 
 If this mistake happened before, the previous fix was too weak.
Go UP the priority list (e.g., if rule exists but wasn't followed → add hook). 
 Step 5: Verify the Fix 
 Test that the fix actually works: 
 
 If hook: test with a simulated bad input 
 If tool: run the tool and verify output 
 If rule: check it's in the right location and formatted correctly 
 
 Step 6: Log Everything 
 # 1. Log to CHANGELOG
bash ~/system/tools/syslog.sh add "LEARNING: [description] — fix: [what was changed]"

# 2. Log to HiveMind
node ~/system/agents/hivemind/hivemind.js post john lesson "[failure type]: [what happened] → [what was fixed]"

# 3. Update lessons-learned if exists
# ~/system/rules/lessons-learned.md
 
 Step 7: Report 
 Show the user: 
 ## Learning Opportunity Report

### Failure
- **Type:** [HALLUCINATION|PROCESS_SKIP|WRONG_OUTPUT|KNOWLEDGE_GAP|REPEAT_MISTAKE]
- **Description:** [what went wrong]
- **Root Cause:** [which GOTCHA layer failed and why]

### Fix Applied
- **Fix Type:** [Hook|Tool|Rule|CLAUDE.md|Memory]
- **File Changed:** [path]
- **What Changed:** [description]

### Enforcement Level
- [ ] Deterministic (hook/script blocks bad behavior)
- [ ] Documented (rule/instruction guides good behavior)
- [ ] Remembered (memory/HiveMind for context)

### Verification
- [ ] Fix tested and working
- [ ] Logged to CHANGELOG
- [ ] Logged to HiveMind
 
 Rules 
 
 Deterministic > Documented — A hook that blocks is worth 100 markdown rules 
 ZAKON #1 applies — If the fix is "write more markdown", it's NOT a fix 
 Escalate repeats — Same mistake twice = previous fix was too weak 
 Always log — CHANGELOG + HiveMind, no exceptions 
 Backup first — setup-backup.sh before any hook/tool changes 
 
 $ARGUMENTS