Skip to content

evolve-skill

<!– story: e23s03 –>

<!– story: e09s01 –> <!– story: e09s05 –>

HARD GATE — No skill change ships without benchmark score ≥ pre-change baseline. Learning is measured and versioned — never implicit.

  1. Regression gate — Run bash scripts/run-verification-gates.sh to catch mechanical regressions (compliance, sync pipeline, size budget) before spending time on benchmark evals. If golden suite fails, fix regressions first — they are pre-requisites for any capability improvement.

  2. Establish baseline — Run run-benchmark &lt;skill> --baseline. If no definition exists at specs/benchmarks/&lt;skill>.yaml, create one following specs/benchmarks/SCHEMA.md first. Save report path in state.yaml. If specs/benchmarks/reports/BASELINE-&lt;skill>.yaml already exists, skip this step.

  3. Identify gap — Read the baseline report (specs/benchmarks/reports/BASELINE-&lt;skill>.yaml). Find scenarios with result: FAIL or low pass_at_k. This is the measurable gap.

  4. plan-work — Write a minimal change proposal targeting the failing scenarios. Include verify commands.

  5. Edit via craft-skill / direct SKILL.md edit; run bash scripts/sync-skills.sh.

  6. Re-run benchmark — run-benchmark &lt;skill>. Compare new pass_at_k against baseline.

    • IMPROVED or STABLE → advance to step 6.
    • REGRESSION (new pass_at_k &lt; baseline) → revert the change and loop back to step 3.
  7. Record decision — Write specs/adr/NNNN-evolve-&lt;skill>.md with before/after pass_at_k scores. Update session-state.

→ verify: test -d specs/benchmarks && test -f skills/run-benchmark/SKILL.md

See REFERENCE.md for ADR template.

<!– story: e31s07 –>