---
name: self-improving-agent
description: "Structured logging for recurring mistakes, corrections, and knowledge gaps. Use when the same type of error happens twice, or when you discover a better approach to something you've done before. NOT for one-off fixes or daily notes."
---

# Self-Improvement Skill

Log recurring mistakes, corrections, and knowledge gaps to structured files inside `memory/learnings/`. These files are indexed by the native memory search and complement daily notes (`memory/YYYY-MM-DD.md`) without duplicating them.

## Write Targets

All writes go to `memory/learnings/` only. Four files:

| File | Purpose |
|------|---------|
| `memory/learnings/LEARNINGS.md` | Corrections, knowledge gaps, best practices |
| `memory/learnings/ERRORS.md` | Command failures, tool errors, exceptions |
| `memory/learnings/FEATURE_REQUESTS.md` | Capabilities the maintainer has requested |
| `memory/learnings/PROMOTIONS.md` | Proposals for promoting patterns to boot files |

No other write targets exist. This skill does not write to boot files, config files, or any location outside `memory/learnings/`.

## When to Log

Log when you notice a **pattern**, not a one-off event.

**Detection triggers:**

| Signal | Entry Type | Category |
|--------|-----------|----------|
| The maintainer corrects you ("No, that's wrong...", "Actually...") | Learning | `correction` |
| Your knowledge was outdated or incorrect | Learning | `knowledge_gap` |
| You discover a better approach to a recurring task | Learning | `best_practice` |
| Command/tool returns an error you have seen before | Error | (by tool name) |
| API or external service fails repeatedly | Error | (by service name) |
| The maintainer requests a capability that does not exist | Feature Request | (by capability) |

**When NOT to log:**
- One-off fixes that will not recur
- Facts that belong in daily notes (`memory/YYYY-MM-DD.md`)
- Context that belongs in SESSION-STATE.md
- Anything already captured in a daily note from this session
- Information that belongs in a boot file (route it there instead)

**Workflow interruption rule:** Finish the active task first. Log at natural breakpoints (after a task completes, after a conversation topic changes), not mid-action. Never chain more than 2 tool calls for logging in a single turn.

## How to Log

### Step 1: Search Before Writing

Before adding a new entry, search `memory/learnings/` for similar entries:

```
memory_search("keyword from the issue")
```

Or grep directly:

```
grep -r "keyword" memory/learnings/
```

If a match exists: bump its Priority if warranted, increment Recurrence-Count, update Last-Seen, add a See Also cross-reference. Do NOT create a duplicate.

### Step 2: Write the Entry

Append to the appropriate file. Templates are in this skill's `assets/` directory. Full field reference is in `references/entry-format-reference.md`.

**Entry ID format:** `TYPE-YYYYMMDD-XXX`
- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature request), `PROMO` (promotion)
- YYYYMMDD: Today's date
- XXX: Sequential number (001, 002) or random 3 chars (A7B)

**Minimal required fields:**

```markdown
## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: (freeform tag)

### Summary
One-line description

### Details
What happened, what was wrong, what is correct

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file
```

### Step 3: Cross-Reference Daily Notes

If the learning relates to something in today's daily note, add a Related Files link to that note. Do not copy daily note content into the learning.

## Area Tags

Freeform convention list (not a fixed enum): `operations`, `writing`, `research`, `social`, `memory`, `privacy`, `build-process`. Use whatever tag fits. Multiple tags are fine.

## Priority Guidelines

| Priority | When to Use |
|----------|-------------|
| `critical` | Blocks core functionality, data loss risk, security issue |
| `high` | Significant impact, affects common workflows, recurring |
| `medium` | Moderate impact, workaround exists |
| `low` | Minor inconvenience, edge case |

## Entry Lifecycle

### Statuses

`pending` > `in_progress` > `resolved` | `wont_fix` | `promoted` | `archived`

### Resolving an Entry

When fixed, update the entry:

1. Change `**Status**: pending` to `**Status**: resolved`
2. Add a Resolution block:

```markdown
### Resolution
- **Resolved**: ISO-8601 timestamp
- **Notes**: Brief description of what was done
```

## Recurring Pattern Detection

When logging something similar to an existing entry:

1. Link entries with See Also in Metadata
2. Bump priority if the issue keeps recurring
3. If a pattern recurs **3+ times across 2+ distinct tasks**, it qualifies for promotion

## Promotion Workflow

Promotion means proposing that a recurring pattern become a permanent rule. This skill never writes to boot files directly.

**Off-limits targets:** Identity and personality files are off-limits for promotion. Route identity-related insights through your agent's existing identity review process, not through this skill.

### When to Propose

All three conditions must be true:
- Recurrence-Count >= 3
- Seen across at least 2 distinct tasks
- Occurred within a 30-day window

### How to Propose

1. Draft a proposal in `memory/learnings/PROMOTIONS.md` using the template in `assets/PROMOTIONS-TEMPLATE.md`
2. Set the source entry status to `promoted`
3. Notify the maintainer through your preferred direct channel (not group chats) with the proposal title and a one-sentence summary
4. Wait for the maintainer's explicit written approval before any changes are made elsewhere

The maintainer applies changes manually. The proposal is a recommendation, not an action.

## Periodic Review

During your regular review cycle, also review `memory/learnings/` for:
- Resolved entries that can be archived
- Pending entries that are stale (>30 days with no activity)
- Patterns across entries that warrant a promotion proposal
- Entries that duplicate daily note content (delete the duplicate)

One pass through the four files is sufficient. Note findings in the daily note under the review section.

## Archiving

When total file size across `memory/learnings/` (excluding archive/) exceeds 10,000 characters:

1. Move resolved and wont_fix entries older than 30 days to `memory/learnings/archive/YYYY-MM/`
2. Set their status to `archived`
3. Preserve the entry ID so cross-references remain valid

## Memory Layer Boundary

| Layer | Location | Contains | Format |
|-------|----------|----------|--------|
| Daily notes | `memory/YYYY-MM-DD.md` | Raw chronological log | Timestamped narrative |
| Learnings | `memory/learnings/` | Structured patterns | ID'd entries with metadata |
| Long-term | `MEMORY.md` | Curated current state | Prose summaries |

Daily notes record what happened. Learnings record what to do differently. Cross-reference via Related Files. Never duplicate content across layers.

## References

- Entry templates: `assets/` directory in this skill
- Full field descriptions: `references/entry-format-reference.md`
- Worked examples: `references/examples.md`