/skill-evolution

name: skill-evolution
description: Evolve the skills that do the work — capture lessons at phase boundaries into .john/lessons/, draft project-local skill overrides when guidance fights reality, and train workerLLM skills with a scored, gated edit loop when the domain has a scorer. Use this skill at every phase boundary ("what did this phase teach us?"), whenever worker output quality disappoints, when the user says "improve/optimize/train this skill or prompt", when a template ships a scorer or eval set, or when you notice a skill's guidance repeatedly mismatching the corpus. Evolution without this skill's discipline (bounded edits, held-out gates, the trainable-surface test) makes skills worse, not better — documented failure modes, not caution.
metadata:
  triggers:
    - improve the skill
    - optimize the prompt
    - train the worker skill
    - skill evolution
    - lessons learned
    - what did we learn
    - record a lesson
    - the skill is wrong
    - evolve the template
    - eval set
    - scorer

skill-evolution

A skill document is not finished at authoring time — it should *earn* its content from run evidence. John structures that earning as **evolution rings**: the closer a text is to the work, the faster and more automated its evolution may be; the more meta it is, the slower and more human-gated.

• **Ring 0 — this project** (you, this skill): lessons, project-local override drafts, and the worker-skill training loop. Blast radius: this project only.
• **Ring 1 — the template**: the template's owner evolves it from accumulated run reports across projects. You *feed* Ring 1 (lessons, reports); you never edit the template itself.
• **Ring 2 — John core**: the maintainers evolve the teaching skills from cross-domain evidence. You feed it the same way. The top gate is human, permanently.

Your influence travels **upward as evidence, never as edits**. This skill teaches Ring 0: what to capture, what you may change, how to change it safely, and how to train the one class of skill where a real optimization loop applies.

The boundary: trainable vs teaching

Before touching any skill text, classify it:

> **Could a different domain's template author have legitimately written this passage differently?** Then it's *trainable* — domain-specific "what to do", fair game for Ring-0 drafts and the training loop. **Is it true in every domain?** Then it's *teaching* — core methodology, hands off; if it's wrong, that's a `core`-scope lesson, not an edit.

In practice the trainable surface is what the template changed relative to vanilla John (its overrides, additive skills, plan skeleton, agents, worker prompts — enumerated in the applied plugin's `.applied-metadata.json`) plus anything project-local you created. When in doubt: **log a lesson, don't edit.**

A second classification, for deciding where an improvement *lands* (it shapes your lesson's `scope_guess`, and Ring 1 uses it when folding lessons in):

• **Core assets of a template** — its SKILL.md bodies, reusable scripts, the plan skeleton: things every project of this type needs. A lesson that generalizes across corpora of the domain points here.
• **Perimeter assets** — `references/` depth, worked examples, edge-case notes: useful, loaded on demand. A lesson that's real but conditional points here.
• **Ad-hoc** — judgment calls each project should make fresh. Not every lesson deserves to be institutionalized; over-folding kills the wide tunnel. It's legitimate for a lesson's destiny to be "stay project-local."

The lessons ledger

`<project>/.john/lessons/` — one small JSON file per lesson, append-only, never edited or deleted. Format and examples: `references/lessons-ledger.md`. The non-negotiables:

1. **Conditional form.** A lesson states *when it applies*, not just what to do: `condition` + `lesson`. "Always chunk smaller" is over-generalization from one corpus; "when tables span chunk boundaries, chunk by row group" travels. 2. **Evidence pointer.** Every lesson cites what it was learned from (event files, checkpoint, gate verdict, a PLAN.md Log anchor). Un-evidenced lessons get rejected at promotion — write the pointer now, while you know it. 3. **Scope guess.** `project` / `template` / `core` — your honest estimate of where this lesson belongs. This is the promotion hint Rings 1–2 aggregate on.

**When to distill: at phase boundaries** — the same seam where [[plan-md-evolution]] runs and the user signs off. Ask: what fought reality this phase? What would I tell the next session building this kind of app? Two or three honest lessons beat ten plausible ones — a ledger full of unvalidated truisms is evolution theater, and reviewers learn to ignore it.

Raw corpus text is allowed *inside* the ledger (it's project-local). It must be scrubbed and generalized before anything leaves the project — see the care list. The export vehicle is the **run report** (`/john:report`): scorecard + manifest + outcome + the few lessons worth promoting, assembled per `references/run-report-format.md` and shared manually by the user (typically to the template's owner, as evolution evidence).

Project-local skill overrides

When a skill's guidance actively fights this project (not just "could be better" — *fights*: you keep working around it), you may evolve it **for this project**:

1. **Draft** the override in the active provider's project skill tree as a *bounded delta* from the original. For a dual-provider project, publish the same bytes under `.claude/skills/<name>/` and `.agents/skills/<name>/`. Change only the passages that fight, and note the diff and evidence in the draft's header comment. 2. **Apply at the next phase boundary, with the user's sign-off.** The draft rides the same seam as plan evolution — present it alongside the phase summary. 3. **Endurance-mode exception**: if the session is in endurance mode, the user is away, and the blockage is real (you cannot proceed sensibly without the change), you may ap