agent-learning

# Agent Learning Patterns ## What It Does Defines when to record learnings, quality standards for entries, and retrieval strategies. Loaded by memory-related commands and agents for consistent learning behavior. ## When to Use Use when yellow-ruvector plugin commands or agents need guidance on learning triggers, quality gates, or retrieval ranking. ## Usage This skill is not user-invocable. It provides shared context for the yellow-ruvector plugin's learning workflows. ## Learning Triggers ### Record a Context Entry When (type: `context`) - Test failure that required a code fix - Lint or type error that needed resolution - User corrected the agent's approach - Agent retried after an error and succeeded - Build or deploy failure ### Record a Decision Entry When (type: `decision`) - Complex operation succeeded on first attempt - User explicitly praised a technique - Clean solution to a recurring problem - Novel approach that worked well ### Record a Code Entry When (type: `code`) - Debugging revealed "X caused Y" - Configuration change resolved an issue - Performance investigation found a bottleneck - Dependency update triggered a regression ### Skip Recording When - Trivial file reads or searches - Simple, routine operations - Information already captured in a previous entry - The operation has no notable outcome ## Quality Gates Every learning entry must meet these criteria: 1. **Minimum length:** 20 words in the content field 2. **Structure:** Must include context (what happened), insight (why), and action (what to do) 3. **Specificity:** Reference concrete files, functions, or error messages — not vague generalizations 4. **Actionability:** The "action" must be something a future agent can follow ### Good Examples **Context:** > "Test `auth.test.ts:testTokenRefresh` failed because the mock JWT was expired. > Fix: always set mock token expiry to `Date.now() + 3600000` instead of a > hardcoded timestamp. Applied in commit abc123." **Decision:** > "Batch database inserts wrapped in a transaction are 10x faster than > individual inserts for the users table. Use > `db.transaction(async (tx) => { ... })` pattern when inserting more than 5 > rows." ### Bad Examples > "Fixed a bug" — No context, no insight, no action. "Tests should pass" — Not > specific, not actionable. ## Retrieval Strategy Use Reciprocal Rank Fusion (RRF) to combine multiple ranking signals: ``` final_score = sum(1 / (rank_i + 60)) for each signal i ``` ### Ranking Signals 1. **Semantic similarity** — Vector cosine distance to query 2. **Recency** — Time-decay: newer entries rank higher (Retrieval frequency is not a usable signal: the recall result shape exposes only `content`, `type`, `score`, and `created` — there is no retrieval-count field to read.) ### Context Budget - Load max 5 learnings per session start (via SessionStart hook) - Prioritize by RRF score - Each loaded learning should be a concise, actionable reminder ### Dedup Threshold - Cosine similarity > 0.82 = likely duplicate (canonical constant from the `memory-query` skill's protocol constants) - Warn user before storing near-duplicates - Don't apply hard threshold on search results — always return top-k, filter below 0.5 ## Skill Promotion When a recurring `context` pattern appears 3+ times across sessions, consider promoting it to a reusable `decision` entry: 1. Identify the recurring pattern from prior context entries 2. Formulate as a positive "do this" rule (not "don't do that") 3. Store as a `decision` entry with broader context 4. Optionally add to project CLAUDE.md if it's a project-wide convention