← Core Skills · Back to README · Plan Files →
Every /ww-fix leaves behind a patch — a structured record of what went wrong and how it was fixed. /ww-evolve processes patches incrementally, analyzes your project's tech stack and conventions, and turns recurring patterns into rules that make skills smarter. The more you fix, the better the evolution.
/ww-fix patches/ /ww-evolve skill rules
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Find bug │ ───▶ │ Save patch │ ───▶ │ Analyze new │ ───▶ │ Add rules to │
│ Fix it │ │ with root │ │ patches + │ │ skills so │
│ Log it │ │ cause + tags │ │ project ctx │ │ they don't │
└──────────┘ └──────────────┘ └──────────────┘ │ repeat the │
▲ │ same bugs │
│ └──────┬───────┘
│ │
└──────────── better /ww-fix, /ww-do, /ww-review ◀────┘
Each iteration of this loop makes the AI more aware of your project's pitfalls. After 10 fixes, /ww-evolve has enough signal to add targeted guards — not generic advice, but rules derived from real bugs in your codebase.
Incremental state file:
.ww-kit/evolutions/patch-cursor.json
- No cursor: first evolve run reads all patches
- Cursor present: evolve reads new patches newer than cursor, plus a small overlap window (reruns help catch missed points)
- Full rescan: delete cursor file and rerun
/ww-evolve
Built-in aif-* skills ship with ww-kit and get overwritten on update. To keep project-specific rules stable, /ww-evolve writes them to a separate location:
.ww-kit/skill-context/<skill-name>/SKILL.md
Key properties:
- Survives
ww-kit update— lives in your project, not in the package - Higher priority than base rules — when a skill-context rule conflicts with a base SKILL.md rule, the skill-context rule wins (same principle as nested CLAUDE.md files)
- Cumulative — each
/ww-evolverun adds new rules, updates existing ones, and removes stale ones
Important: skill-context files are always written in English, regardless of the project's language — they are consumed by AI agents, and English ensures consistent interpretation.
# Project Rules for /ww-fix
> Auto-generated by `/ww-evolve`. Do not edit manually.
> Last updated: 2026-02-15 14:30
> Based on: 12 analyzed patches
## Rules
### Null-check for optional relations
**Source**: 2026-02-10-09.15.md, 2026-02-12-16.45.md, 2026-02-14-11.20.md
**Rule**: Check for optional/nullable fields before accessing nested
properties. This is the #1 source of bugs in this project — 5 of 12
patches involved null references on optional DB relations.
### Prisma unique constraint
**Source**: 2026-02-13-10.00.md
**Rule**: Before `create()` calls on models with unique fields, check
for existing records with `findUnique()`. Use upsert when appropriate.Every aif-* skill reads its own context file at startup (Step 0 in each SKILL.md):
Read .ww-kit/skill-context/<skill-name>/SKILL.md
If the file exists, the skill treats its rules as project-level overrides — more specific context always wins over general instructions.
/ww-evolve # Evolve all skills
/ww-evolve fix # Evolve only /ww-fix
/ww-evolve implement # Evolve only /ww-do
/ww-evolve all # Evolve all skills (explicit)
Skill name is normalized automatically: fix → ww-fix, /ww-plan → ww-plan. If the resolved skill does not exist, an error is reported and evolution stops.
| Step | What happens |
|---|---|
| 0: Resolve target & load context | Normalize skill name, validate it exists. Read DESCRIPTION.md and skill-context files. For single-skill mode — only that skill's context + evolve's own. For all — glob all context files (no duplicates) |
| 1: Collect intelligence | Read patches from .ww-kit/patches/ incrementally (first run reads all; later runs read only new patches by cursor + a small overlap window to catch missed points), extract each independent prevention point with its target skill(s), and build a Prevention Point Registry for the processed set (a patch with 5 points = 5 rows). Group by tags, find recurring patterns. Scan the project for conventions (linters, test patterns, error handling, logging, imports). For single-skill mode — focus convention scanning on areas relevant to that skill |
| 2: Read target skills | Load base SKILL.md only for target skills — not all. For /ww-evolve plan — read only ww-plan/SKILL.md. Keep in memory for Step 3 (no re-reads) |
| 3: Check for stale rules | Compare each skill-context rule against base SKILL.md. Classify as: fully covered (Case A), contradiction (Case B), partial overlap (Case C), or still unique (Case D). See Stale Rule Cleanup |
| 4: Present & resolve stale rules | Present stale rule findings to user in batches of up to 3 via AskUserQuestion. Collect decisions (keep / remove / rewrite) and apply them before proceeding |
| 5: Analyze gaps | Re-read skill-context files modified in Step 4. Prevention-point-exhaustive analysis: iterate over every row in the Prevention Point Registry and check each (prevention_point × target_skill) pair independently. A prevention point is "covered" only when a rule addresses the specific action — not merely when the same patch filename appears in a Source field. A gap exists only if neither the base SKILL.md nor the current skill-context covers the specific prevention point |
| 6: Generate improvements | Create concrete, traceable improvements — each linked to specific patches or conventions. One prevention point = one rule. Preserve concrete formats from patches verbatim |
| 7: Present & apply | Show improvement report, ask for approval (apply all / let me pick / save report only). For "let me pick" — present in batches of up to 4. Apply approved changes, update metadata, save evolution log to .ww-kit/evolutions/ |
| 8: Suggest next actions | Recommend /ww-review, next evolution timing, or new skill creation via /wws-skill |
| Skill type | Where rules are written | Why |
|---|---|---|
Built-in (aif-*) |
.ww-kit/skill-context/<skill-name>/SKILL.md |
Base SKILL.md is overwritten on update |
| Custom (project skills) | skills/<skill-name>/SKILL.md (direct edit) |
You own the file, no risk of overwrite |
When ww-kit is updated, base SKILL.md files may incorporate rules that were previously only in your skill-context. Steps 3-4 handle this.
All decisions affect ONLY skill-context files. Evolve never proposes editing base skills/ww-*/ files — even if they contain errors, that is outside evolve's scope.
The upstream SKILL.md now contains an equivalent or more complete version of the skill-context rule (e.g., skill-context has Wave 1+3, base now has Wave 1+2+3).
Options:
- 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
A new base rule conflicts with your project rule.
Options:
- Keep skill-context rule — has priority, base version will be ignored
- Remove skill-context rule — trust base
- Rewrite skill-context rule
Base and skill-context overlap but neither fully covers the other. Evolution analyzes whether parts depend on each other (ordering, prerequisites).
Options:
- 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 — when parts are independent
- Remove from skill-context — trust base (skill-context's unique parts will be lost)
No overlap with base. Kept as-is, no action needed.
Stale rule decisions are collected in batches of up to 3 per AskUserQuestion call. All stale rules must be resolved before gap analysis begins (Step 5).
If all rules in a skill-context file are removed, the file and its directory are deleted.
- After 5-10 fixes — enough patches for meaningful pattern detection
- After changing tech stack — new framework or library means new pitfalls to learn
- When the same bug type keeps recurring — a signal that skills need a targeted guard
- After an
ww-kit update— stale rule cleanup removes rules now covered upstream
- Development Workflow — where
/ww-evolvefits in the development loop - Core Skills — full reference for
/ww-evolveand other skills - Plan Files — patches, plans, and other workflow artifacts