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.
Optimizing a Pipeline — On-Demand Optimization Workflow
Workflow Phases
PHASE 0.5 — NO-ACTIVE-RUN SOFT GATE
- Scan
<ROOT>/superpipelines/temp/{P}/*for run directories; read eachpipeline-state.jsontop-levelstatus. - IF any run is
runningorescalated(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.
- NEVER stage or mutate the bundle while a
running/escalatedrun exists unless the user explicitly chose discard.escalated/failedrun dirs are never deleted silently.
PHASE 1 — SURVEY
- Dispatch the read-only
pipeline-optimizervia profile-driven dispatch — the SAMEplatform_profile.capabilities.dispatch_mechanismbranching used bycreating-a-pipelinePhase 4 (native_task→Task();native_subagent/model_driven→ platform-native;inline→ Tier 2 inline loop). Hand it absolute paths (resolved viask-pipeline-paths) totopology.json, the bundleagents/dir, thetemp/{P}/*/pipeline-state.jsonhistory, anyrun-telemetry.jsonl, and theplatform_profile. - The optimizer renders an opportunity report as terminal output and NEVER writes a file.
- 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). - 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+ registersubagent-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 thehardenedconstraints.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 theoptimization_plan.- The grilling reconciliation gate must close with ZERO unresolved opportunities before Phase 3.
PHASE 3 — PLAN GATE (single human approval)
- Present the
optimization_planconcretely: the chosen opportunities, the resulting topology diff (steps merged/split/parallelized/removed), the model-tier diff, and the predicted effect against thehardenedsuccess criteria. - ONE
AskUserQuestionapproval for the whole plan (plan-gate + batch-apply: the changes interact and must be approved/audited/promoted together). - No staging, snapshot, or mutation before this approval returns yes. Rejection ends the workflow with the findings preserved.
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 sharededit-{ts}/. - Model-tier changes route through
change-modelsMode C (per-agentmodel_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.
- Topology changes (merge/split/parallelize/reorder/remove) route through the existing mutation engines —
- DELTA audit: run ONE combined
pipeline-auditorDELTA pass over the whole staged delta. - 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.
- Promote all-or-nothing: on a clean DELTA audit, promote the entire
edit-{ts}/atomically. - Stamp: bump
plugin_versionontopology.json, theregistry.jsonentry, and every touched agent; settopology.metadata.optimization = { ts, opportunities_applied: [...], baseline_ref }(baseline_ref= the git checkpoint).
PHASE 5 — POST-APPLY PROOF
- MANDATORY full
pipeline-auditorpass over the promoted bundle. Any SEV-0/1 → auto-rollback from the snapshot + git checkpoint. - Graph-integrity check: every
depends_onresolves 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.mdREPORTING contract (orchestrator owns persistence; ensureaudit/exists; writeaudit/latest.md; updateregistry.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).
Red Flags — STOP
- "The optimizer can write
findings.mditself 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=optimizationreconciliation (returnsoptimization_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-agentmodel_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: 321k | 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: 197k | 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 |