Aif Evolve

Evolve - Skill Self-Improvement

Analyze project context, patches, and codebase to improve existing skills. Makes AI Factory smarter with every run.

Core Idea

patches (past mistakes) + project context + codebase patterns
    ↓
analyze recurring problems, tech-specific pitfalls, project conventions
    ↓
enhance skills with project-specific rules, guards, and patterns

Patch Consumption Policy

Use a two-layer learning model:

1. Raw patches (paths.patches, default: .ai-factory/patches/*.md) are the source material.
2. Skill-context rules (.ai-factory/skill-context/*) are the compact, reusable output.

Policy across workflow skills:

• /aif-evolve is the primary raw-patch analyzer. It processes patches incrementally using a cursor.
• /aif-implement, /aif-fix, and /aif-improve should prefer skill-context first; raw patches are fallback context only.
• Force full re-analysis only when needed (e.g., reset cursor and rerun evolve).

Critical: Never Edit Built-in Skills Directly

NEVER modify any files inside built-in aif-* skill directories (skills/aif-*/). All files in these directories are owned by ai-factory and will be overwritten on update — any direct edits will be lost.

ALWAYS write project-specific rules to skill-context:

.ai-factory/skill-context/<skill-name>/SKILL.md

This is the ONLY correct target for built-in skill improvements. No exceptions.

Workflow

Step 0: Resolve Target & Load Context

Step 0.1: Resolve Target

Normalize skill name from $ARGUMENTS:

Rule: first, strip any leading / from the argument. Then: if the argument does not start with aif- AND a skill named aif-<argument> exists — use aif-<argument>. Otherwise use as-is.

After resolving the skill name: verify that the resolved skill actually exists (check .agents/skills/<resolved-name>/SKILL.md or skills/<resolved-name>/SKILL.md). If the skill is not found → report an error to the user and stop: "Skill '<resolved-name>' not found. Use /aif-evolve without arguments to evolve all skills, or specify a valid skill name."

Determine which skills to evolve from $ARGUMENTS:

• If $ARGUMENTS contains a specific skill name → evolve only that skill
• If $ARGUMENTS is "all" or empty → evolve all installed skills

Step 0.2: Load Context

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, paths.rules_file, paths.rules, paths.patches, and paths.evolutions
• Language: language.ui for prompts and language.artifacts for generated reports
• Rules hierarchy: rules.base plus any named rules.<area> entries

If config.yaml doesn't exist, use defaults:

• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• ARCHITECTURE.md: .ai-factory/ARCHITECTURE.md
• RULES.md: .ai-factory/RULES.md
• rules/: .ai-factory/rules/
• patches/: .ai-factory/patches/
• evolutions/: .ai-factory/evolutions/
• Language: en (English)

Note: .ai-factory/skill-context/ remains a fixed internal AI Factory path in the current schema. Patch and evolution-log locations are configurable via paths.patches and paths.evolutions.

THEN: Read .ai-factory/DESCRIPTION.md (use path from config) to understand:

• Tech stack
• Architecture
• Conventions

Also read .ai-factory/ARCHITECTURE.md (use path from config) and the configured rules hierarchy when present. This context informs convention analysis and gap detection but does not change artifact ownership.

Read skill-context files for target skills:

• If evolving a specific skill (e.g., /aif-evolve plan) → read only:
  1. .ai-factory/skill-context/aif-plan/SKILL.md (target skill's context)
  2. .ai-factory/skill-context/aif-evolve/SKILL.md (evolve's own context, if exists and target skill is not aif-evolve itself)
• If evolving all skills (/aif-evolve or /aif-evolve all) → read all context files: Glob: .ai-factory/skill-context/*/SKILL.md (this already includes evolve's own context — do NOT read it separately)

These contain previously accumulated project-specific rules for built-in skills. Keep them in memory — they affect gap analysis in Step 5.

Skill-context rules are project-level overrides — when they conflict with the base SKILL.md of the target skill, skill-context wins (same principle as nested CLAUDE.md files).

How to apply evolve's own skill-context rules (aif-evolve):

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
• When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
• Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient
• CRITICAL: skill-context rules apply to ALL outputs of this skill — including the evolution report, proposed improvements, skill-context file edits, and stale rule analysis. If a skill-context rule says "evolve MUST prioritize X" or "report MUST include Y" — you MUST comply. Producing evolution output that ignores skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.

Step 1: Collect Intelligence

1.1: Read patches incrementally (cursor-based)

Glob: <resolved patches dir>/*.md

Cursor file:

<resolved evolutions dir>/patch-cursor.json

Recommended shape:

{
  "last_processed_patch": "YYYY-MM-DD-HH.mm.md",
  "updated_at": "YYYY-MM-DD HH:mm"
}

Processing rules:

1. Glob patch files and sort by filename ascending (timestamp format is lexical-friendly).
2. If no cursor file exists → first run: read all patches.
3. If cursor file exists and referenced patch is present → read only patches with filename > last_processed_patch.
4. If cursor file exists but referenced patch is missing (deleted/renamed) → emit WARN [evolve] and do a full rescan.
5. Historical edits/deletes for patches older than cursor are not reliably detectable without a saved baseline (snapshot/hash manifest). Do NOT emit this warning by default.
6. Emit WARN [evolve] for historical drift only when a reliable baseline exists and drift is actually detected.
7. Full rescan procedure: delete <resolved evolutions dir>/patch-cursor.json, then run /aif-evolve again.
8. Do not advance cursor in Step 1.1. Cursor is updated only after successful apply/log write in Step 7.3.

Overlap window (anti-miss guard):

LLMs may miss prevention points on a single pass. To reduce the chance of "permanently skipping" a patch when running incrementally:

9. When running in incremental mode (cursor exists and referenced patch is present), ALSO read the newest 5 patches by filename (tail-5 of the sorted patch list), then de-duplicate by filename.
10. Track these separately in your own notes:

• "New patches" = patches with filename > last_processed_patch
• "Overlap patches" = tail-5 patches
• "Processed patches" = union(New, Overlap)

11. Cursor updates in Step 7.3 MUST be based on "New patches" only (never advance cursor when only overlap patches were processed).

Read every patch. For each one, extract:

• Problem categories (null-check, async, validation, types, API, DB, etc.)
• Root cause patterns (what classes of mistake were made)
• Prevention points — each independent actionable rule from the Prevention/Solution section. A single patch often contains multiple independent prevention points targeting different skills. Extract EACH one separately with its target skill(s). Do NOT treat a patch as a single unit.
• Tags

Build a Prevention Point Registry — a flat list of ALL extracted prevention points across the processed patch set in this run. This registry is the primary input for Step 5 gap analysis.

| # | Patch | Prevention Point (specific action) | Target Skill(s) |
|---|-------|------------------------------------|-----------------|
| 1 | <patch-file> | <concrete action to enforce> | <skill-1> |
| 2 | <patch-file> | <different action from same patch> | <skill-1>, <skill-2> |
| 3 | <other-patch> | <action> | <skill-3> |

CRITICAL: A patch with 5 prevention points produces 5 rows, not 1. If a prevention point targets 2 skills, it appears once but with both skills listed — and EACH skill must be checked independently in Step 5.

When the run is incremental, this registry reflects the processed patch set for this run (new + overlap). Use full rescan when you need full historical backfill.

1.2: Aggregate patterns

Group patches by tags and categories. Identify:

• Recurring problems — same tag appears 3+ times? This is a systemic issue
• Tech-specific pitfalls — problems tied to the stack (e.g., React re-renders, Laravel N+1)
• Missing guards — what checks/patterns could have prevented these bugs

1.3: Read codebase conventions

Scan the project for patterns:

• Linter configs (.eslintrc, phpstan.neon, ruff.toml, etc.)
• Existing test patterns (test file structure, assertions used)
• Error handling patterns (try/catch style, error types)
• Logging patterns (logger used, format, levels)
• Import conventions, file structure

When evolving a specific skill, focus convention scanning on areas relevant to that skill (e.g., for /aif-plan — focus on file structure and naming; for /aif-fix — error handling and testing).

Step 2: Read Target Skills

Read ONLY the base SKILL.md files for target skills — not all skills.

• If evolving a specific skill (e.g., /aif-evolve plan) → read only that one: Read: .agents/skills/aif-plan/SKILL.md (or skills/aif-plan/SKILL.md if not installed)
• If evolving all skills (/aif-evolve or /aif-evolve all) → read all: Glob: .agents/skills/*/SKILL.md (or Glob: skills/*/SKILL.md if not installed)

Keep loaded SKILL.md content in memory — Step 3 needs it for comparison (do NOT re-read).

Step 3: Check for Stale Rules in Skill-Context

When: Run this step for every target aif-* skill that has a skill-context file.

For each rule in .ai-factory/skill-context/<skill-name>/SKILL.md:

Scope constraint: Step 3 can ONLY modify or remove skill-context files. It must NEVER propose editing, deleting, or reverting base skills/aif-*/ files. Even if the base file contains errors or incomplete rules — that is outside evolve's scope.

1. Use the base SKILL.md already loaded in Step 2 (do NOT re-read the file).

2. Compare each skill-context rule against the base SKILL.md content:

   Case A — Base fully covers skill-context rule (equivalent or superset): The base SKILL.md now contains a rule that is equivalent to or MORE complete than the skill-context rule. This includes:

   • Exact equivalent — same rule, same content
   • Base is a superset — base has everything skill-context has, plus more (e.g., skill-context has Wave 1+3, base now has Wave 1+2+3) → Do NOT auto-remove. Do NOT ask the user yet. → Collect for the report in Step 4 — include both rules and mark as "Fully covered by base — recommend removing from skill-context". Note: if user chooses to keep the skill-context rule, this is valid — skill-context has priority over base, so keeping it acts as a guarantee that the complete/correct version is always applied.

   Case B — Contradicting rule found in base SKILL.md: The base skill now has a rule that directly contradicts the skill-context rule. → Do NOT auto-remove. Do NOT ask the user yet. → Collect this conflict for the report in Step 4 — include both rules and mark as "Conflict — user decision required".

   Case C — Partial overlap (in either direction): The base SKILL.md and skill-context rule overlap, but NEITHER fully covers the other. This includes:

   • Base covers part of skill-context, but skill-context has unique parts too
   • Skill-context covers part of base, but base has unique parts too (e.g., skill-context has A→B→C, base has A→C→D — both have unique parts) → Do NOT auto-narrow. Analyze whether parts depend on each other (ordering, prerequisites, data flow). → Collect this overlap for the report in Step 4 — include both rules, analysis, and mark as "Partial overlap — user decision required". Priority warning: skill-context has priority over base on the same topic. If user keeps skill-context as-is, the base's unique parts will likely be LOST (AI uses skill-context version, ignores base version of the same rule). Always explain this consequence in option descriptions.

   Case D — No overlap: The rule is still unique to the project context. → Keep as-is, no action needed.

Step 4: Present & Resolve Stale Rules

Skip this step if no Case A/B/C rules were found in Step 3.

Present all stale rule findings using the stale rules report format (Case A/B/C sections with base vs skill-context comparison).

IMPORTANT: All decisions here affect ONLY skill-context files. Never propose editing, deleting, or reverting base skills/aif-*/ files — they are outside of evolve's scope.

Stale Rules Report Format

For each stale rule, present:

/aif-plan — Fully covered: [Rule Name]

• Base SKILL.md says: [base rule text]
• Skill-context says: [project rule text]
• Decision required: Keep in skill-context (has priority over base — ensures the complete version is always applied) / Remove from skill-context (trust base) / Rewrite skill-context rule

/aif-plan — Conflict: [Rule Name]

• Base SKILL.md says: [base rule text]
• Skill-context says: [project rule text]
• Decision required: Keep skill-context rule (has priority — base version will be ignored) / Remove skill-context rule (trust base) / Rewrite skill-context rule

/aif-fix — Partial overlap: [Rule Name]

• Base SKILL.md says: [base rule text]
• Skill-context says: [project rule text]
• Analysis: [explain overlap and whether parts are independent or sequential]
• Decision required: Rewrite skill-context to include both unique parts (recommended when parts are sequential) / Keep skill-context as-is (WARNING: base's unique parts will be lost — skill-context has priority) / Narrow skill-context to uncovered part / Remove from skill-context (trust base — skill-context's unique parts will be lost)

Collecting Decisions

Use AskUserQuestion to collect stale rule decisions. Process in batches of up to 3 decisions per AskUserQuestion call:

• Present first batch (up to 3 stale rules) → AskUserQuestion
• Get answers → apply decisions
• If more stale rules remain → present next batch → AskUserQuestion
• Repeat until all stale rules are resolved

Do NOT proceed to Step 5 until all stale rule decisions are collected and applied. This determines the actual skill-context state for gap analysis.