evolve

Evolve Roles

Try it: /roles:evolve — or say "audit the roles and propose refinements".

Graduation gets a learning into the role file. Evolution is the loop that keeps it useful afterwards: learnings consolidate as the same lesson recurs in new forms; entries go stale when the artifact they cite is renamed or removed; the Charter and Body drift out of date when the cumulative learnings have effectively re-shaped how the role behaves. Without this loop a role file calcifies — every new run appends, nothing refines, and after enough sessions the file is a layered archaeology no future reader will trust.

This skill runs that loop. Never silently rewrites a role file. Every proposal is shown to the user with the evidence; the user accepts, edits, or rejects each one.

Proactive runs and non-goals

Beyond the say-it phrases (in the description), run this when the SessionStart roles-init-audit.py hook surfaces high solo-learning counts (>15 per role) or cross-orchestrator usage signals — those are reactive nudges; this is the deeper pass that acts on them.

Not for one-off "add this learning to the role" edits: the orchestrator that produced the lesson appends directly, and a single new entry needs no audit.

The four audit dimensions

For each role file in .claude/roles/ (skipping consumer registries crew.md / panel.md / research.md / registry.md), run all four:

1. Consolidation candidates

When the same topic appears in ≥3 Learnings (core) entries — same artifact, same failure mode, same recurring critique — propose a single merged rule that captures the load-bearing pattern, and a proposed strike-through of the three originals.

Detection signal: clustering of backticked artifacts (same ClassName.method or path/to/file cited across multiple entries), or repeated lead phrases ("always", "never", "remember that").

Threshold: 3+ entries on one topic. Below that, individual entries still carry distinct nuance worth keeping.