The evolution Skill — Framework Self-Update Rules
How Datarim proposes and applies improvements to its own framework after compliance, on demand, and on explicit request — while keeping every change human-approved and independently reversible.
A framework used across many tasks will accumulate friction over time: a skill that describes a pattern no longer used, two skills with overlapping concerns, a description that was accurate six months ago but has since drifted from what the code actually does. The evolution skill defines the rules by which Datarim corrects itself.
Every change requires explicit human approval. The skill does not apply anything speculatively.
Two paths to change
Growth starts after a passing /dr-compliance. The reflecting skill reviews the completed work, identifies patterns that would benefit future tasks, and generates evolution proposals. If that reflection is absent or stale when archival begins, /dr-archive Step 0.5 supplies the fallback instead of silently skipping it. Proposals might update an existing skill, refine an agent description, add a template for a recurring pattern, or create a distinct skill for an uncovered domain. Each one carries a category, target file, concise change description, and motivating evidence.
A follow-up discovered during reflection is returned to the archive stage for explicit backlog allocation. Framework changes still require human approval, and a Class B proposal that changes an existing contract also requires the relevant PRD to be updated before implementation.
Maintenance runs through /dr-optimize. The optimizer builds a dependency graph of the full framework, finds unused components, oversized files, duplicate skills, and broken cross-references, then presents a structured report with proposals to prune, merge, or split components.
Health thresholds
The skill defines concrete thresholds that trigger an optimization suggestion. More than 20 skills, more than 18 agents, more than 25 commands, any single skill over 500 lines, any description over 155 characters, or an orphan rate above 15% — any of these prompts a suggestion to run /dr-optimize. The thresholds exist because every new file and every longer description adds to the token budget each pipeline command must pay at invocation.
One concrete example
A task reflection notes that a property-based testing approach caught edge cases that unit tests missed. The reflecting skill generates a growth proposal: category skill-update, target skills/testing/SKILL.md, change: add a property-based testing section with a concrete example. The operator approves. The skill file is updated in place. The change is recorded in datarim/history/evolution-log.md with the task ID, category, target, and a one-line rationale.
Anti-bloat rule and rollback
Before any proposal to create a new file, the skill requires checking whether an existing component could absorb the content. Every new file increases the cold-path overhead for agents that load it. A proposal for a new skill only proceeds if the content is clearly a distinct concern that no existing skill covers.
Each approved change is a discrete edit to a specific file. The evolution log records enough information to undo any change manually. For prune operations, the optimizer archives deleted files to documentation/archive/optimized/ before removal. Since 2026-04-25, skills, commands, agents, and templates in $HOME/.claude/ are symlinks to the Datarim git repository — reverting a change is a standard git revert.
Read the /dr-compliance command post for the primary completion gate, the /dr-archive command post for the fallback and backlog route, and what Datarim is for the broader framework picture.