Evolve Skill

Purpose

Capture positive evolutions from completed epics - the new components, fields, patterns, and capabilities that were added during implementation. This complements /retro (which captures failures) by documenting what was successfully created.

Key Principle: Only propose updates for truly new additions. If an epic used existing patterns and components, no updates are needed.

When to Use

• Automatically invoked at /run-tasks Step 10 (epic completion)
• User invokes /evolve <epic-id> directly
• After any epic that added new UI components, data fields, or patterns

---

Entry Points

Invocation	Description
/evolve <epic-id>	Analyze a specific completed epic
/evolve <epic-id> --dry-run	Preview without modifying files
/run-tasks Step 10	Automatically called before epic close

---

Process

Step 1: Gather Epic Context

Get the epic's git history to understand what changed:

# Get epic branch or commit range
EPIC_ID="$1"

# Find commits associated with this epic (from commit messages)
COMMITS=$(git log --oneline --grep="$EPIC_ID" --format="%H")

# Or if on epic branch
git log main..HEAD --oneline

Get the combined diff of all changes:

# Files changed in epic
git diff main...HEAD --name-only

# Full diff for analysis
git diff main...HEAD --unified=3

Step 2: Load Existing Registries

Read current documented patterns to compare against:

# Design system registries
COMPONENTS_REGISTRY=".design/Components.md"
FIELDS_REGISTRY=".design/Fields.md"
PATTERNS_REGISTRY=".design/Patterns.md"

# Extract known components (look for ## headers or component names)
KNOWN_COMPONENTS=$(grep -E "^### " "$COMPONENTS_REGISTRY" | sed 's/### //')

# Extract known fields
KNOWN_FIELDS=$(grep -E "^\| \`" "$FIELDS_REGISTRY" | sed 's/| `//' | cut -d'`' -f1)

# Extract known patterns
KNOWN_PATTERNS=$(grep -E "^### " "$PATTERNS_REGISTRY" | sed 's/### //')

Step 3: Detect New Additions

Analyze the diff for new exports and definitions:

3a. New React Components

# Find new component exports in renderer
git diff main...HEAD -- "src/renderer/**/*.tsx" | \
  grep -E "^\\+export (const|function) [A-Z]" | \
  sed 's/+export //' | \
  awk '{print $2}' | \
  cut -d'(' -f1

Look for:

• New files in src/renderer/components/
• New export const ComponentName or export function ComponentName
• New entries in component index files

3b. New Type Definitions / Fields

# Find new interface/type definitions
git diff main...HEAD -- "src/shared/types/**/*.ts" | \
  grep -E "^\\+export (interface|type) " | \
  sed 's/+export //'

# Find new enum values
git diff main...HEAD -- "src/shared/types/**/*.ts" | \
  grep -E "^\\+  [A-Z_]+ = "

Look for:

• New fields in existing interfaces
• New interfaces/types
• New enum values
• New Zod schemas

3c. New Patterns

Analyze code structure for repeated patterns:

• New hook patterns (useXxx)
• New utility functions
• New service patterns
• New IPC handlers

# Find new hooks
git diff main...HEAD -- "src/renderer/**/*.ts" | \
  grep -E "^\\+export function use[A-Z]"

# Find new utilities
git diff main...HEAD -- "src/*/lib/**/*.ts" | \
  grep -E "^\\+export (const|function)"

Step 4: Filter Against Known

Remove items already in registries:

function filterNew(detected: string[], known: string[]): string[] {
  return detected.filter(item =>
    !known.some(k => k.toLowerCase() === item.toLowerCase())
  );
}

const newComponents = filterNew(detectedComponents, knownComponents);
const newFields = filterNew(detectedFields, knownFields);
const newPatterns = filterNew(detectedPatterns, knownPatterns);

Step 5: Generate Evolution Report

If new items found, present for approval:

## Evolution Report: <epic-id>

### Summary
- **Epic**: <title>
- **New Components**: <count>
- **New Fields/Types**: <count>
- **New Patterns**: <count>

---

### New Components

#### TaskStatusBadge
- **File**: `src/renderer/components/common/TaskStatusBadge.tsx`
- **Props**: `{ status: TaskStatus, size?: 'sm' | 'md' }`
- **Usage**: Display task status with color coding

**Suggested addition to `.design/Components.md`:**
```markdown
### TaskStatusBadge

Status indicator for beads tasks.

**Usage:**
\`\`\`tsx
<TaskStatusBadge status="in_progress" size="sm" />
\`\`\`

**Variants:** Uses status colors from Colors.md

---

New Fields/Types

TaskPriority (enum)

• File: src/shared/types/beads.ts
• Values: P0 | P1 | P2 | P3 | P4

Suggested addition to .design/Fields.md:

Field	Type	Values	Description
priority	TaskPriority	P0-P4	Task urgency (P0=critical)

---

New Patterns

useBeadsQuery Hook

• File: src/renderer/lib/hooks/useBeadsQuery.ts
• Purpose: Cached data fetching for beads with auto-refresh

Suggested addition to .design/Patterns.md:

### useBeadsQuery

Custom hook for fetching beads data with caching.

\`\`\`tsx
const { data, loading, error, refetch } = useBeadsQuery('bd list --json');
\`\`\`

---

Approval Required

Apply these evolution updates?

1. Apply all updates
2. Apply selectively (I'll specify)
3. Skip all (no changes)

### Step 6: Apply Approved Updates

For each approved item, append to the appropriate registry:

#### Components Registry
```bash
cat >> .design/Components.md << 'EOF'

---

### <ComponentName>

<description>

**Usage:**
```tsx
<example code>

Added: Epic , EOF

#### Fields Registry
```bash
# Append to table in .design/Fields.md
# Insert before the closing of the table

Patterns Registry

cat >> .design/Patterns.md << 'EOF'

---

### <PatternName>

<description>

**Example:**
```tsx
<example code>

Added: Epic EOF

### Step 7: Update Agent Knowledge (Optional)

If new capabilities were discovered, offer to update agent prompts:

```markdown
### Agent Knowledge Updates

The following agents may benefit from knowing about new patterns:

#### typescript-agent.md
**Suggested Addition:**
```diff
+ ### TaskStatusBadge
+ Use TaskStatusBadge from components/common for status display.
+ Don't create custom status badges.

Apply agent updates?

1. Yes, update agent prompts
2. No, skip agent updates

### Step 8: Archive Evolution

Create evolution record:

```bash
mkdir -p .claude/evolutions

cat > .claude/evolutions/<epic-id>.md << 'EOF'
# Evolution: <epic-id>

**Date**: <date>
**Epic**: <title>

## Additions

### Components
- TaskStatusBadge

### Fields
- priority (TaskPriority enum)

### Patterns
- useBeadsQuery hook

## Registry Updates
- .design/Components.md: +1 component
- .design/Fields.md: +1 field
- .design/Patterns.md: +1 pattern
EOF

---

Handling Edge Cases

No New Additions

When epic used only existing patterns:

## Evolution Report: <epic-id>

**No new additions detected.**

This epic successfully reused existing:
- Components: Button, Card, Badge
- Fields: status, created_at, user_id
- Patterns: useBeadsQuery, IPC handler

No registry updates needed.

Dry Run Mode

When --dry-run specified:

---

**DRY RUN: No files modified**

To apply these updates, run:
`/evolve <epic-id>` (without --dry-run)

Conflicting Names

If detected item name conflicts with existing (but different implementation):

**Warning: Name Conflict**

Detected `StatusBadge` but `.design/Components.md` already has a StatusBadge.

Options:
1. This is the same component (skip)
2. This is different - rename to `TaskStatusBadge`
3. This replaces the old one (update existing entry)

---

Registry File Formats

.design/Components.md

# Component Patterns

> UI component registry for the project

---

## Core Components

### Button
<existing documentation>

### Card
<existing documentation>

---

## Feature Components

### TaskStatusBadge
**Added**: Epic bd-x1y2, 2024-01-15

Status indicator for beads tasks.
...

.design/Fields.md

# Field Registry

> Data field definitions, types, and allowed values

---

## Core Fields

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| `id` | `string` | UUID | Unique identifier |
| `created_at` | `datetime` | ISO 8601 | Creation timestamp |
| `status` | `enum` | open, closed, blocked | Current state |

---

## Feature Fields

| Field | Type | Values | Description | Added |
|-------|------|--------|-------------|-------|
| `priority` | `TaskPriority` | P0-P4 | Task urgency | bd-x1y2 |

.design/Patterns.md

# Pattern Library

> Reusable code patterns and conventions

---

## Data Fetching

### useBeadsQuery
**Added**: Epic bd-x1y2

Custom hook for beads data with caching.

```tsx
const { data, loading, refetch } = useBeadsQuery('bd list --json');

---

State Management

Zustand Store Pattern

...

---

## Integration with /run-tasks

At Step 10 (epic completion), before closing:

```markdown
All tasks complete for "<epic-title>".

**Checking for evolutions...**

Found 2 new additions:
- Component: TaskStatusBadge
- Pattern: useBeadsQuery

Options:
1. Close epic (skip evolution capture)
2. Review and capture evolutions (recommended)
3. Run retrospective + evolution capture

If user selects 2 or 3, invoke /evolve <epic-id>.

---

Integration with /discover

The discovery skill should reference registries:

## Step 3: Establish Patterns

Before designing new components, check existing registries:

**Available Components** (from .design/Components.md):
- Button, Card, Badge, Input, Select, Dialog...

**Available Fields** (from .design/Fields.md):
- id, created_at, updated_at, status, priority...

**Available Patterns** (from .design/Patterns.md):
- useBeadsQuery, IPC handler, Zustand store...

Spec should reference existing patterns where applicable.

---

Token Budget

Target: ~1500 tokens for evolution check

Component	Budget
Git diff analysis	~300
Registry comparison	~200
Generate report	~500
Apply updates	~300
Archive	~200

Skip entirely if no new additions detected (~100 tokens).

---

Configuration

# project.yaml
workflow:
  evolution:
    enabled: true
    auto_prompt: true           # Prompt at epic close
    registries:
      components: ".design/Components.md"
      fields: ".design/Fields.md"
      patterns: ".design/Patterns.md"
    detect:
      components: true
      fields: true
      patterns: true
      agent_capabilities: false  # Optional

---

Files Modified

This skill may create or modify:

Path	Action	Approval
.design/Components.md	Append	Required
.design/Fields.md	Append	Required
.design/Patterns.md	Append	Required
.claude/agents/*.md	Append	Required
.claude/evolutions/<epic-id>.md	Create	Automatic

---

Example: No Changes Needed

User: /evolve bd-abc1

Claude:

## Evolution Report: bd-abc1

Analyzing epic "Add user profile page"...

**Detected patterns used:**
- Components: Card, Button, Input, Avatar
- Fields: user_id, email, created_at
- Patterns: useBeadsQuery, Zustand store

**Comparison with registries:**
- All components already documented
- All fields already in registry
- All patterns already captured

**No new additions detected.**

This epic successfully followed existing patterns. No registry updates needed.

---

Example: New Additions Found

User: /evolve bd-xyz9

Claude:

## Evolution Report: bd-xyz9

Analyzing epic "Task dependency visualization"...

### New Additions Detected

#### Components (2 new)
1. **DependencyGraph** - `src/renderer/components/board/DependencyGraph.tsx`
   - Interactive graph showing task dependencies
   - Uses react-flow for rendering

2. **DependencyEdge** - `src/renderer/components/board/DependencyEdge.tsx`
   - Custom edge component for dependency arrows

#### Fields (1 new)
1. **blocked_by** - `string[]` - Array of task IDs that block this task

#### Patterns (1 new)
1. **useGraphLayout** - Custom hook for auto-layout of dependency graphs

---

**Apply these updates?**
1. Apply all (4 additions)
2. Apply selectively
3. Skip all

User: 1

Claude:

Applying evolution updates...

- Updated: .design/Components.md (+2 components)
- Updated: .design/Fields.md (+1 field)
- Updated: .design/Patterns.md (+1 pattern)
- Created: .claude/evolutions/bd-xyz9.md

Evolution capture complete.