self-improve

name	self-improve
version	0.1.0
description	Use only when the user explicitly invokes one of the slash commands: `/self-improve capture`, `/self-improve promote`, `/self-improve prune`, `/self-improve review`. Never trigger during code review, normal coding, or end-of-session summaries.

Self-Improvement Loop

A cross-agent self-improvement system. Works with Claude Code, Codex, Cursor, and any agent that reads SKILL.md.

Core loop: Capture → Promote → Prune → Review.

Three-Tier Architecture

NOTES.md          Tier 0   raw observations, quick captures
LESSONS.md        Tier 1   validated patterns, domain-specific playbook
AGENTS.md         Tier 2   hard rules, always loaded, ≤100 lines

Promotion direction: NOTES → LESSONS → AGENTS. Each tier is more selective, more abstract, and higher priority.

Setup

File layout:

project-root/
├── AGENTS.md                          # Tier 2: always loaded
└── .agents/self-improve/
    ├── LESSONS.md                     # Tier 1: read on demand
    └── NOTES.md                       # Tier 0: staging area

The .agents/self-improve/ directory is owned by this skill. On first invocation, create it if missing, plus any missing files inside it with a one-line heading. No fingerprint is needed for these files — the path itself is the ownership marker.

Throughout this document, NOTES.md and LESSONS.md refer to their fixed paths inside .agents/self-improve/.

Each tier has its own structural scope. The skill only reads and writes content that matches its tier's format:

• NOTES.md — entries matching the Phase 1 capture format (### [observe|promote] ... with a <!-- captured: YYYY-MM-DD --> footer).
• LESSONS.md — bullet points (- ...) under ## section headings (Code Style, Testing, API, etc.).

Anything that does not match these shapes — prose, comments, headings outside the skill's format — is never parsed, moved, or deleted.

AGENTS.md

AGENTS.md lives at the project root and is never owned as a whole by this skill. The skill only touches a single fingerprinted block:

## Self-Improve
<!-- managed-by: self-improve -->
See `.agents/self-improve/LESSONS.md` for domain-specific patterns.

- <promoted rule 1>
- <promoted rule 2>

Rules for this block:

• Identified by block fingerprint, not heading text. A project's own ## Self-Improve heading without the fingerprint is out of scope — never touched.
• The only place Phase 2 writes promoted rules and Phase 3 prunes them.
• Created on first promotion with a separate user confirmation. If AGENTS.md does not exist, Phase 2 also asks before creating it.
• Everything else in AGENTS.md is project-owned and read-only. If a promotion candidate overlaps with a project-owned rule outside the block, see the merge procedure in Phase 2.

Mirror files (CLAUDE.md, .cursorrules, copilot-instructions.md, …) are never written to. AGENTS.md is the single source of truth.

---

Phase 1: Capture → NOTES.md

Trigger: /self-improve capture.

1. One sentence: what happened
2. One sentence: root cause (ask "why", not "what")
3. Decide: record or dismiss?
   • dismiss — one-off, not a pattern. Tell user why, do not write to NOTES.md, stop here.
   • record — continue to step 4.
4. Tag the entry:
   • [promote] — clear pattern, recommend moving to LESSONS.md in Phase 2
   • [observe] — might be a pattern, keep for now
5. Append to NOTES.md with date stamp

Entry format:

### [observe] Database calls must be awaited
- **Symptom**: Missing await in userService.ts caused silent failure
- **Root cause**: No lint rule enforcing consumption of async return values
- **Scope**: `src/services/**`
<!-- captured: YYYY-MM-DD -->

Constraints:

• Max 5 lines per entry
• Write behavioral directives ("must X", "never Y"), not narratives
• Record glob scope when determinable

---

Phase 2: Promote

Trigger: /self-improve promote.

Promotion moves entries between tiers. Do not leave breadcrumbs like [promoted → ...] in the source file — git log is the audit trail.

Two promotion paths, evaluated independently.

NOTES.md → LESSONS.md

1. Read NOTES.md
2. Gather candidates: [promote]-tagged entries, plus [observe] entries with 2+ similar occurrences
3. Abstract: from specific incidents to general principle
4. Present candidates to user, ask for each:

Action	When
Promote to LESSONS.md	Pattern confirmed, domain-specific
Stay in notes	Needs more observation
Dismiss	Turned out to be noise

5. On confirm: append to the correct section in LESSONS.md (Code Style, Testing, API, …), creating the section if it does not yet exist, and delete the entry from NOTES.md.

LESSONS.md → AGENTS.md

1. Read LESSONS.md
2. Find lessons that apply across the whole project
3. Compression test: can it be stated in one line? If yes → candidate
4. Present candidates to user:

Action	When
Promote to AGENTS.md	Universal, high-impact, one-liner
Stay in lessons	Domain-specific or needs context
Extract to a skill	Complex enough to be a standalone workflow
Merge into existing rule	Says the same thing as an existing rule

5. On confirm: append the rule to the ## Self-Improve block in AGENTS.md and delete the entry from LESSONS.md.

Merge procedure

When a candidate overlaps with an existing rule, the destination action depends on where the duplicate lives.

1. Duplicate in skill-managed space (LESSONS.md, or the ## Self-Improve block in AGENTS.md). Show both wordings side-by-side and ask the user: keep existing, replace with candidate, or combine. Apply the choice to the destination, then delete the source entry (move semantics).
2. Duplicate in project-owned AGENTS.md content. Tell the user the rule already exists outside the skill's managed area and recommend they update the project-owned rule themselves. Never auto-edit project-owned content. Keep the source entry in place — the skill cannot verify the destination was updated, so deleting it would risk silent loss. Offer an explicit dismiss action if the user wants to drop the source anyway.

---

Phase 3: Prune

Trigger: /self-improve prune.

Prune each tier independently.

AGENTS.md (Tier 2)

Scope: the ## Self-Improve block only. Never touch content outside it, even if a rule elsewhere looks redundant or stale. Hard constraint: ≤100 lines inside the block.

Check	Condition	Action
Redundant	Removing it would not cause mistakes	Delete from block
Over-detailed	Needs examples to understand	Demote to LESSONS.md
Duplicate	Another block rule says the same thing	Merge in place

LESSONS.md (Tier 1)

No hard line limit, but each section must earn its place.

Check	Condition	Action
Obsolete	Codebase has changed, no longer applies	Delete
Section bloat	One section dominates	Split into a skill

NOTES.md (Tier 0)

Aggressive cleanup — this is a staging area, not an archive.

Check	Condition	Action
Stale observe	> 14 days, no second occurrence	Dismiss

Present the pruning plan, wait for user confirmation, execute, and report line counts before vs after for all three files.

---

Phase 4: Review

Trigger: /self-improve review.

1. Scan the current session for:
   • Corrections the user made
   • Dead ends that required backtracking
   • Repeated attempts before success
2. Run Phase 1 (Capture) on each finding → NOTES.md
3. If NOTES.md has ≥ 2 similar [observe] entries, suggest Promote
4. Output summary: N new notes captured, M ready for promotion

---

Constraints

• NOTES.md entries: ≤ 5 lines each
• AGENTS.md: ≤ 100 lines inside the ## Self-Improve block (project-owned content elsewhere is out of scope and uncounted)
• Every entry must have a date: <!-- captured: YYYY-MM-DD -->
• Date stamps use the harness-provided current date (e.g., Claude Code's currentDate context). If unavailable, ask the user for today's date before writing. Never guess or fabricate.
• All file modifications require user confirmation
• Write behavioral directives, not narratives
• When promoting to AGENTS.md, compress to one line; if impossible, it belongs in LESSONS.md