gustavo-meilus/superpipelines / plugins/superpipelines/skills/optimizing-a-pipeline
optimizing-a-pipeline
VerifiedOptimize an existing named Superpipelines workflow for topology, model tiers, cost, latency, and reliability.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
SKILL.md
View on GitHub---
name: optimizing-a-pipeline
description: Optimize an existing named Superpipelines workflow for topology, model tiers, cost, latency, and reliability.
user-invocable: false
---
# Optimizing a Pipeline — On-Demand Optimization Workflow
<overview>
Top-level orchestrator for optimizing an existing pipeline. A read-only `pipeline-optimizer` analyst surveys the selected bundle across four axes (topology structure, model-tier cost, past-run signals, protocol/prompt quality); a discovery session (4D → brainstorm → grill) converges the findings into an `optimization_plan` with the user; the approved plan is batch-applied atomically through the existing mutation and `change-models` engines, gated by a `pipeline-auditor` DELTA pass and proven by a mandatory full audit. Orchestration lives only here (`SUB_AGENT_SPAWNING: FALSE`); the optimizer never mutates (render-inline, #33).
</overview>
<glossary>
<term name="Opportunity">A single proposed improvement rendered by the optimizer, carrying an axis, impact, affected steps, and a suggested engine.</term>
<term name="optimization_plan">The reconciled set of accepted/rejected/modified opportunities returned by `sk-pipeline-grilling MODE=optimization`.</term>
<term name="Batch apply">Staging ALL approved changes in one `edit-{ts}/` and promoting them all-or-nothing — a multi-change optimization is one semantic change.</term>
<term name="Snapshot">A pre-mutation copy of the bundle in `edit-{ts}/backup/` plus a git checkpoint, used for rollback.</term>
</glossary>
## Workflow Phases
<protocol>
### PHASE 0 — SELECTION
- Reuse the `running-a-pipeline` Phase 0 multi-scope discovery pattern: call `sk-pipeline-paths.ENUMERATE_ALL_SCOPE_ROOTS(workspace)`, merge every `<root>/superpipelines/registry.json`, annotate each entry with `source_tier` and `scope`.
- Present the pipelines; capture the selection `{ROOT, P, pattern, source_tier}`.
- Load `sk-platform-dispatch` → `DETECT()` → `platform_profile` (cache once; same probe/fallback rules as `running-a-pipeline` Phase 0.25). Emit every `platform_profile.degradation_warnings` entry.
- IF `$ARGUMENTS` named a pipeline, pre-select it; still confirm before proceeding.
### PHASE 0.5 — NO-ACTIVE-RUN SOFT GATE
- Scan `<ROOT>/superpipelines/temp/{P}/*` for run directories; read each `pipeline-state.json` top-level `status`.
- IF any run is `running` or `escalated` (non-terminal):
- `AskUserQuestion`: **(a) discard those run states** and proceed (delete the non-terminal run dirs), or **(b) abort** and let the user finish/handle them manually.
- <HARD-GATE>NEVER stage or mutate the bundle while a `running`/`escalated` run exists unless the user explicitly chose discard. `escalated`/`failed` run dirs are never deleted silently.</HARD-GATE>
### PHASE 1 — SURVEY
- Dispatch the read-only `pipeline-optimizer` via profile-driven dispatch — the SAME `platform_profile.capabilities.dispatch_mechanism` branching used by `creating-a-pipeline` Phase 4 (`native_task` → `Task()`; `native_subagent` / `model_driven` → platform-native; `inline` → Tier 2 inline loop). Hand it absolute paths (resolved via `sk-pipeline-paths`) to `topology.json`, the bundle `agents/` dir, the `temp/{P}/*/pipeline-state.json` history, any `run-telemetry.jsonl`, and the `platform_profile`.
- The optimizer renders an opportunity report as terminal output and NEVER writes a file.
- <HARD-GATE>Persistence is the orchestrator's job (#33): write the rendered report to `<ROOT>/superpipelines/temp/{P}/optimize-{ts}/findings.md` (ensure the dir exists first).</HARD-GATE>
- IF the optimizer returns `DONE_WITH_CONCERNS` (telemetry-blind axes), surface the advisory on enabling the opt-in telemetry hook (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` + register `subagent-telemetry`). NEVER auto-edit settings.
- IF no opportunities were found: report that and exit cleanly — nothing to optimize.
### PHASE 2 — DISCOVERY
- `sk-4d-method` — frame what "better" means for this pipeline (cost? latency? reliability? clarity?). Produce the `hardened` constraints.
- `superpipelines:brainstorming` — divergent exploration of alternative redesigns and their trade-offs against the findings.
- `sk-pipeline-grilling GRILL(MODE=optimization, findings, hardened)` — convergent: walk each opportunity one at a time, capturing accept/reject/modify + rationale. Returns the `optimization_plan`.
- <HARD-GATE>The grilling reconciliation gate must close with ZERO unresolved opportunities before Phase 3.</HARD-GATE>
### PHASE 3 — PLAN GATE (single human approval)
- Present the `optimization_plan` concretely: the chosen opportunities, the resulting topology diff (steps merged/split/parallelized/removed), the model-tier diff, and the predicted effect against the `hardened` success criteria.
- ONE `AskUserQuestion` approval for the whole plan (plan-gate + batch-apply: the changes interact and must be approved/audited/promoted together).
- <HARD-GATE>No staging, snapshot, or mutation before this approval returns yes. Rejection ends the workflow with the findings preserved.</HARD-GATE>
### PHASE 4 — BATCH APPLY (atomic)
- **Snapshot:** copy the bundle to `<ROOT>/superpipelines/temp/{P}/edit-{ts}/backup/` AND create a git checkpoint commit. This is the rollback source.
- **Stage ALL changes in one `edit-{ts}/`** (never promote partials):
- Topology changes (merge/split/parallelize/reorder/remove) route through the existing mutation engines — `updating-a-pipeline-step` / `adding-a-pipeline-step` / `deleting-a-pipeline-step` (architect STEP-* modes), staging into the shared `edit-{ts}/`.
- Model-tier changes route through `change-models` **Mode C** (per-agent `model_tier:` override) — recommend a tier direction only; concrete model IDs stay in profile JSON (`DEPENDENCY_INVERSION`).
- Advisory-only (Axis-4) opportunities are NOT auto-applied; surface them for manual follow-up.
- **DELTA audit:** run ONE combined `pipeline-auditor` DELTA pass over the whole staged delta.
- <HARD-GATE>SEV-0/1 == 0 is required to promote. Any SEV-0/1 → roll back from the snapshot, restore the git checkpoint, and surface the findings. Do NOT promote a partial set.</HARD-GATE>
- **Promote all-or-nothing:** on a clean DELTA audit, promote the entire `edit-{ts}/` atomically.
- **Stamp:** bump `plugin_version` on `topology.json`, the `registry.json` entry, and every touched agent; set `topology.metadata.optimization = { ts, opportunities_applied: [...], baseline_ref }` (`baseline_ref` = the git checkpoint).
### PHASE 5 — POST-APPLY PROOF
- <HARD-GATE>MANDATORY full `pipeline-auditor` pass over the promoted bundle. Any SEV-0/1 → auto-rollback from the snapshot + git checkpoint.</HARD-GATE>
- **Graph-integrity check:** every `depends_on` resolves to an existing step; no orphan edges; no unreachable non-entry step; I/O contracts chain (each consumed input is produced upstream). Any failure → auto-rollback.
- Persist the auditor report per the `commands/audit-steps.md` REPORTING contract (orchestrator owns persistence; ensure `audit/` exists; write `audit/latest.md`; update `registry.json last_audit`).
- **Offer** an optional live smoke-run via `running-a-pipeline` (not mandatory — `PARITY_TESTING: MANUAL_PHASE1`).
- Write the durable provenance report to `<ROOT>/superpipelines/pipelines/{P}/optimization-report-{ts}.md` (opportunities applied/rejected, diffs, audit verdict, baseline_ref).
</protocol>
<invariants>
- No mutation under a live run — Phase 0.5 soft gate with explicit discard-or-abort; `escalated`/`failed` runs are never deleted silently.
- Snapshot (`edit-{ts}/backup/`) + git checkpoint precede any production write.
- All-or-nothing promotion; roll back from the snapshot on any DELTA-audit, full-audit, graph-integrity, or promotion failure.
- SEV-0/1 == 0 gates BOTH the DELTA (pre-promote) and full (post-promote) audits.
- `plugin_version` is re-stamped on `topology.json`, the registry entry, and every touched agent on promotion.
- The optimizer is read-only and renders inline; the orchestrator persists (#33). Orchestration is top-level only (`SUB_AGENT_SPAWNING: FALSE`).
- Isolation-correctness and frontmatter-compliance are delegated to `pipeline-auditor` — never re-checked here (`DEPENDENCY_INVERSION`).
- No concrete model IDs in this body; model-tier changes name a tier direction only and route through `change-models` Mode C.
- One plan gate (Phase 3); batch-apply is one semantic change.
</invariants>
## Red Flags — STOP
- "The optimizer can write `findings.md` itself to save a step." → **STOP**. Read-only render-inline; the orchestrator persists (#33).
- "Promote the topology changes now; apply the tier changes after." → **STOP**. Batch-apply is all-or-nothing; partial promotion leaves the bundle in an unaudited interleaved state.
- "The DELTA audit found a SEV-1, but it's minor — promote anyway." → **STOP**. SEV-0/1 == 0 gates promotion. Roll back.
- "A run is escalated, but optimizing won't touch it." → **STOP**. Phase 0.5 gate: mutating the definition under a live run corrupts resume. Discard explicitly or abort.
- "Skip the snapshot — the git checkpoint is enough." → **STOP**. Both are required; the snapshot is the staging-local rollback source, the checkpoint the version baseline.
- "Re-check the isolation defect while surveying." → **STOP**. That is `pipeline-auditor`'s job (`DEPENDENCY_INVERSION`); the optimizer delegates.
- "Apply the advisory (Axis-4) quality fixes automatically." → **STOP**. Advisory-only opportunities are surfaced for manual decision, never auto-applied.
## Rationalization Table
<rationalization_table>
| Excuse | Reality |
| :--- | :--- |
| "One plan gate is too slow — approve each change inline." | The changes interact; piecemeal approval can promote a half-coherent topology. One plan, one gate, one atomic promote. |
| "The optimizer already audited the bundle." | It did not — it surveys opportunities. Compliance/isolation is the auditor's DELTA + full passes (`DEPENDENCY_INVERSION`). |
| "Skip the post-apply full audit; the DELTA passed." | The DELTA only saw the changed delta. The full pass + graph-integrity prove the whole bundle still chains. |
| "No telemetry, so skip past-run analysis silently." | Degrade and SAY SO — surface the opt-in hook advisory so the next run can ground cost/latency signals. |
| "Down-tier this step to `fast` and name the model." | Name a tier direction only; route through `change-models` Mode C. Concrete IDs live in profile JSON. |
| "Rolling back is wasteful after staging so much." | A failed audit/graph check means the staged set is unsafe. Rollback is the contract, not a failure of effort. |
</rationalization_table>
## Reference Files
- `agents/pipeline-optimizer.md` + `skills/pipeline-optimizer-protocol/SKILL.md` — the read-only survey worker.
- `skills/pipeline-optimizer-references/references/opportunity-taxonomy.md` — opportunity classes + heuristics.
- `sk-pipeline-grilling/SKILL.md` — `MODE=optimization` reconciliation (returns `optimization_plan`).
- `sk-4d-method/SKILL.md` · `superpipelines:brainstorming` — the discovery session.
- `updating-a-pipeline-step` · `adding-a-pipeline-step` · `deleting-a-pipeline-step` — topology mutation engines (`edit-{ts}/` staging).
- `change-models/SKILL.md` — Mode C per-agent `model_tier:` override.
- `pipeline-auditor` + `commands/audit-steps.md` — DELTA + full audit and report persistence.
- `running-a-pipeline/SKILL.md` — Phase 0 discovery pattern reused here; optional Phase 5 smoke-run.
- `sk-pipeline-paths/SKILL.md` — scope-root and path resolution.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |