omk-self-reflect

name	omk-self-reflect
description	Agent self-learning: promote recurring episodes to rules, capture complex corrections. Trigger when hook outputs 🔥 or ⬆️ (promotion needed), 🚨 (complex correction), or when user says 'reflect', 'learn from this', 'remember this', 'always do X', 'never do Y', '@reflect'. Also trigger when same mistake pattern appears ≥3 times in episodes.

Trigger Examples

• "记住，以后都要这样做"
• "always use jq for JSON, never sed"
• "@reflect 把这个教训沉淀一下"
• "I told you this before, capture it"
• "这个错误犯了好几次了，升级成规则"

Self-Reflect — Agent Self-Learning System

Scope (v3)

1. Promotion execution: When hook outputs 🔥 or ⬆️, read episodes.md, distill into 1-2 line rule, propose to user, write to rules.md if approved. Mark source episodes as promoted.

2. Complex insight capture: When hook outputs 🚨 (complex) and the correction is too complex for auto-capture (no simple DO/DON'T pattern), help user articulate and write to episodes.md via the same format.

NOT responsible for: daily capture (hook does it), dedup (hook does it), quality reporting (hook does it).

Sync Targets

Scenario	Target
Top-level principle (user approved)	AGENTS.md / CLAUDE.md (Principles section)
Promotion (≥3 same pattern)	knowledge/rules.md (matching keyword section)
Complex insight	knowledge/episodes.md
Code-enforceable rule	.kiro/rules/enforcement.md

Writing to Protected Files (AGENTS.md / CLAUDE.md / .claude/rules/)

When user explicitly approves writing to a protected instruction file, agent MUST autonomously execute the full three-step flow — do NOT wait for the human to do it manually:

1. touch .skip-instruction-guard
2. Write the change
3. rm -f .skip-instruction-guard

This bypasses the pre-write hook temporarily. Only do this when user has clearly approved the content in the current conversation.

Episode Format

DATE | STATUS | KEYWORDS | SUMMARY

• DATE: YYYY-MM-DD
• STATUS: active / resolved / promoted
• KEYWORDS: 1-3 english technical terms, ≥4 chars, comma-separated
• SUMMARY: ≤80 chars, no | character, actionable DO/DON'T

Promotion Process

1. Read episodes.md, find keywords appearing ≥3 times in active episodes
2. Distill into 1-2 line rule with DO/DON'T + trigger scenario
3. Read knowledge/rules.md section headers (## [keywords])
4. Clustering — choose target section by semantic match:
   • Compare episode keywords with each section's keyword list
   • Pick the section with most keyword overlap + semantic relevance
   • If no section matches → create new ## [episode-keywords] section at end of file
   • If placing in existing section → append new keywords to section header if they add value
5. Propose to user for approval (show target section)
6. If approved: append rule to chosen section, change source episodes status to promoted
7. Output: ⬆️ Promoted to rules.md [section]: 'RULE'

Note: promoted episodes are auto-cleaned by context-enrichment on next session start.

Trigger Patterns

High confidence (90%):

• remember: / always:
• don't ... unless
• I told you

Medium confidence (80%):

• no, use X / not X, use Y
• you missed / why didn't you

Exclusion Patterns (Don't capture)

• Questions ending with ?
• Requests starting with please / help me
• Messages over 300 characters without clear DO/DON'T pattern

On Detection

1. Confirm: 📝 Learning captured: '[preview]'
2. Write to target file immediately (no queue)
3. Continue answering the user's question