---
name: forge-evolve
description: "Review lessons learned from accumulated gotchas and improve the forge skill system itself. Run after completing a feature or project. Operates on the forge harness — not on user project code."
---

# /forge-evolve — Self-Improvement Review

You are reviewing lessons learned and improving the forge skill system itself. This is how the system gets smarter over time. Run this after completing a feature, project, or periodically to process accumulated gotchas.

## Execution Protocol

- **"REQUIRED SUB-SKILL"** means you MUST load the named skill before acting. Do NOT substitute your own judgment for the skill's process.

## Step 1: Gather All Gotchas

Read all gotcha files from both locations:
- **Project gotchas**: `aiwiki/gotchas/*.md`
- **Global gotchas**: `~/.claude/gotchas/*.md`

For each gotcha, extract:
- The lesson learned
- The affected skills
- The date discovered
- Whether it has been addressed already

## Step 2: Identify Patterns

Analyze the collected gotchas for patterns:

1. **Repeated gotchas** — The same type of mistake happening multiple times
2. **Skill gaps** — Gotchas that no current skill would have caught
3. **Gate failures** — Issues that slipped through quality gates
4. **Gate successes** — Issues that gates DID catch (reinforce these)
5. **Process friction** — Steps that consistently cause slowdowns or confusion

Present findings as a summary table:
```
Pattern                          | Occurrences | Affected Skills      | Severity
---------------------------------|-------------|----------------------|---------
Missing error handling in APIs   | 4           | build-tdd, code-review | High
Tests pass but behavior wrong    | 2           | quality-test-plan     | Medium
```

## Step 3: Check Quality Gate Effectiveness

For each quality gate in the system:
1. How many issues did it catch? (good)
2. How many issues slipped through? (needs improvement)
3. Is the gate too strict (blocking unnecessarily)?
4. Is the gate too loose (letting problems through)?

## Step 4: Propose Changes

Based on the patterns, propose specific changes:

### Skill Changes
- Modifications to existing skill prompts
- New steps to add to existing skills
- New skills to create (if a gap was identified)

### Rule Changes
- New rules to add
- Modifications to existing rules
- Rules to relax (if too strict)

### Gate Changes
- Gates to tighten
- Gates to add
- Gates to relax (with justification)

Present each proposed change with:
- **What**: The specific change
- **Why**: Which gotcha pattern it addresses
- **Risk**: What could go wrong if we make this change

## Step 5: Validate Changes

REQUIRED SUB-SKILL: Use **support-skill-validator** before applying ANY changes.
Do NOT apply changes without validating first — the validator catches contradictions you will miss.

If contradictions are found, resolve them before proceeding.

## Step 6: User Approval

Present all proposed changes to the user. Changes are applied ONLY with explicit approval. The user may:
- Approve all changes
- Approve some changes and reject others
- Request modifications to proposed changes
- Defer changes for later

## Step 7: Apply Changes

For each approved change:
1. Make the modification to the relevant skill, rule, or gate file
2. REQUIRED SUB-SKILL: Re-run **support-skill-validator** to verify consistency after the change
3. Record the change in `aiwiki/decisions/{nnnn}-{slug}.md` — use the next available ADR number and a slug describing the change (e.g., `0042-tighten-build-tdd-mock-check.md`). Per the decision schema, capture: status, context (which gotcha pattern this addresses), the change itself, and what could go wrong.

## Step 8: Promotion Check

Check for gotchas that have repeated 3 or more times. These are candidates for promotion to rules:

```
PROMOTION CANDIDATES
--------------------
Gotcha: "Always check for null responses from external APIs"
  Occurrences: 4
  Currently in: support-gotcha (project level)
  Proposed promotion: references/common/coding-standards.md

  Promote to rule? [yes/no]
```

For each promotion candidate:
- Draft the rule text
- Identify where in the rules it should live
- Present to the user for approval
- If approved, add to the appropriate rules file and archive the gotcha