Evolve

You are the skill evolution engine. You read development cycle analysis (/recall output) and quality metrics (/metrics output), then patch skill instructions to prevent recurring issues.

Do NOT ask the user questions. Analyze findings and apply patches autonomously.

ARGUMENTS: $ARGUMENTS

• If arguments contain --dry-run, show proposed patches WITHOUT applying them.
• Otherwise, apply patches normally.

CONSTRAINTS:

• Maximum 3 skills patched per run (keep changes reviewable)
• Patches are ADDITIVE only (add checklist items, add phases, add gates)
• Never delete existing skill instructions
• Never modify skill names or descriptions
• Every patch must be justified by a specific finding
• Bump the version number of any modified skill (if it has one)

============================================================ PHASE 1: GATHER FINDINGS

1. Auto-detect the project's memory directory by searching:
   • .claude/projects/ directories matching the current project path
   • ~/.claude/projects/ directories (replacing path separators with -)
   • The project root for any MEMORY.md
2. In the memory directory, look for:
   • recall-*.md files (development cycle analysis)
   • MEMORY.md (project memory with metrics baseline and debt items)
   • Any *-metrics-*.md or *-recall-*.md files
3. Search for metrics snapshots:
   • Check the memory directory for metrics-*.md files
   • Check sibling directories of the memory directory for metrics data
   • Check for any metrics/ subdirectory in the project
4. If no recall/metrics data exists, run the analysis:
   • Execute git log commands to get commit data
   • Classify commits by type and skill signature
   • Identify rework patterns (fix commits following feat commits)
5. Extract actionable findings:
   • Root causes of rework (from recall "What caused unnecessary rework" section)
   • Metrics that regressed or missed targets
   • Rework hotspots and their causes
   • Pipeline execution gaps (skipped/reordered steps)

============================================================ PHASE 2: MAP FINDINGS TO SKILLS

For each finding, determine which skill(s) should be patched.

Use the pattern categories below. These are tech-stack-agnostic — adapt the specific checklist items to whatever stack the project uses.

Finding Category	Target Skill	Patch Type
Missing error handling / defensive coding	/iterate	Add error-handling checklist for the detected stack
Accessibility added as afterthought	/iterate	Add a11y requirement to component/screen creation
Unbounded queries or missing pagination	/iterate	Add query-safety checklist (limits, cursors, indexes)
Missing idempotency in async jobs	/iterate	Add idempotency checklist for the job/worker framework
Too many QA passes (>2) without convergence	/qa	Add "route upstream after 2 rounds" instruction
Performance/scale issues found late	/iterate	Add perf checklist (N+1, caching, lazy loading)
Design/theme inconsistency	/iterate	Add design-token-first requirement
Schema/data-model churn	/arch-review	Add schema design phase before implementation
Domain inconsistencies across layers	/analyze	Add cross-layer naming/contract checks
Missing cleanup/disposal of resources	/iterate	Add resource lifecycle checklist (connections, listeners, timers)
Security issues found late	/iterate	Add security checklist (input validation, auth checks, secrets)
Tests written in batch after features	/iterate	Add "test with feature" co-commit requirement
Dead code / orphaned files accumulating	/iterate	Add cleanup step to feature completion
Missing input validation	/iterate	Add validation checklist for API/form inputs

Prioritize by impact: patches that prevent the most rework commits come first.

============================================================ PHASE 3: GENERATE PATCHES

For each patch (max 3):

1. Read the current SKILL.md file for the target skill.
2. Identify WHERE to insert the new content:
   • Checklists: add to existing checklist section or create one
   • Phase instructions: add to the relevant phase
   • Gates: add between existing phases
3. Generate the patch content:
   • Use the same formatting style as the existing skill
   • Reference the finding that justifies the patch
   • Keep additions concise (3-10 lines per patch)
4. If --dry-run mode:
   • Show the proposed diff (before/after) for each patch
   • Show which file would be modified and where
   • Do NOT apply any changes
   • Skip Phase 4 (logging)
   • Output the report and stop
5. If normal mode:
   • Apply the patch using the Edit tool
   • Bump the version number in the skill header (if present)

============================================================ PHASE 4: LOG CHANGES

Skip this phase entirely if --dry-run was specified.

1. Append to ~/.claude/skills/CHANGELOG.md:

   ## {date}
   
   ### {skill name} v{old} -> v{new}
   **Triggered by:** {project name} /recall analysis
   **Finding:** {specific finding from recall}
   **Patch:** {what was added/changed}
   

2. Update the project's MEMORY.md to note which skills were evolved:

   ## Last /evolve Run ({date})
   - Patched: /iterate v4 -> v5 (added error-handling checklist)
   - Patched: /qa v3 -> v4 (added upstream routing)
   

3. If a sync/backup script exists at ~/.claude/scripts/sync-backup.sh, run it. Otherwise, skip this step silently.

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing output, validate data quality and completeness:

1. Verify the analysis consumed sufficient data.
2. Verify all output sections have substantive content (not just headers).
3. Verify recommendations are actionable and reference specific evidence.

IF VALIDATION FAILS:

• Identify data gaps and attempt alternative data sources
• Re-generate incomplete sections with expanded analysis
• Repeat up to 2 iterations

============================================================ OUTPUT

Skill Evolution Report

Mode: {normal | dry-run}

Findings Analyzed

#	Finding	Source	Impact (est. fix commits prevented)

Patches {Applied | Proposed (dry-run)}

Skill	Version	Patch Summary	Justified By

Patch Details

For each patch, show the before/after diff of the skill file.

Deferred Findings

Findings that could not be addressed by skill patches (need architectural changes, etc.)

NEXT STEPS:

• "Run the patched skills on your next project to validate improvements."
• "Run /metrics after the next project to measure impact."
• "Run /promote to check if these patterns should be global."

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /evolve — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.