Optimizing A Pipeline

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 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.
• 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.

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.
• 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 + 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.
• The grilling reconciliation gate must close with ZERO unresolved opportunities before Phase 3.

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).
• 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 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.
• 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_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

• MANDATORY full pipeline-auditor pass over the promoted bundle. Any SEV-0/1 → auto-rollback from the snapshot + git checkpoint.
• 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).

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

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.