# Evolve

> Analyze and evolve the knowledge base and project configuration. This is the meta-improvement loop.

- Skill: `antonioshaman/evolve` (Agent Skill)
- Install (CLI): `npx skillmds@latest add antonioshaman/evolve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/antonioshaman/evolve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: antonioshaman (https://skillmd.com/u/antonioshaman)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/antonioshaman/evolve

---


Analyze and evolve the knowledge base and project configuration. This is the meta-improvement loop.

## Process

### 1. Audit Knowledge Base Health

Read all `.agents/knowledge/*.jsonl` files and compute:

- **Total entries** per category
- **Confidence distribution** (how many high/medium/low)
- **Age distribution** (entries older than 30 days may be stale)
- **Tag coverage** (which areas of the codebase have knowledge, which don't)

### 2. Promote Recurring Patterns (mode: promote)

When a pattern appears 3+ times across sessions or has high confidence with broad impact:

1. Extract the core rule
2. Add it to the appropriate section in `CLAUDE.md`
3. Mark the KB entry as `promoted: true` (keep for history, but no longer surfaced by `/prime`)

**Example promotion:**
- KB entry: "Always test WebSocket changes against both NDJSON and JSON-RPC backends"
- → Becomes a bullet point in CLAUDE.md's Architecture section

### 3. Prune Stale Entries (mode: prune)

An entry is stale when:
- It references a file that no longer exists
- It describes a bug that's been fixed (check git log)
- Its recommendation contradicts a newer entry
- It has `confidence: low` and is older than 14 days without re-confirmation
- `outdatedReports >= helpfulCount` and `outdatedReports >= 2` (the field-driven signal — at least two flags and no fresh confirmations to balance them)
- `usageCount >= 10` and `helpfulCount == 0` (surfaced often but never re-confirmed → too generic to be useful)

**Actions:**
- Remove clearly stale entries
- Downgrade confidence on questionable entries
- Flag uncertain entries for human review

### 4. Identify Knowledge Gaps (mode: gaps)

Cross-reference:
- Files in `web/server/` and `web/src/` that have NO knowledge entries tagged to them
- Recent commits that touched areas with no KB coverage
- Test files without corresponding gotchas or patterns

Output a list of suggested areas to investigate.

### 5. Suggest New Skills

If the knowledge base reveals:
- A repeated workflow that takes multiple steps → suggest a new skill to automate it
- A category of gotchas around a specific tool/library → suggest a targeted skill
- A testing pattern used frequently → suggest codifying it as a skill

### 6. Report

```
## Evolution Report

### Knowledge Base Health
- Total entries: N (patterns: X, gotchas: Y, decisions: Z, ...)
- Confidence: H high, M medium, L low
- Coverage: N/M source files have associated knowledge

### Actions Taken
- Promoted N patterns to CLAUDE.md
- Pruned N stale entries
- Downgraded N entries to lower confidence

### Knowledge Gaps
- [area]: no entries covering [specific aspect]

### Suggested Skills
- [skill-name]: [why it would be useful]

*Next evolution recommended: [date]*
```

## When to Run

- After 5+ sessions of accumulated learning
- When the knowledge base exceeds 50 entries
- Monthly as maintenance
- When CLAUDE.md feels out of sync with actual development practices