self-improvement

name

self-improvement

description

Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects the agent ('No, that's wrong...', 'Actually...'), (3) User requests a capability that doesn't exist, (4) An external API or tool fails, (5) The agent realizes its knowledge is outdated or incorrect, (6) A better approach is discovered for a recurring task. Also review learnings before major tasks.

Self-Improvement Skill

Log learnings and errors to markdown files for continuous improvement. Coding agents can later process these into fixes, and important learnings get promoted to project memory.

Not for general Q&A, coding tasks, or ad-hoc reasoning. Use only to log, review, and promote learnings/errors/feature requests.

Context discipline: Do not open whole log files; append directly or read only a small slice around the target entry.

Memory Index (progressive loading)

Purpose	Path
Learnings log	.learnings/LEARNINGS.md
Errors log	.learnings/ERRORS.md
Feature requests	.learnings/FEATURE_REQUESTS.md
Formats reference	references/formats.md
Examples	references/examples.md
Promotion guide	references/promotion.md
Review workflow	references/review.md

Maintain this table when adding new reference files; keep descriptions short so only the needed file is opened.

Progressive Loading Rules

• Do not load whole log files by default. Append directly to the correct file; if you must inspect, read only the relevant entry or a small surrounding slice.
• Use grep/search first to find matching IDs or keywords before opening anything large.
• Only load reference files (formats/examples/promotion/review) when you need their content.

Quick Reference

Situation	Action	Details
Command/operation fails	Log to .learnings/ERRORS.md	Format
User corrects you	Log to .learnings/LEARNINGS.md	Category: correction
User wants missing feature	Log to .learnings/FEATURE_REQUESTS.md	Format
API/external tool fails	Log to .learnings/ERRORS.md	Include integration details
Knowledge was outdated	Log to .learnings/LEARNINGS.md	Category: knowledge_gap
Found better approach	Log to .learnings/LEARNINGS.md	Category: best_practice
Similar to existing entry	Link with See Also	Consider priority bump
Broadly applicable learning	Promote to CLAUDE.md/AGENTS.md	Guide

Setup

Create .learnings/ directory in project root:

mkdir -p .learnings
```text

Copy template files from `assets/` or create files with headers:

- `LEARNINGS.md` - Corrections, insights, knowledge gaps
- `ERRORS.md` - Technical failures and bugs
- `FEATURE_REQUESTS.md` - Requested capabilities

Templates available in `assets/` directory.

## Core Workflow

### 1. Log the Entry

When you encounter a triggering situation:

0. **Search first**: `grep -r "keyword" .learnings/` to avoid duplicates; link if related.
1. Determine entry type (learning, error, or feature request)
2. Generate ID: `TYPE-YYYYMMDD-XXX` (e.g., `LRN-20250108-001`)
3. Append entry to appropriate file without loading the full file; if you need context, read only the nearby lines for the target section.
4. Use the format from [references/formats.md](references/formats.md)

**Quick format overview:**

```markdown
## [TYPE-YYYYMMDD-XXX] category_or_name

**Logged**: 2025-01-08T12:00:00Z
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description

### Details / Error / Requested Capability
[Context specific to entry type]

### Suggested Action / Fix / Implementation
What should be done

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: [related entry IDs]

---

See references/formats.md for complete templates and references/examples.md for real examples.

2. Resolve When Fixed

Update the entry when addressed:

1. Change **Status**: pending → **Status**: resolved
2. Add resolution block:

### Resolution
- **Resolved**: 2025-01-09T10:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of fix

3. Promote If Applicable

When a learning is broadly applicable, promote to permanent documentation:

• CLAUDE.md: Project context, conventions, architecture
• AGENTS.md: Automation workflows, tool usage patterns

See references/promotion.md for detailed promotion guidelines.

Detection Triggers

Log automatically when you notice:

Corrections → learning with correction category:

• "No, that's not right..."
• "Actually, it should be..."
• "You're wrong about..."

Feature Requests → feature request entry:

• "Can you also..."
• "I wish you could..."
• "Is there a way to..."

Knowledge Gaps → learning with knowledge_gap category:

• User provides information you didn't know
• Documentation you referenced is outdated
• API behavior differs from your understanding

Errors → error entry:

• Command returns non-zero exit code
• Exception or stack trace
• Unexpected output or behavior

Priority Guidelines

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

Recurring Pattern Detection

If logging something similar to an existing entry:

1. Search first: grep -r "keyword" .learnings/
2. Link entries: Add **See Also**: ERR-20250110-001 in Metadata
3. Bump priority if issue keeps recurring
4. Consider systemic fix:
   • Missing documentation → promote to CLAUDE.md
   • Missing automation → promote to AGENTS.md
   • Architectural problem → create tech debt ticket

Periodic Review

Review .learnings/ regularly to:

• Resolve fixed items
• Promote applicable learnings
• Link related entries
• Escalate recurring issues

See references/review.md for review commands and workflow.

Best Practices

1. Log immediately - context is freshest right after the issue
2. Be specific - future agents need to understand quickly
3. Include reproduction steps - especially for errors
4. Link related files - makes fixes easier
5. Suggest concrete fixes - not just "investigate"
6. Use consistent categories - enables filtering
7. Promote aggressively - if in doubt, add to CLAUDE.md
8. Review regularly - stale learnings lose value

Reference Documentation

• references/formats.md - Complete entry format specifications
• references/examples.md - Real-world examples with all fields
• references/promotion.md - Guidelines for promoting to project memory
• references/review.md - Commands and workflow for periodic review

Assets

• assets/LEARNINGS_template.md - Template file for learnings
• assets/ERRORS_template.md - Template file for errors
• assets/FEATURE_REQUESTS_template.md - Template file for features