makepad-evolution

What this skill does

# Makepad Skills Evolution

This skill enables makepad-skills to self-improve continuously during development.

---

## Automatic vs Manual Triggers

**IMPORTANT FOR CLAUDE**: Some mechanisms should trigger automatically without user request.

### Automatic (Claude should do proactively)

| Mechanism | When to Auto-Trigger |
|-----------|---------------------|
| **Version Adaptation** | At session start, read Cargo.toml and detect Makepad branch |
| **Personalization** | On first code generation, scan 2-3 existing widgets for style |
| **Self-Correction** | Immediately when skill-suggested code fails |
| **Usage Feedback** | After each pattern usage (success or failure) |

### Semi-Automatic (Claude proposes, user confirms)

| Mechanism | When to Propose |
|-----------|-----------------|
| **Self-Evolution** | After solving a non-trivial problem worth documenting |

### Manual (User must request)

| Mechanism | Trigger Phrase |
|-----------|---------------|
| **Self-Validation** | "validate makepad-skills" |
| **Health Report** | "show pattern health report" |

---

## Session Start Checklist (Auto-Execute)

When starting a Makepad development session, Claude should automatically:

```
1. [ ] Detect Makepad version from Cargo.toml
       → Set internal context: "Using Makepad {branch}"

2. [ ] Scan project style (if not done before)
       → Note naming conventions, module structure

3. [ ] Apply version-specific and personalized suggestions
       → All subsequent advice adapted automatically
```

**Claude: Do these silently. Don't announce unless relevant to user's question.**

---

## When to Evolve

Trigger skill evolution when any of these occur during development:

| Trigger | Target Skill | Priority |
|---------|--------------|----------|
| New widget pattern discovered | makepad-patterns | High |
| Shader technique learned | makepad-shaders | High |
| Compilation error solved | makepad-troubleshooting | High |
| Layout solution found | makepad-adaptive-layout | Medium |
| Build/packaging issue resolved | makepad-packaging | Medium |
| New project structure insight | makepad-init | Low |
| Core concept clarified | makepad-fundamentals | Low |

## Evolution Process

### Step 1: Identify Knowledge Worth Capturing

Ask yourself:
- Is this a reusable pattern? (not project-specific)
- Did it take significant effort to figure out?
- Would it help other Makepad developers?
- Is it not already documented in makepad-skills?

### Step 2: Classify the Knowledge

```
Widget/Component Pattern     → makepad-patterns/SKILL.md
Shader/Visual Effect         → makepad-shaders/SKILL.md
Error/Debug Solution         → makepad-troubleshooting/SKILL.md
Layout/Responsive Design     → makepad-adaptive-layout/SKILL.md
Build/Deploy Issue           → makepad-packaging/SKILL.md
Project Structure            → makepad-init/SKILL.md
Core Concept/API             → makepad-fundamentals/SKILL.md
```

### Step 3: Format the Contribution

**For Patterns (makepad-patterns)**:
```markdown
## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

### live_design!
\```rust
live_design! {
    // DSL code
}
\```

### Rust Implementation
\```rust
// Rust code
\```

### Usage
\```rust
// How to use
\```
```

**For Troubleshooting (makepad-troubleshooting)**:
```markdown
### [Error Type/Message]

**Symptom**: What the developer sees

**Cause**: Why this happens

**Solution**:
\```rust
// Fixed code
\```
```

**For Shaders (makepad-shaders)**:
```markdown
### [Effect Name]

\```rust
draw_bg: {
    // shader code with comments
    fn pixel(self) -> vec4 {
        // implementation
    }
}
\```
```

### Step 4: Update the Skill File

1. Read the target SKILL.md file
2. Find the appropriate section
3. Add new content following existing format
4. Ensure no duplicate content

### Step 5: Mark Evolution (NOT Version)

**Important**: Do NOT update version number locally. Add an evolution marker instead:

```markdown
<!-- Evolution: 2024-01-15 | source: my-app | author: @zhangsan -->
```

Place this comment above the new content you added.

### Step 6: Submit via Git

```bash
# Create branch for your contribution
git checkout -b evolution/add-loading-pattern

# Commit your changes
git add makepad-patterns/SKILL.md
git commit -m "evolution: add loading state pattern from my-app"

# Push and create PR
git push origin evolution/add-loading-pattern
```

---

## Multi-Developer Collaboration

### The Problem

```
Developer A: evolves locally → version 1.4.1
Developer B: evolves locally → version 1.4.1  ← Conflict!
```

### The Solution: Content-First Model

```
┌─────────────────────────────────────────────────────────┐
│  Local Development (Each Developer)                     │
│  - Add content only                                     │
│  - Add evolution markers (date, source, author)         │
│  - Do NOT change version number                         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Git PR / Merge                                         │
│  - Content reviewed and merged                          │
│  - Conflicts resolved at content level                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Release (Maintainer / CI)                              │
│  - Bump version based on accumulated changes            │
│  - Tag release                                          │
│  - Publish                                              │
└─────────────────────────────────────────────────────────┘
```

### Evolution Marker Format

Each contribution should include a marker:

```markdown
<!-- Evolution: YYYY-MM-DD | source: project-name | author: @github-handle -->
```

Example in makepad-patterns/SKILL.md:

```markdown
## Pattern 15: Loading State Button

<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->

A button that shows loading spinner when processing...
```

### Git Workflow

```bash
# 1. Sync with upstream before evolving
git fetch upstream
git rebase upstream/main

# 2. Create evolution branch
git checkout -b evolution/descriptive-name

# 3. Make your changes (content only, no version bump)
# ... edit SKILL.md files ...

# 4. Commit with conventional prefix
git commit -m "evolution(patterns): add loading state button"
git commit -m "evolution(troubleshooting): fix for timer not firing"
git commit -m "evolution(shaders): add glassmorphism effect"

# 5. Push and create PR
git push origin evolution/descriptive-name
gh pr create --title "evolution: add loading patterns from moly"
```

### Handling Content Conflicts

When multiple developers add to the same section:

```markdown
<<<<<<< HEAD
## Pattern 15: Loading Button
<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->
=======
## Pattern 15: Expandable Card
<!-- Evolution: 2024-01-15 | source: robrix | author: @lisi -->
>>>>>>> evolution/add-card-pattern
```

Resolution: **Renumber and keep both**

```markdown
## Pattern 15: Loading Button
<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->
...

## Pattern 16: Expandable Card
<!-- Evolution: 2024-01-15 | source: robrix | author: @lisi -->
...
```

### Version Bumping (Maintainer Only)

At release time, maintainer reviews accumulated changes:

```bash
# Check what's new since last release
git log v1.4.0..HEAD --oneline

# Determine version bump
# - Only troubleshooting fixes → patch (1.4.1)
# - New patterns/shaders → minor (1.5.0)
# - New skill files → major (2.0.0)

# Update version in plugin.json
# Tag and release
git tag v1.5.0
git push --tags
```

### CI Automation (Optional)

`.github/workflows/version.yml`:

```yaml
name: Auto Version on Release
on:
  push:
    branches: [main]
    paths:
      - '*/SKILL.md'

jobs:
  version:
    runs-on: ubuntu-latest