# Deleting A Pipeline Step

> Remove a step from an existing named Superpipelines workflow while preserving topology continuity.

- Skill: `gustavo-meilus/deleting-a-pipeline-step` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gustavo-meilus/deleting-a-pipeline-step`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gustavo-meilus/deleting-a-pipeline-step/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: gustavo-meilus (https://skillmd.com/u/gustavo-meilus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gustavo-meilus/deleting-a-pipeline-step

---


# Deleting a Pipeline Step — Removal Workflow

<overview>
Removes a named step from an existing pipeline. Performs gap analysis to identify predecessor/successor disconnections, stages all file removals and topology mutations for audit, and enforces a mandatory human approval gate before any irreversible deletion occurs.
</overview>

<glossary>
  <term name="Gap Analysis">The process of identifying predecessor/successor disconnections caused by a step removal.</term>
  <term name="Through-gap">A condition where a deleted step sat between two active steps, requiring direct reconnection.</term>
  <term name="Blocking-gap">A condition where a deleted step was the sole source of required inputs for a successor.</term>
</glossary>

## Workflow Phases

<protocol>
### PHASE 0: PIPELINE & STEP SELECTION
- Resolve scope registries and identify the target pipeline and step.
- Display the current `topology.json` as a graph showing all dependency chains.

### PHASE 1: GAP ANALYSIS
- Analyze the impact of removal on predecessors and successors.
- <HARD-GATE>If a **Blocking-gap** is found (no alternative input source), STOP. The user must provide an alternative source or cancel the deletion.</HARD-GATE>

### PHASE 2: MUTATION DESIGN (REWIRE)
- For through-gaps or entry-gaps, present a rewire plan to the user (e.g., "Wire A directly to C").
- Dispatch `pipeline-architect` in `STEP-DELETE` mode to stage all changes.
- <invariant>All mutations (file removals and topology updates) MUST be staged in `edit-{ts}/`. NEVER delete directly from production paths during design.</invariant>
- **Architect completion manifest gate**: After the architect returns, read the STEP-DELETE completion manifest. It MUST cover every file the architect was tasked with touching and use only `edited`, `copied-unchanged`, or `deleted`.
  - <HARD-GATE>If any expected markdown artifact (`*.md`) is listed as `copied-unchanged`, STOP before Phase 3. Emit a blocking error naming the file and explain that unchanged markdown in STEP-DELETE staging indicates an architect partial exit.</HARD-GATE>
  - <HARD-GATE>If any expected file is missing from the manifest, STOP before Phase 3. The staging set is incomplete and cannot be audited as a coherent delta.</HARD-GATE>
- **Staged markdown modification guard**: Independently diff every staged `*.md` file against its production original before Phase 3. If the staged file has a production source and is byte-identical to that source, STOP before Phase 3 with a blocking error naming both paths. This guard is independent of the manifest and catches partial exits even when the manifest is wrong or missing detail.
- **Pre-audit residual-reference scan**: Prefer the Phase 3 delta auditor as the authoritative gate. If a manual grep is run as an additional pre-audit smoke check, it MUST explicitly include markdown files (for example, `--include="*.md"`) so `.md` artifacts cannot be silently skipped.

### PHASE 3: DELTA AUDIT
- Dispatch `pipeline-auditor` in `DELTA` mode on the staged topology, entry skill, and neighbor steps.
- <HARD-GATE>SEV-0 or SEV-1 findings block deletion. A fragmented pipeline is a critical failure. Re-audit until the delta is clear.</HARD-GATE>

### PHASE 4: HUMAN APPROVAL
- Present a "Deletion Manifest" showing exactly which files will be removed and which edges will be rewired.
- <HARD-GATE>Wait for explicit `APPROVE`. On `CANCEL`, discard all staged changes and do NOT delete artifacts.</HARD-GATE>

### PHASE 5: ATOMIC PROMOTION
- Execute file removals (agents/skills) and write updated `topology.json` and `tasks.md`.
- Update the `registry.json` to reflect the removal.
- **Version Stamp**: Update `plugin_version` in `topology.json` and the registry entry to the current superpipelines version.
</protocol>

<invariants>
- NEVER assume a step is "unused" without verifying all `depends_on` entries in the topology graph.
- ALWAYS perform atomic promotion from a staging area to ensure rollback capability.
- NEVER delete a step that creates an unresolvable blocking-gap in the orchestration.
- ALWAYS update `plugin_version` in `topology.json` and the registry entry to the current superpipelines version when promoting changes.
</invariants>

## Red Flags — STOP
- "The pipeline will work without rewiring — it's obvious." → **STOP**. Obvious assumptions are the leading source of silent runtime failures.
- "I'll skip the human gate; deletion is a simple task." → **STOP**. Deletion is irreversible; the human gate is the final recovery point.
- "I'll delete the files first, then update the topology." → **STOP**. This results in a broken pipeline if the topology update fails.

## Rationalization Table

<rationalization_table>
| Excuse | Reality |
| :--- | :--- |
| "The step is terminal, why audit?" | Removing a terminal step can still break final status reporting or cleanup logic. |
| "Rewiring is over-engineering." | A broken dependency chain blocks every subsequent pipeline run. Rewiring is essential maintenance. |
| "I can recover from git if I'm wrong." | Relying on git recovery for basic workflow errors indicates a failure of the safety protocol. |
</rationalization_table>

## Reference Files
- `sk-pipeline-paths/SKILL.md` — Path resolution.
- `sk-pipeline-state/SKILL.md` — Run state tracking.
- `adding-a-pipeline-step/SKILL.md` — Insertion workflow.
- `updating-a-pipeline-step/SKILL.md` — Modification workflow.