--- 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**: ```bash 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: ```bash python3 .claude/hooks/self-improve/self_improve_db.py resolve ,,... 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 ```bash python3 .claude/hooks/self-improve/self_improve_db.py resolve [,,...] 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 resolve list` ### Phase 2: Analyze Read `references/quality-dimensions.md` for mechanical check scripts, staleness signals, and conflict resolution rules. Then run per-component analysis — see `references/audit-guide.md` for the full checklist covering skills, rules, CLAUDE.md, CLAUDE.local.md, and hooks. ### Phase 3: Fix **Severity**: CRITICAL (wrong code/skill, broken refs) → fix. MODERATE (suboptimal output) → fix if easy. LOW (style) → report only. Fix: broken refs, inaccurate facts, trigger overlaps, weak/stale rules, redundant cross-layer content, broken hooks, orphaned project refs. Don't fix: workflow skill descriptions (report for skill-creator), substantial completeness gaps (report as recommendation), things that work. ### Phase 4: Verify For each fix: re-read, re-run the specific check, confirm it passes. Check no new broken refs introduced. ### Phase 5: Report Use the report template in `references/audit-guide.md § Report Template`. Health verdicts: HEALTHY (0 CRITICAL, ≤2 MODERATE) | NEEDS ATTENTION (unfixed MODERATE or 1 CRITICAL) | CRITICAL ISSUES (2+ CRITICAL). ## Constraints - **Stay in your lane.** Config quality + proposals only. Not for creating skills, priming projects, or fixing code bugs. - **Fix what's broken, not what's working.** Respect knowledge layers: skills teach, rules guard, refs provide context. - **Don't bloat.** If a fix requires 50+ new lines, report as recommendation. - **Don't weaken when merging.** Combined version must be at least as strong as the original.