/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