Evolution
Rules for proposing and applying framework improvements. Covers growth (new components) and maintenance (pruning, merging). Human approval required.
Overview
Evolution governs how Datarim improves itself over time through two paths: Growth (new components proposed during /dr-archive Step 0.5 via the reflecting skill) and Maintenance (pruning, merging, and efficiency improvements via /dr-optimize). Every change requires explicit human approval — the framework never modifies itself speculatively.
Growth Path
After each completed task, the reflect stage analyzes lessons learned and may propose improvements: updating an existing skill with new patterns, refining agent capabilities, adding templates for recurring patterns, or creating new skills for uncovered domains. Each proposal includes category, target file, what/why/impact, and a diff preview.
Maintenance Path
The optimizer agent performs a full audit: builds a dependency graph of commands, agents, and skills; detects unused, oversized, duplicate, and broken components; and generates optimization proposals — prune, merge, split, rewrite, or fix references.
Anti-Bloat Rule
Always prefer updating existing files over creating new ones. Before proposing a new skill, check if an existing one can absorb the content. Framework bloat degrades agent performance — every new file adds to context loading overhead.
Health Metrics
- Total skills > 20 triggers optimization suggestion
- Total agents > 18 triggers optimization suggestion
- Any skill > 500 lines should be split
- Total description characters > 8000 triggers shortening
- Orphan rate > 15% triggers pruning
Class A vs Class B Gate
Not all proposals are equivalent. Class A (content changes — add a recipe, fix a description, update a skill) go through normal reflection approval. Class B (operating-model changes — source-of-truth direction, sync semantics, pipeline routing, core contract) require a PRD update before approval. This gate was introduced after TUNE-0002/TUNE-0003 where a research conclusion was treated as a regular proposal and caused 6 hours of wrong-direction work.
Deprecation Pattern
When a concept or command is removed/renamed, use forward-pointer annotations in historical references instead of rewriting history. Delete the live artifact, sweep all spec/doc files with the new name, and preserve historical mentions with an annotation citing the version and task ID. A sweep-test guards against accidental re-introduction.
Rollback
Each evolution change is a discrete edit to a specific file. For pruned components, backups are saved to documentation/archive/optimized/. Changes are designed to be independently revertable — if two proposals modify the same file, they are applied as separate edits.