self-improvement

Self-Improvement

The review + auto-promote half of the learning loop. Capture is handled separately by the learnings skill, which writes pending entries to ~/.learnings/ continuously. This skill is the deliberate-but-autonomous half: it investigates each pending entry, promotes the ones that clear a conservative bar into CLAUDE.md, and records every decision in CHANGELOG.md so the active log stays clean and every promotion is reversible.

It closes the loop so Claude gets better as you keep using it — no manual step required.

How it runs

One pipeline, one behavior, two triggers. The pipeline never branches on who called it — it always runs non-interactively and auto-promotes. That single invocation model is what makes it safe to run headless (an approval prompt in an unattended process would deadlock).

Trigger	How
Autonomous (primary)	A gated SessionEnd hook (~/.claude/self-improvement/review-trigger.sh) checks the user-level pending count; if it's ≥ REVIEW_THRESHOLD and the cooldown has elapsed and no review holds the lock, it spawns a detached, headless claude -p review that runs the pipeline in its own process — zero cost to your live session.
Manual	/self-improvement runs the same pipeline in the foreground so you can watch promotions happen and intervene.

Undo any promotion with /self-improvement:revert <PROMO-hex>.

Relationship to learnings

	learnings	self-improvement
Who invokes	Main Claude, autonomously, on every trigger	SessionEnd hook (headless) or the user (/self-improvement)
When	Continuously	After a session ends (if enough piled up), or on demand
Does	Appends pending entries to ~/.learnings/	Investigates, auto-promotes qualifiers, logs to CHANGELOG
Behavior	Pure capture	Non-interactive auto-promote + revertible trail

The pipeline (run by the self-improvement agent)

1. Sweep (if given a session transcript path) for learnings passive capture missed; write them as Status: pending using the learnings entry formats.
2. Read all Status: pending entries from ~/.learnings/{LEARNINGS,ERRORS,FEATURE_REQUESTS}.md. (Manual runs also read the project .learnings/ mirror; autonomous runs do not — see Scope.)
3. Investigate each candidate with a learning-investigator subagent — one per entry, dispatched as concurrent foreground calls (parallel but blocking; never run_in_background, which would let the orchestrator yield before verdicts return). Collect every verdict before acting.
4. Act: auto-promote verdicts that clear the bar (append to target CLAUDE.md, [PROMO-<hex>] to CHANGELOG, remove from pending); [SKIP-<hex>] clear rejects; leave uncertain/project-scoped entries pending. Enforce MAX_PROMOTIONS_PER_RUN.
5. Notify via a single Pushover summary.
6. Report the same summary to stdout (lands in .review.log for headless runs).