magpie-optimize-skill

<!-- SPDX-License-Identifier: Apache-2.0 https://www.apache.org/licenses/LICENSE-2.0 --> <!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files): <project-config> → adopting project's `.apache-magpie/` directory <tracker> → value of `tracker_repo:` in <project-config>/project.md <upstream> → value of `upstream_repo:` in <project-config>/project.md <framework> → `.apache-magpie/apache-magpie` in adopters; `.` in the framework standalone --> # optimize-skill Take one existing framework skill — or a maintainer-supplied set of them — and make it leaner without changing what it does. The skill diagnoses a target against the optimization catalogue distilled from the recent security-suite refactors, proposes the applicable passes, and applies them one at a time as **behavior-preserving** edits the maintainer confirms. The skill validator (and, for tracker-touching skills, the placeholder linter) is the deterministic gate: it is green before the first pass and green again after the last. This skill operates only on **framework-internal files** — `SKILL.md` bodies, their sibling docs, `<project-config>` manifests, tool adapters in this repo. It reads no external or attacker-controlled content, so the prompt-injection-defence callout does not apply. It is the refactoring counterpart to [`write-skill`](../write-skill/SKILL.md): `write-skill` authors a net-new skill; `optimize-skill` restructures one that already exists. The five passes, their smells, exemplar PRs, mechanics, and behavior-preservation guarantees live in [`patterns.md`](patterns.md); this body is the orchestration. --- ## Adopter overrides Before running the default behaviour documented below, this skill consults [`.apache-magpie-local/optimize-skill.md`](../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/optimize-skill.md`](../../docs/setup/agentic-overrides.md) (committed, project-wide) in the adopter repo if it exists, and applies any agent-readable overrides it finds. See [`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md) for the contract — what overrides may contain, hard rules, the reconciliation flow on framework upgrade, upstreaming guidance. **Hard rule**: agents NEVER modify the snapshot under `<adopter-repo>/.apache-magpie/`. Local modifications go in the override file. Framework changes go via PR to `apache/magpie`. --- ## Snapshot drift Also at the top of every run, this skill compares the gitignored `.apache-magpie.local.lock` (per-machine fetch) against the committed `.apache-magpie.lock` (the project pin). On mismatch the skill surfaces the gap and proposes [`/magpie-setup upgrade`](../setup/upgrade.md). The proposal is non-blocking — the user may defer if they want to run with the local snapshot for now. --- ## Inputs - **Target** — the skill to optimize, as a skill name (`security-issue-import`), a directory (`.claude/skills/security-issue-import/`), or a `SKILL.md` path. Required for a single-skill run. - **Sweep selector** (optional) — `--all` to diagnose every skill under `.claude/skills/` and rank optimization candidates without applying anything, or `over:<N>` to scope the sweep to SKILL.md files longer than `<N>` lines (default threshold: **500**, the `PRINCIPLES.md` P14 cap). - **Pass filter** (optional) — restrict to named passes from [`patterns.md`](patterns.md), e.g. `pass:split` or `pass:config-lift,out-of-context`. Default: propose every applicable pass. When no target and no sweep selector are given, default to a read-only `--all` diagnosis and let the maintainer pick a target from the ranked list. --- ## Prerequisites - **`uv`** — runs the skill validator ([`tools/skill-and-tool-validator`](../../tools/skill-and-tool-validator/README.md)) and the placeholder linter. Without it the green-before / green-after gate cannot run; stop and ask the user to install `uv`. - **`git`** — the behavior-preservation checks rely on `git diff` / `git mv`; the skill expects a clean (or intentionally dirty, user-acknowledged) working tree so its own edits are isolable. - **`doctoc`** — regenerates a sibling/anchor TOC after a split changes headings. If absent, surface the manual TOC step instead of silently skipping it. --- ## Step 0 — Pre-flight check 1. **Target resolves** to a real skill directory containing a `SKILL.md`. A bad name → stop and list the available skills. 2. **Baseline is green.** Run the validator on the target (or the whole tree for a sweep) and record the result. If it is already **red**, stop: optimization is a no-behavior-change operation layered on a passing skill, not a way to fix a broken one. Hand the failures back; the maintainer fixes correctness first. 3. **Working tree is isolable.** Prefer a clean tree, or a dedicated branch, so the optimization diff is reviewable on its own. If the tree carries unrelated changes, surface them and ask before proceeding. 4. **Snapshot is current** (see *Snapshot drift* above) — a stale snapshot means the target on disk may not match the framework the maintainer thinks they are editing. --- ## Step 1 — Diagnose Run every diagnostic in [`patterns.md`](patterns.md) against the target and emit a findings table — one row per detected smell, each naming the pass that addresses it, the evidence (`path:line`, line count, the offending construct), and an effort/blast-radius note. Diagnosis is **read-only**; it never edits. The five smells, in the order the passes below apply them: 1. **Oversized body** — `SKILL.md` over the 500-line P14 cap, or a single section that dominates the body. → *split* pass. 2. **Concrete-name leakage** — adopter-specific values (a concrete `<upstream>` repo slug, real list addresses, real IDs) baked into the body instead of resolved from `<project-config>`. → *config-lift* pass. 3. **In-context bulk read** — a step that pulls a whole issue body, rollup comment, or large artefact into the agent context only to touch one field of it. → *out-of-context* pass. 4. **Per-item round-trips** — N sequential fetches the skill could issue as one upfront batch. → *fetch-upfront* pass. 5. **No deterministic pre-filter** — the skill spends an LLM pass on items a cheap deterministic classifier could skip as obvious no-ops. → *preflight-classifier* pass. For a sweep, rank targets by (cap overflow × number of distinct smells) and present the list; apply nothing until the maintainer picks one. --- ## Step 2 — Propose For the chosen target, propose the applicable passes **in the order above** (lowest blast radius first: a pure file move before any content lift before any tool rewire). For each proposed pass state: the exact files created/moved, the slimming delta (e.g. *"SKILL.md 3425 → ~660 lines, four new siblings"*), and the behavior-preservation guarantee from [`patterns.md`](patterns.md). Propose; do not apply. Wait for the maintainer to pick which passes to run, in which order. --- ## Step 3 — Apply one pass at a time For each confirmed pass, smallest reversible step first: - **Restructure passes (split, config-lift)** move or relocate text with **no wording change to the instructions themselves**. Use `git mv` where a whole file relocates; otherwise cut-and-paste the exact bytes and replace the body region with a one-line pointer to the new sibling. Never paraphrase a moved instruction — a behavior-preserving move means the moved bytes are identical. - **Rewire passes (out-of-context, fetch-upfront, preflight-classifier)** change *how* a step runs, not *what decision it reaches*. They route through an existing deterministic tool (e.g. [`github-body-field`](../../tools/github-body-field/README.md), [`github-rollup`](../../tools/github-rollup/README.md)) or a pre-flight classifier; the human-visible proposals and gates the skill produces are unchanged. If a rewire would alter what the skill proposes to the user, it is a behavior change — stop and route it through normal review, not this skill. After each pass: regenerate the doctoc TOC if headings moved, and re-run the validator. One pass per commit keeps the diff reviewable and the `git mv` rename-detection intact. --- ## Step 4 — Validate (green-after gate) Re-run the validator (and the placeholder linter for tracker- touching skills) on the optimized target. It **must** return the same green it returned at Step 0. Then prove behavior preservation: - For restructure passes, confirm the concatenation of `SKILL.md` + new siblings contains the same instruction bytes as the original (a moved-not-changed check: `git diff` should show deletions in `SKILL.md` matching additions in the siblings, plus the new pointer lines). - For rewire passes, confirm the skill's proposal/apply surface — the things a human signs off on — is unchanged; only the in-context cost or round-trip count drops. If the validator goes red or behavior preservation cannot be shown, **revert the pass** and hand back; do not ship a half-applied optimization. --- ## Step 5 — Hand back Summarise per pass: files touched, the slimming delta, validator result, and the behavior-preservation evidence. Do **not** open a PR or commit unless the maintainer asks — surface the diff and let them review. When they do commit, one pass per commit, subject in the `refactor(<skill>): …` form the security-suite splits used (e.g. *"extract N subdocs to slim SKILL.md A → B lines"*). If the run was a sweep, restate the ranked remaining candidates so the maintainer can queue the next one. --- ## Hard rules - **Behavior never changes.** This skill restructures and rewires; it never alters what a skill decides, proposes, or asks a human to confirm. A change that alters behavior is out of scope — route it through normal skill editing and review. - **Moved bytes are identical bytes.** A split or lift that paraphrases the moved instructions is a behavior change in disguise. Move verbatim; only the surrounding pointer is new. - **Propose before applying.** Every pass is a proposal the maintainer confirms (framework Principle 6). Never batch-apply a sweep. - **The validator is the gate.** Green before, green after, every pass. A pass that needs the validator relaxed is not an optimization. - **The optimized SKILL.md still obeys P14** — under 500 lines, with every sibling linked exactly one level deep and no unreferenced siblings. - **Never touch the snapshot** (`<adopter-repo>/.apache-magpie/`). Framework-skill optimizations land via PR to `apache/magpie`. --- ## References - [`patterns.md`](patterns.md) — the five optimization passes: smell, exemplar PR, mechanics, behavior-preservation guarantee, validation. - [`write-skill`](../write-skill/SKILL.md) — authoring a net-new skill (this skill's counterpart). - [`tools/skill-and-tool-validator`](../../tools/skill-and-tool-validator/README.md) — the green-before / green-after gate. - [`tools/github-body-field`](../../tools/github-body-field/README.md) and [`tools/github-rollup`](../../tools/github-rollup/README.md) — out-of-context read/PATCH tools the rewire passes route through. - [`docs/labels-and-capabilities.md`](../../docs/labels-and-capabilities.md) — the `capability:*` taxonomy and the P14 authorship rule this skill enforces.