improve

What this skill does

# Improve

Autonomous skill improvement loop inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch). You modify a skill, evaluate whether it got better, keep or discard, repeat.

**Your originals are always safe.** The loop works on a copy. Nothing changes until you say so.

---

## Setup

When the user says "improve [skill name]":

1. **Locate the skill.** Read `skills/<name>/SKILL.md`. If it doesn't exist, ask the user which skill they mean.

2. **Back up the original.** Copy the full `skills/<name>/` directory to `eval/experiments/<name>/`. Create `eval/experiments/` if it doesn't exist.
   ```
   mkdir -p eval/experiments/<name>
   cp skills/<name>/SKILL.md eval/experiments/<name>/SKILL.md
   cp skills/<name>/*.md eval/experiments/<name>/  (if supporting files exist)
   ```

3. **Read the design philosophy.** Read `CLAUDE.md` to ground yourself in the plugin's standards. The rubric below is derived from these.

4. **Read neighbor skills.** Identify skills with overlapping scope (check the Related Skills section, check skills in the same category from CLAUDE.md). Read their descriptions — you need to know the boundaries.

5. **Initialize the log.** Create `eval/results.tsv` (or append if it exists from a previous run):
   ```
   experiment	skill	tier	dimension	score_before	score_after	status	change_description
   ```

6. **Run the baseline diagnosis.** Score the original against the rubric (see below). Log it as experiment 0.

7. **Show scores and ask for focus.** Print the rubric scores in a compact tiered table:
   ```
   Tier 1 (Critical):  trigger-precision=1  trigger-phrases=1  checklists=2  tell-ai-prompts=2  → 6/12
   Tier 2 (Important): boundary=1  tool-specific=N/A  founder-pov=2  mistakes=1             → 4/9
   Tier 3 (Polish):    conciseness=✓  disclosure=✗  scannable=✓  cross-refs=✗
   Total: 10/21
   ```
   (Example shows a knowledge skill where tool-specific is N/A. For implementation skills, all 8 dimensions apply and max is /24.)
   Then ask:
   > "I'll focus on the lowest-scoring dimensions, Tier 1 first. Want me to auto-prioritize (default) or focus on specific areas?"

   If the user says "go," "auto," or anything non-specific → auto-prioritize (Tier 1 first, then Tier 2).
   If the user names specific dimensions → focus the loop on those, skip others.

---

## Rubric: Diagnosing Weaknesses

Score each dimension 0-3 (0=missing, 1=weak, 2=adequate, 3=strong). Dimensions are tiered by impact.

### Tier 1 — Critical (scored 0-3, experimented first)

These determine whether the skill fires and delivers value. All must reach ≥2 before moving to Tier 2.

- **Trigger precision:** Does the description activate for the right prompts and NOT for neighbor skills' prompts?
- **Trigger phrases:** Does it include phrases users actually say (natural language, not jargon)?
- **Actionable checklists:** Does it have concrete workflows with checkboxes?
- **"Tell AI:" prompts:** Does it include copy-paste prompts founders can use with any AI tool?

### Tier 2 — Important (scored 0-3, experimented after Tier 1 ≥2)

These improve quality but only matter if the skill fires correctly.

- **Boundary clarity:** Does it explicitly state what this skill is NOT for and where to go instead?
- **Tool-specific guidance (conditional):** Does it differentiate advice by tool (Claude Code vs Lovable vs Replit)? **Mark N/A** for knowledge/decision skills where the same guidance applies regardless of tool — e.g., compliance, hiring, legal, pricing, finances, market-research, customer-research, validate, analytics, retention. If the skill's advice changes depending on which tool runs it, score it. If not, skip it and reduce the denominator.
- **Founder perspective:** Is it written for a non-technical founder, not a developer?
- **Common mistakes:** Does it cover what founders typically get wrong?

### Tier 3 — Polish (binary checklist, batch pass at end)

Not scored individually. Handled as a single cleanup pass after the main loop converges.

- [ ] **Conciseness:** Avoids explaining concepts Claude already knows?
- [ ] **Progressive disclosure:** SKILL.md first, supporting files for depth?
- [ ] **Scannable:** Headers, tables, short paragraphs — not walls of text?
- [ ] **Cross-references:** Links to related skills where relevant?

**Loop score: Tier 1 + Tier 2 = applicable dimensions × 3pts.** Max is 24 when all 8 dimensions apply, 21 when tool-specific guidance is N/A.

Tier 3 is not part of the loop score. It's a yes/no sweep after convergence.

---

## The Loop

```
REPEAT:
  1. PICK the lowest-scoring dimension, respecting tier order:
     - Tier 1 dimensions below 2 → always first
     - Tier 2 dimensions → only after all Tier 1 ≥ 2
     - N/A dimensions → skip entirely, never experiment on them
     - Tier 3 → never (handled in polish pass)
     - User-specified focus areas override this order

  2. MAKE ONE CHANGE to eval/experiments/<name>/SKILL.md
     - Target the specific weakness identified
     - One focused change per iteration, not a rewrite

  3. EVALUATE via A/B comparison (do reasoning internally, log to experiment-log.md):

     a. Generate 3 representative user prompts for this skill
        (realistic things a non-technical founder would say)

     b. For each prompt, reason through what guidance the ORIGINAL
        skill would produce vs what the MODIFIED version would produce

     c. Judge: "Which version gives a non-technical founder better,
        more actionable guidance?" Score: Original wins / Modified wins / Tie

     d. Majority wins across the 3 prompts

     Write the full A/B reasoning to eval/experiments/<name>/experiment-log.md.
     Do NOT print it to the terminal. See Output Rules.

  4. DECIDE
     - Modified wins majority → KEEP the change
     - Original wins or tie → DISCARD (revert experiment file to previous version)

  5. LOG to eval/results.tsv:
     experiment#  skill  tier  dimension_targeted  score_before  score_after  status  change_description

  6. RE-SCORE the full rubric after every KEEP (do this internally, don't print)

  7. PRINT one line per experiment (see Output Rules)

  8. CHECK stopping condition
```

### Stopping Condition

Stop the main loop when ANY of:
- **Converged:** 3 consecutive experiments with no improvement (all discarded)
- **Experiment cap reached:** default 8 experiments. User can override: "improve seo with 12 experiments max"
- **All Tier 1+2 dimensions scoring 3:** nothing left to improve
- **User interrupts**

### Polish Pass

After the main loop stops, run **one** final experiment targeting all Tier 3 items at once:
- Check each Tier 3 item (conciseness, progressive disclosure, scannable, cross-references)
- Make a single batch edit addressing any that are missing or weak
- Evaluate the batch change via the same A/B process
- KEEP or DISCARD as a unit — not individually
- Show as one line in output: `P  polish  KEEP|DISCARD  score→score  summary`

The polish pass does not change the /24 loop score. It's shown as a separate line at the end.

---

## Evaluation Rules

Be honest. You are both the improver and the judge — this only works if you don't fool yourself.

- **Generate diverse prompts.** Don't write prompts that favor your change. Write prompts a real founder would type.
- **Judge from the founder's perspective.** Not "which is more technically correct" but "which helps a non-technical founder take action."
- **Preserve voice.** The original author's style and personality should survive. You're improving, not rewriting.
- **Respect neighbor boundaries.** If a change makes this skill bleed into another skill's territory, that's a regression even if the content is "better."
- **One change at a time.** If you bundle 3 changes and it wins, you don't know which change helped. Isolate variables.

---

## Winners Report

When the loop stops, generate `eval/winners-report.md`:

```markdown
# Skill Improvement Results — [skill name] — [date]

## Summary
[skill