Promote Memory

## `[LEARN:foo] <summary>`

**Vote:** 4-of-5 YES (promote with note)

| Critic | Vote | Rationale |
|---|:---:|---|
| Generality | YES | ... |
| Staleness | YES | ... |
| Redundancy | YES | ... |
| Evidence | NO  | Entry doesn't cite the originating incident. Add a one-line "Incident:" pointer before promoting. |
| Format | YES | ... |

**Recommendation:** Address Evidence critic, then promote.

**Proposed MEMORY.md addition:**
```text
[LEARN:foo] <full proposed text>

**Near the cap, adding means removing.** MEMORY.md is capped at 200 lines **and** 25KB, and the byte cap usually binds first. When the file plus the proposed additions would pass ~190 lines or ~24KB (`wc -c MEMORY.md`), the report also names the **weakest current entry** as a demotion candidate — stale (a named file, flag, or model that no longer exists), contradicted by a newer rule, or local rather than generic — with the evidence, and asks the user whether to move it to auto memory or delete it. The test for keeping an entry: *would removing it cause a mistake on many tasks?*

### Step 5: User approves the promotions

The user reviews the report and explicitly approves which entries to promote. The skill writes approved entries to MEMORY.md, marks the same entries in their auto-memory topic files with `# promoted YYYY-MM-DD` for audit, and surfaces a summary.

Do **not** auto-promote — even on 5-of-5 YES votes. The user's approval is the final gate.

## Output

- Per-entry council report (verdicts, rationales, recommendations) — to the conversation.
- On approval: MEMORY.md updated (append at appropriate `[LEARN:category]` section), the auto-memory topic file updated (entry marked promoted).
- A `quality_reports/memory_promotion_<date>.md` audit file recording the full council session for forensics.

## Anti-patterns

- **Auto-promoting on 5-of-5 YES.** Even unanimous critic agreement can be wrong; the user's domain judgment is the final gate.
- **Re-running the council on the same entry repeatedly** hoping for a different result. If 4 critics consistently say NO, the entry doesn't belong in MEMORY.md — leave it in auto memory and stop.
- **Skipping the Evidence critic** because the entry "looks obvious." Evidence is what makes the entry portable across forkers; obvious-to-you ≠ obvious-to-them.
- **Demoting via this skill.** It only promotes. Demotion is a manual edit + commit.

## Cross-references

- [`.claude/rules/meta-governance.md`](../../rules/meta-governance.md) — the two-tier memory contract this skill operationalizes.
- [`.claude/agents/promote-memory-council.md`](../../agents/promote-memory-council.md) — the five-critic implementation (one agent file with five role specs, dispatched in parallel via the `Agent` tool).
- [`.claude/rules/model-routing.md`](../../rules/model-routing.md) — why critics default to Haiku tier.
- `/learn` (existing skill) — captures new `[LEARN]` entries; pairs with `/promote-memory` (which decides what graduates).

## Source of candidates (v2.5)

Candidates come from **native auto memory** — `~/.claude/projects/<project>/memory/`. Claude
writes these itself as it works, typed `user` / `feedback` / `project` / `reference`, and the
`MEMORY.md` there is an index, not the content.

The promotion question is unchanged and is the whole point: *would a researcher in a different
field, forking this template, be better off knowing this?* If yes it belongs in the committed
`MEMORY.md`; if it is about this machine, this dataset, or this person's preferences, it stays
local.

**Retired:** `.claude/state/personal-memory.md`. The two-tier idea was right; Claude Code now
ships the local tier natively, so the hand-rolled file is redundant. An existing one still
reads as a plain file, but nothing writes to it.

## The capture gate — before anything is remembered

Promotion decides what becomes *shared* knowledge. This gate decides what is worth recording
**at all**. Five questions; a candidate must pass all five:

1. **Durable** — will this still be true in six months, or is it about today's branch?
2. **Non-obvious** — would a competent person rediscover it in five minutes anyway?
3. **Stable** — does it describe a rule, or a symptom that a fix will erase?
4. **Specific** — is it actionable, or is it a mood? *"Be careful with merges"* is a mood.
5. **Not already captured** — does an existing entry cover it? Extend that one instead.

> **Just-in-case memories are banned.** They pollute the index and make the useful entries
> unfindable. A memory store nobody trusts is a memory store nobody reads.

Promotion from local observation to committed knowledge is a **reviewed act, not an autosave** —
which is why the five-critic council exists and why the user is the final gate even on a
unanimous vote.