# Learn > Persist durable project learnings into a topic wiki. Use when the user asks "总结一下经验", "沉淀一下", or "记住这个"; when the user states a convention to persist ("保存为项目规范", "from now on use X"); when the user is correcting an answer or plan; when a verified belief conflicts with the codebase; or when an undocumented project convention surfaces. - Skill: `mrlyk/learn` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add mrlyk/learn` - Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/learn/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools, Research & Search - Author: mrlyk (https://skillmd.com/u/mrlyk) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mrlyk/learn --- # Learn Maintain a compact project knowledge base under `.superharness/spec/learnings/`. ## Select material Use this evidence order: 1. Start with the live session context because it preserves the user's exact intent. 2. Add unconsumed project observations from `.superharness/trace.jsonl` to recover earlier signals and supporting prompts. Persist only durable information: - user corrections that change future behavior - verified conflicts between an assumption and the codebase - project conventions or decisions that cannot be inferred reliably from code - recurring pitfalls with a verified resolution Exclude one-off task details, facts already obvious from code, and generic programming knowledge. ## Admission gate Verify every candidate against the repository before persisting. Search for existing coverage in `skills/`, `docs/`, `AGENTS.md`, `CLAUDE.md`, `.superharness/spec/`, and recent git history, then deliver one verdict per candidate: - **Save** — durable and absent from the repo; create or merge a topic page. - **Improve then Save** — durable but vague; sharpen the trigger and action wording, then save. - **Absorb into X** — an existing topic page or spec file already covers it; merge the new evidence there instead of creating a page. - **Drop** — readable from the repo, one-off, or generic knowledge; do not persist. This gate also applies to the 0.9 fast path: when the user says "remember this" but the repo already covers the rule, absorb the evidence into the existing carrier instead of creating a page. When a dropped or absorbed candidate shows that a proper document (`docs/`, `AGENTS.md`, spec files) should change, append one suggestion line to `.superharness/spec/learnings/pending-doc-updates.md` (create it when missing) instead of editing those documents directly; they change through `setup-superharness` review. ## Claim project observations Use the same single-flight protocol as `learn-summarizer` when a project trace exists: 1. Atomically create the directory `.superharness/learn-summarizer.lock`. If it already exists, report that learning is already in progress and stop. 2. Create `.superharness/trace.archive/` when needed. 3. List existing `processing-*.jsonl` snapshots, oldest first. If any exist, resume those snapshots and leave the active trace for the next run. 4. When no processing snapshot exists, atomically move `.superharness/trace.jsonl` to `.superharness/trace.archive/processing-.jsonl` before reading it. Hooks can then create a fresh active trace for the next batch. 5. Treat every complete JSONL record in the selected processing snapshots as the current batch. Join `learn:signal` entries to `user:prompt` entries by their shared `ref`. Ignore a malformed final fragment and preserve it for inspection. Continue with live session context when no project trace exists. ## Merge topic pages Choose a lowercase kebab-case topic name. Write or merge `.superharness/spec/learnings/.md` instead of creating duplicate pages. Each topic page must use this frontmatter: ```yaml --- confidence: <0.3|0.5|0.7|0.85|0.9> evidence: last_seen: tags: - --- ``` Structure the page body with four sections: `## Trigger` (when the rule applies, one line), `## Action` (what to do, 1-2 imperative sentences), `## Why` (root cause or decision rationale), and `## Evidence` (ref / commit / file references, one per line). Derive `confidence` from the `evidence` count; never assign it by judgment alone: - `0.3`: tentative signal without a confirmed correction - `0.5`: exactly 1 confirmed evidence event (one explicit correction or clarification) - `0.7`: 2 independent evidence events - `0.85`: 3 or more independent evidence events - `0.9`: the user explicitly states a durable rule such as "remember this" or "always do this" One contradicting evidence event or long-term lack of recurrence moves confidence down one band; record the event in `## Evidence` either way. Merge new evidence into the existing rule, remove superseded guidance, and keep the page denser than the source material. Add `[[topic]]` links when another learning directly explains or constrains the rule. A `promoted_to: ` frontmatter field marks a rule that `setup-superharness` has promoted into spec proper. Keep merging evidence into the page as usual and keep the field in place. ## Maintain the injected index Maintain the lowercase `.superharness/spec/learnings/index.md`. Include a concise link and one-line summary for every topic at confidence `0.7` or higher. Keep topics below 0.7 on their pages and out of the index; the index is the injection unit, so listing a topic is what feeds it back into future sessions. ## Finish safely When a processing snapshot was claimed: 1. Rename it to `.superharness/trace.archive/processed-.jsonl` after all writes succeed. 2. Update `.superharness/learn-state.json` with `lastSummaryTs` and clear `nudgedAt`. 3. Leave every failed processing snapshot unchanged so the next gate can retry it, and do not update `lastSummaryTs` after a failed write. 4. Remove `.superharness/learn-summarizer.lock` in a final cleanup step. Remove the lock even when no durable learning qualifies. Summarize the affected topics and suggest committing the learning files; do not commit unless the user requested it.