---
id: skill-edit-step-ordering-spec
app: wkappbot
description: "Feature spec for wkappbot skill edit step management commands. Until implemented: use workarounds documented here. After implementation: use flags directly."
tags: [skill, edit, step, ordering, insert, move, delete, swap, undo, clone, diff, spec, workaround, feature-request]
---

# skill edit step ordering UX spec: insert/move/delete/swap/undo/clone/diff

## Steps

1. PROBLEM: --add-step always appends to end (step N+1). No --insert-before/after flag exists. --step N --content intermittently dispatches as background task instead of synchronous. Result: misplaced steps require ugly ordering hacks in step 1 text (e.g. 'run steps 2, 3, 11, 4' instead of '2, 3, 4, 5').
2. SPEC [MUST] Step insert: wkappbot skill edit <id> --insert-before N --content TEXT. Inserts new step before position N; old steps N+ shift down by 1. wkappbot skill edit <id> --insert-after N --content TEXT. Inserts after N; old steps N+1+ shift down. Both: print [SKILL] inserted step M: TEXT and exit 0 synchronously.
3. SPEC [MUST] Step move and delete: wkappbot skill edit <id> --move-step N --to M (moves step N to M; renumbers affected range). wkappbot skill edit <id> --delete-step N (removes step N; shifts N+1+ down). wkappbot skill edit <id> --swap-steps N M (exchanges content of N and M, no renumber).
4. SPEC [MUST] Bulk reorder: wkappbot skill edit <id> --reorder 1,3,2,4,5. Full new sequence as comma-separated current step numbers. Validates all steps present exactly once. Prints [SKILL] reordered: 1,3,2,4,5.
5. SPEC [MUST] Auto step-ref update + foreground guarantee: on insert/move/delete that shifts numbers, scan all step bodies for literal 'step N' and update to new number (opt-out: --no-ref-update). --step N --content X must print [SKILL] step N: old -> new synchronously to stdout; never defer to background task.
6. SPEC [NICE] Undo: wkappbot skill edit <id> --undo. Rolls back to previous version (v1.5 -> v1.4). Prints [SKILL] rolled back to v1.4. NICE Dry-run: --dry-run flag on any edit: prints proposed change without saving. Format: [DRY-RUN] step N: OLD -> NEW (not saved).
7. SPEC [NICE] Clone and Diff: wkappbot skill clone <id> <new-id> (duplicates skill at v1.0 under new id). wkappbot skill diff <id> (git-diff-style comparison of current vs previous version -- step additions/removals/changes).
8. WORKAROUND until implemented: (1) --add-step to append, then update step 1 order text manually. (2) For --step N --content background failure: retry once with shorter content. (3) Label misplaced steps in step 1 with parenthetical: '11(skill news)'. (4) To delete: note step number in desc, skip in step 1 order ref.
9. SUGGEST REF: ts=2026-05-23T06:18:21 DG-wkappbot-sdk tracks implementation status of all MUST/NICE items above. Check wkappbot suggest read <ts> for current resolution state.
