Unikit Evolve

Evolve — Rules Discovery from Patches

Analyze accumulated patches (past mistakes) and propose new rules: coding rules → .unikit/RULES.md, workflow rules → .unikit/skill-context/<skill>/SKILL.md.

Core Idea

patches (past mistakes)
    |
extract prevention points (concrete, actionable rules)
    |
classify: coding rule vs workflow rule
    |
cross-check against existing rules (RULES.md + knowledge base + skill-context)
    |
present uncovered candidates to user
    |
user picks → coding rules to RULES.md, workflow rules to skill-context

Two rule destinations:

• RULES.md — coding conventions: HOW to write code (patterns, naming, null-checks, async, serialization). These reach unikit-devcontext via RULES.md → /unikit-memory → memory/.
• skill-context — workflow overrides: HOW a skill should behave (delegation strategy, commit frequency, compilation checks, parallelism). These go to .unikit/skill-context/<skill>/SKILL.md and are read by the target skill directly.

Rule migration from RULES.md to core/stack rule files is handled by /unikit-memory --migrate-rules.

Language Awareness — BLOCKING PRE-REQUISITE

BEFORE producing ANY output, silently read .unikit/system/LANGUAGE_RULES.md and apply its rules to ALL subsequent output. If the file is missing or unreadable, fall back to English. Do not produce any user-facing output until language rules are loaded. Do not announce, confirm, or mention the language setting.

Workflow

Step 1: Read Patches (Incremental)

Glob: .unikit/patches/*.md

If no patches found → report "No patches to analyze" and STOP.

Cursor file: .unikit/evolutions/patch-cursor.json

{
  "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. Do not advance cursor in this step. Cursor is updated only after successful apply in Step 7.

Overlap window (anti-miss guard):

LLMs may miss prevention points on a single pass. To reduce the risk:

6. When running in incremental mode, ALSO read the newest min(5, total) patches (tail-5), then de-duplicate.
7. Track separately:
   • "New patches" = patches with filename > last_processed_patch
   • "Overlap patches" = tail-5 patches
   • "Processed patches" = union(New, Overlap)
8. Cursor updates in Step 7 are based on "New patches" only — never advance cursor when only overlap patches were processed.

Read every patch in the processed set. For each one, extract:

• Problem categories (null-check, async, serialization, DI, lifecycle, etc.)
• Root cause patterns
• Prevention points — each independent actionable rule from the Prevention/Solution section. A single patch often contains multiple independent prevention points. Extract EACH one separately. Do NOT treat a patch as a single unit.
• Tags

Step 2: Load Context

Read the following files:

1. .unikit/DESCRIPTION.md — tech stack, project constraints
2. .unikit/RULES.md — current project rules. If doesn't exist, will be created in Step 6
3. .unikit/memory/RULES_INDEX.md — index of knowledge base rule files. If doesn't exist or empty, skip knowledge base cross-check in Step 4 (check only RULES.md)

Step 3: Build Prevention Point Registry

Build a flat list of ALL extracted prevention points:

| # | Patch | Prevention Point (specific action) | Type |
|---|-------|-------------------------------------|------|
| 1 | <patch-file> | <concrete rule to enforce> | code |
| 2 | <patch-file> | <different rule from same patch> | workflow:<skill> |
| 3 | <other-patch> | <rule> | code |

CRITICAL: A patch with 5 prevention points produces 5 rows, not 1.

Type classification:

Each prevention point must be classified:

• code — about HOW to write code: patterns, null-checks, async handling, serialization, naming, DI registration, lifecycle management. Destination: RULES.md.
• workflow:<skill-name> — about HOW a skill should behave: delegation strategy, when to compile, commit frequency, parallelism decisions, what to check before/after a step. Destination: .unikit/skill-context/<skill>/SKILL.md.

Classification heuristic:

• If the prevention point says "code MUST do X", "always use pattern Y", "never call Z" — it's code
• If the prevention point says "skill should check X before Y", "run compilation after each file", "delegate to agent instead of inline" — it's workflow:<skill>
• When in doubt, default to code — it reaches devcontext through RULES.md → memory/ and applies broadly

Step 4: Filter — Remove Already Covered

For each prevention point, cross-check against the appropriate destination:

For code type:

1. .unikit/RULES.md — is this rule already codified? If RULES.md doesn't exist, no rules are covered — all prevention points are candidates.
2. Knowledge base via RULES_INDEX.md — identify relevant rule files by topic, read them, check if covered. If RULES_INDEX.md doesn't exist or is empty — skip this check, use only RULES.md.

For workflow:<skill> type:

1. .unikit/skill-context/<skill>/SKILL.md — is this workflow override already recorded?
2. Base skill {{skills_dir}}/<skill>/SKILL.md — does the base skill already include this behavior?

A prevention point is "covered" ONLY when there is a rule that addresses the specific action described — not merely the same topic area.

Mark uncovered prevention points as candidates.

Verification: Count total, covered, uncovered. If uncovered = 0, report "all prevention points already covered" and skip to Step 7 (log only, no rules added).

Step 5: Present Candidates to User

Group candidates by type and format each uncovered prevention point:

## Rule Candidates

Based on N patches analyzed, M uncovered prevention points found:

### Coding Rules (→ RULES.md)

#### 1. [Rule Name]
- **Source:** patch-YYYY-MM-DD-HH.mm.md
- **Category:** #tag
- **Proposed rule:** "[specific, actionable instruction]"
- **Target section:** [suggested RULES.md section name]

### Workflow Rules (→ skill-context)

#### 2. [Rule Name]
- **Source:** patch-YYYY-MM-DD-HH.mm.md
- **Target skill:** [skill name]
- **Proposed rule:** "[specific, actionable instruction]"

AskUserQuestion: Apply proposed rules?

Options:

1. ✅ Apply all
2. 🔍 Let me pick — present in batches of up to 4
3. 🚫 Skip all

Based on choice:

• Apply all → run /unikit-rules for each code rule, add workflow rules to skill-context
• Let me pick → present batches of up to 4, Apply/Skip per rule
• Skip all → skip rule creation, proceed to cursor update

Do NOT add any rules until the user answers.

Step 6: Add Accepted Rules

For code type — run /unikit-rules <rule text> for each accepted rule.

The skill handles everything: cross-check against knowledge base, dedup against existing RULES.md entries, section placement, and confirmation. If a rule is already covered, it will report it — note and move on.

For workflow:<skill> type — add directly to skill-context:

1. Read .unikit/skill-context/<skill>/SKILL.md if it exists
2. If file doesn't exist — create it with the standard header:

# Project Rules for /<skill-name>

> Managed by `/unikit-evolve` and `/unikit-skills-context`. Do not edit manually.
> Last updated: YYYY-MM-DD HH:mm

## Rules

### [Rule Name]
**Source**: patch-YYYY-MM-DD-HH.mm.md
**Rule**: [Specific, actionable instruction in English]

3. If file exists — append new ### [Rule Name] entry under ## Rules, update > Last updated: line
4. Cross-check against base {{skills_dir}}/<skill>/SKILL.md — if base already covers the rule, skip and report

Step 7: Save Evolution Log & Update Cursor

7.1: Create evolution log

mkdir -p .unikit/evolutions

Create .unikit/evolutions/YYYY-MM-DD-HH.mm.md:

# Evolution: YYYY-MM-DD HH:mm

## Intelligence Summary
- Patches analyzed: X (new: N, overlap: M)
- Prevention points extracted: X
- Already covered: X
- Rules added: X

## Rules Added

- [rule text] <- Source: [patch filename]
  **Section:** [RULES.md section name]

## Patterns Identified
- [pattern]: [frequency] occurrences

7.2: Update cursor

1. If no new patches were processed → keep cursor unchanged.
2. If new patches were processed:
   • If rules were added → advance cursor to newest "New patch" filename.
   • If no rules were added (user skipped all) → advance cursor. Patches have been analyzed; re-reading them wastes context.
3. If execution fails before changes finalized → do not advance cursor.

Context Cleanup

After completing evolution, suggest /clear or /compact — context is heavy after patch analysis and skill processing.

Rules

1. Traceable — every proposed rule must link to a specific patch
2. Minimal — add rules to RULES.md, don't rewrite the knowledge base
3. Reversible — user approves before any changes are applied
4. Cumulative — each evolution builds on previous ones
5. No hallucination — only propose rules backed by evidence from patches
6. English only — all rules in RULES.md are in English
7. No generic advice — "write clean code" is not a rule; only specific, actionable instructions
8. One prevention point = one rule — don't merge multiple independent rules into a single vague summary
9. Preserve concrete formats — if a patch specifies exact format/syntax/template, the rule must include it verbatim
10. Ownership boundary — this command owns .unikit/evolutions/*.md and .unikit/evolutions/patch-cursor.json; may append coding rules to .unikit/RULES.md (via /unikit-rules); may write workflow rules to .unikit/skill-context/<skill>/SKILL.md; treats everything else as read-only. Rule migration from RULES.md to memory/ is handled by /unikit-memory --migrate-rules

Example

/unikit-evolve

> Analyzed 5 patches (3 new, 2 overlap)
> Extracted 8 prevention points, 6 already covered, ⚠️ 2 uncovered
>
> Rule candidates:
> 1. "Constructor null checks MUST be symmetric..." <- patch-2026-03-10-12.00.md
> 2. "Event subscriptions before fallible operations..." <- patch-2026-03-10-12.00.md
>
> Apply all / Let me pick / Skip all?