/self-evolve

name: self-evolve
description: >
  The single config quality skill. Two modes: (1) Default — review/wire pending self-improvement proposals. (2) Audit — analyzes skills, rules, CLAUDE.md, project refs, hooks, and agents against the actual codebase to find inaccuracies, trigger overlaps, stale references, and weak rules, then fixes them. Trigger on 'self-evolve', 'evolve', 'config health check', 'audit config', 'check claude setup', 'apply this rule', 'reorganize rules', 'ok' (when proposals are pending). NOT for improving individual skills (use skill-creator), diagnosing code bugs (use diagnose), or fixing broken code (use fix).
argument-hint: scope-or-focus-area

ultrathink.

Wire Mode: Apply Self-Improvement Proposals

When scope is `(none)`, or when pending proposals exist and user says "ok":

**Fetching proposals**:

python3 .claude/hooks/self-improve/self_improve_db.py resolve list

Step 0: Consolidate before showing

User attention is finite — showing 12 proposals when 4 are duplicates, 3 already exist in rules, and 2 are noise wastes their focus on what matters. Before presenting anything, read the existing config (`.claude/rules/`, CLAUDE.md, CLAUDE.local.md, active skills) to understand what's already there. Then filter: proposals already covered by existing rules, duplicates of each other, and low-value noise that wouldn't improve agent behavior. Merge proposals addressing the same pattern into one entry with the clearest rationale.

Tell the user what you filtered: "Showing X of Y proposals (Z filtered)."

After user finishes reviewing visible proposals, batch-reject the filtered ones:

python3 .claude/hooks/self-improve/self_improve_db.py resolve <id1>,<id2>,... rejected

For each shown proposal, ask the user to approve or reject.

Step 1: Classify — where does it belong?

| Test | Question | If Yes | |------|----------|--------| | **Rule test** | "Will an agent still produce incorrect code without this, even with the skill active?" | → Rule (`.claude/rules/`) | | **Skill test** | "Is this a repeatable process/workflow, not a constraint?" | → Skill — rare | | **On-demand ref** | "Is this project-specific architecture/context, not a behavioral rule?" | → Reference file pointed from CLAUDE.md | | **Personal pref** | "Is this specific to this user, not team-shared?" | → `CLAUDE.local.md` (gitignored) | | **Default** | None clearly match? | → Rule (safest default) |

~80% of proposals become rules — the pipeline detects behavioral corrections, and corrections are rules by definition.

Step 2: Read existing content, check for overlap

Read all files in the target location. Scan for semantic overlap — does an existing rule/section already cover this?

Step 3: Place — merge or add

• **If overlap exists**: merge into existing entry — expand/refine/strengthen, don't create near-duplicates
• **If distinct**: add under the most relevant section header

**Writing quality** — proposals describe specific incidents, but rules must work for the general case:

1. **Generalize from the incident.** The proposal says "Claude changed the pass dot when user meant N/A dot." The rule should address the *class*: "When multiple UI elements match an ambiguous reference, confirm which one before changing any." Don't encode the specific incident — encode the pattern. 2. **Ground in reasoning, not commands.** "ALWAYS confirm ambiguous references" is brittle — the agent doesn't know when it applies. "Because acting on the wrong target wastes a correction cycle, confirm which element when multiple candidates match" gives the agent judgment for edge cases. 3. **Trim while merging.** When adding to an existing rule file, read what's already there. If existing entries are redundant with the new content or with each other, consolidate. The goal after merging is a *tighter* file, not a longer one. 4. **Watch for accumulation.** If 3+ proposals have landed in the same file or section, that's a restructuring signal — the section may need splitting, or the underlying skill needs fixing instead of piling on more rules. 5. **Think from the agent's perspective.** Before finalizing, ask: "If I were an agent reading this rule for the first time with no context about the incident, would I understand *when* and *why* to apply it?" If the answer requires knowledge of the original proposal, rewrite. 6. **Re-read with fresh eyes.** After merging, re-read the entire section (not just your addition). Does the new content flow with the existing entries, or does it feel bolted on? Revise for coherence.

Step 4: Verify — smoke test

Use the proposal's `rationale` to construct a minimal replay prompt that would trigger the same mistake. Spawn a subagent with the new rule, give it the prompt, check if it avoids the failure. If it fails, revise once. If still fails, flag to user. Keep this fast — one prompt, one check.

Step 5: Resolve

python3 .claude/hooks/self-improve/self_improve_db.py resolve <id>[,<id>,...] approved  # or rejected

Step 6: Confirm

Tell the user: **what** was placed, **where** (file + section), **why** that location, and **whether verification passed**.

Manual reorganization

When invoked for rule reorganization (not proposals): read all `.claude/rules/`, identify duplicates/misplaced rules, propose consolidation plan, apply on approval.

---

Audit Mode: Proactive Config Analysis

When scope is `full`, `skills`, `rules`, `claude-md`, or `quick`. Also when `(none)` and no pending proposals found.

Phase 1: Understand the Project

1. Read `package.json`, `pyproject.toml`, `go.mod`, or equivalent — know the stack 2. Scan top-level directory structure — know the architecture 3. Read CLAUDE.md — know what config claims about the project 4. Read `.claude/settings.json` — know what hooks are configured 5. If `.claude/hooks/self-improve/` exists, check for pending proposals: `python3 .claude/hooks/self-improve/self_improve_db.py res