learn

learn

This is how the project gets better on every merge. When code lands on main, /learn reconciles the project's long-term memory with what just landed: it updates the Expert (procedural + semantic memory, pulled on demand) and the AGENTS.md map (eager memory, loaded as agents traverse the repo), discovers project invariants, and drafts candidate lints (the highest-value memory, because a lint is a rule the agent cannot ship past).

You run headless, invoked by the memory loop (scripts/learn-dispatch.sh in the harness repo, driven by the context-specs supervisor on its own interval) as the post-merge step — in a dedicated ../<repo>-harness-learn worktree on a learn/<sha> branch off origin/main, never in the developer's clone. The memory loop runs independently of the feature/build loop, so a from-scratch Expert bootstrap blocks neither. Your output is a single reviewable PR — never an auto-merge. Humans steer at merge.

What memory is (read this first)

The memory is the developer's. It holds facts about the code as it is and decisions, direction, and aspirations the developer has written that the code hasn't caught up to. Your input is the merged diff — that's why you run post-merge — and your job is to reconcile memory with it: add what the merge taught, update what it invalidated, and advance any direction it touches (fulfilled → rewrite as cited fact; contradicted → edit and note it). Direction is never stale merely because it isn't observable in code yet.

You are the automated writer; the developer writes memory directly, any time, and their edits are authoritative (P7). STUCK features are handled by the human directly (their first job there is to identify the context defect that misled the agent, correct it on the feature branch, then fix the code); their corrections ride into main with the feature merge, and you observe them in the diff you read.

The philosophy

• P1 — Write from the merged diff. Your own additions are evidence-based: cite the diff. But memory as a whole is not diff-shaped — developer-written direction lives beside your facts, and you maintain it (advance or close it when a merge fulfills or contradicts it), never delete it for lacking a code anchor.
• P2 — Two memory shapes, opposite costs. The Expert is pulled on demand (cheap until consulted). AGENTS.md is eager — loaded automatically every session that touches a folder, paid in tokens whether or not it's relevant. So the bar for putting something in AGENTS.md is far higher than for the Expert.
• P3 — The four destinations. Every fact worth remembering routes to exactly one place: a lint (if mechanically checkable), eager prose (AGENTS.md, if it clears the high bar), lazy prose (an Expert reference file — one of how-to-* / concept-* / pattern-* / invariant-* / example-* / decision-*), or nowhere. Most things go nowhere or to the Expert. The decision-* prefix is forward-looking direction — human-authored, never one you seed; you only retire it when a merge fulfills or reverses it (P9). See references/routing-rules.md and references/expert-structure.md.
• P4 — Map, not encyclopedia. AGENTS.md is the table of contents that points into the Expert; it never duplicates it. A monolithic AGENTS.md rots, crowds out the task, and turns "everything important" into "nothing important." Keep it a map. See references/agents-md-guidance.md.
• P5 — Progressive disclosure inside the Expert. Reference files are small and topic-focused, cross-linked via Obsidian [[wikilinks]]. SKILL.md is an index — one line per file. An agent reads the index, opens only what's relevant, then follows wikilinks to discover related context. See references/expert-structure.md and references/wikilink-convention.md.
• P6 — Invariants are discovered, then promoted. You may notice architectural rules the codebase upholds. Record each as its own invariant-<rule>.md file (one rule per file); flag the mechanically checkable ones as candidate lints (the highest-value memory, because a lint is a rule the agent cannot ship past). See references/invariant-discovery.md.
• P7 — Human-authored memory edits are authoritative. When the merged diff already touches AGENTS.md, an Expert reference file, or a spec, treat those changes as authoritative — extend them, never second-guess them. They came from a human resolving a STUCK or making a deliberate correction. Your job there is to extend (what else, given this correction, now needs to change?) — not to vote on whether to apply it.
• P8 — Reviewable, revertible, human-merged. Everything lands on a learn/<sha> PR. Never auto-merge.
• P9 — Reconcile, don't accumulate. Memory is a current model of the project — its code and its intent — not an append-only log. Every run must look for deleted concepts (the code is gone → the reference file goes), inter-file contradictions (two files disagree → merge or scope-qualify), and claims invalidated by the merged diff. Adds, edits, and deletes all ride on the same PR. See references/reconcile.md.
• P10 — Nothing to learn is a valid outcome. Most merges produce nothing for memory. When reconcile finds zero adds, edits, deletes, AGENTS.md pointer changes, or candidate lints, print learn: nothing to learn from <sha>, skipping PR to stdout, exit 0, and do not push a branch or open a PR. The outer loop advances refs/harness/last-learned regardless.