optimizing

# Optimizing Bundle-Plugins

## Overview

Orchestrate targeted improvement of a bundle-plugin project or a single skill. Unlike a full audit, optimization focuses on goals: better triggering, lower token cost, tighter workflow chains, and feedback-driven skill refinement. This skill diagnoses issues, decides on improvements, and delegates content changes to `bundles-forge:authoring`.

**Core principle:** Optimize for the agent's experience. Diagnose → decide → delegate → verify.

**Skill type:** Hybrid — follow the execution flow rigidly (diagnose → decide → delegate → verify), but select targets and adapt execution strategies flexibly based on audit findings and user goals.

**Announce at start:** "I'm using the optimizing skill to improve [this project / this skill]."

## Step 1: Resolve Input & Detect Scope

The target can be a local path, a GitHub URL, or a zip file. Normalize the input to a local directory before scope detection.

### Input Normalization

> Edge cases & naming conventions: `bundles-forge:auditing` — `references/input-normalization.md`

**This is a mandatory step — do not skip it or improvise paths.** Resolve the target to a local directory before proceeding to Scope Detection.

1. **Resolve the workspace.** The workspace is `$CLAUDE_PROJECT_DIR` or `$CURSOR_PROJECT_DIR` (plugin mode), falling back to the current working directory.
2. **Normalize the target by type:**
   - **Local path** — use directly; no transformation needed.
   - **GitHub URL** — parse `<owner>` and `<repo>` from the URL. Shallow-clone to `<workspace>/.bundles-forge/repos/<owner>__<repo>/` using `--depth 1 --no-checkout`, then run `git checkout`. If the directory already exists, append a `__<YYYYMMDD>` timestamp to avoid collisions. **Do not clone to `/tmp/`, `~/`, or any path outside `.bundles-forge/repos/`.**
   - **Zip/tar.gz** — extract to `<workspace>/.bundles-forge/repos/<archive-name>/`.
3. **Create the target subdirectory** if it does not exist.
4. **On failure** (network error, 404, auth required, rate limit): tell the user what failed and suggest providing a local path or zip file instead. Do not silently skip or proceed with partial data.

See the canonical source for the full naming convention (version/timestamp suffixes), GitHub subdirectory URLs, and security rules.

### Scope Detection

**Prerequisites:** Target resolved to a local path (via Input Normalization above).

After normalization, determine the scope from the resolved local path:

| Target | How to Detect | Mode |
|--------|--------------|------|
| Project root | Has `skills/` directory and `package.json` | **Project optimization** — all 6 targets |
| Single skill directory | Contains `SKILL.md` but no `skills/` subdirectory | **Skill optimization** — 3 targets + feedback iteration |
| Single SKILL.md file | Path ends in `SKILL.md` | **Skill optimization** — 3 targets + feedback iteration |

**If the target is a single skill, skip to the Skill Optimization section below.**

---

## Project Optimization

### Process

1. **Diagnose** — run audit scripts, assess skill health, detect workflow gaps
2. **Classify & Route** — classify action type, select applicable targets
3. **Apply** — execute selected targets, delegate content changes to authoring
4. **Verify** — re-audit to confirm improvement

### Diagnostic Tools

#### Audit Script Baseline

Run the quality linter to identify frontmatter issues, description anti-patterns, and broken references before manual optimization:

```bash
bundles-forge audit-skill <target-dir>        # markdown report
bundles-forge audit-skill --json <target-dir>  # machine-readable
```

The linter automates checks Q1-Q15 and X1-X3 from the skill quality ruleset. Focus manual effort on the subjective targets below.

#### Skill Health Assessment

Assess each skill across four qualitative dimensions: trigger confidence, execution clarity, end-to-end completeness, and degradation signals. See `references/optimization-decision-trees.md` for the full assessment framework and signal-to-target mapping.

#### Workflow Gap Detection

When findings reveal structural gaps (not just broken connections but missing capabilities), consider creating new skills via the CAPTURED action type. See `references/optimization-decision-trees.md` for the gap detection signals.

### Routing & Classification

Route findings to targets and classify each action (FIX / DERIVED / CAPTURED) before delegating. See `references/optimization-decision-trees.md` for:
- **Target routing table** — maps Q/W/SC findings and user signals to the 6 targets
- **Action classification** — FIX (repair defect), DERIVED (enhance/specialize), CAPTURED (new skill for gap)
- **Pre-delegation checklist** — classification rationale, impact analysis, scope preservation

### Target 1: Skill Description Triggering

The highest-impact optimization. Descriptions are the primary mechanism for skill discovery.

**Diagnosis** — identify descriptions that summarize workflow, exceed 250 characters, are too narrow/broad, or fail to start with "Use when...".

**Decision** — draft the improved description and rationale. Use A/B eval (see below) to compare triggering accuracy before and after.

**Delegation** — invoke `bundles-forge:authoring` with a precise change spec: the old description verbatim, the new description, the rationale tied to a specific diagnosis (audit finding, health assessment dimension, or user feedback), and the action classification (FIX/DERIVED). Do not ask authoring to "improve the description" — specify the exact change.

**Guiding principle:** Use A/B eval when a change could produce regression effects — when improving one dimension might degrade another. Each eval scenario below defines its own skip conditions based on what kind of regression is possible.

#### A/B Eval for Description Changes

Follow `references/ab-eval-protocol.md` using the **Description Triggering** context. Compare trigger rate, false negatives, and false positives. S