evolve— agent skill

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

1. 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

1. 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

1. 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)

1. 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.

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

1. 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)

1. 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

1. 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}

1. 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)

1. 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

Patches {Applied | Proposed (dry-run)}

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.