kata-remove-phase

What this skill does

<objective>
Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.

Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
</objective>

<execution_context>
@.planning/ROADMAP.md
@.planning/STATE.md
</execution_context>

<process>

<step name="parse_arguments">
Parse the command arguments:
- Argument is the phase number to remove (integer or decimal)
- Example: `/kata-remove-phase 17` → phase = 17
- Example: `/kata-remove-phase 16.1` → phase = 16.1

If no argument provided:

```
ERROR: Phase number required
Usage: /kata-remove-phase <phase-number>
Example: /kata-remove-phase 17
```

Exit.
</step>

<step name="preflight_roadmap_format">
**Pre-flight: Check roadmap format (auto-migration)**

If ROADMAP.md exists, check format and auto-migrate if old:

```bash
if [ -f .planning/ROADMAP.md ]; then
  node "${CLAUDE_PLUGIN_ROOT}/skills/kata-remove-phase/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
  FORMAT_EXIT=$?
  
  if [ $FORMAT_EXIT -eq 1 ]; then
    echo "Old roadmap format detected. Running auto-migration..."
  fi
fi
```

**If exit code 1 (old format):**

Invoke kata-doctor in auto mode:

```
Skill("kata-doctor", "--auto")
```

Continue after migration completes.

**If exit code 0 or 2:** Continue silently.
</step>

<step name="load_state">
Load project state:

```bash
cat .planning/STATE.md 2>/dev/null
cat .planning/ROADMAP.md 2>/dev/null
```

Parse current phase number from STATE.md "Current Position" section.
</step>

<step name="validate_phase_exists">
Verify the target phase exists in ROADMAP.md:

1. Search for `### Phase {target}:` heading
2. If not found:

   ```
   ERROR: Phase {target} not found in roadmap
   Available phases: [list phase numbers]
   ```

   Exit.
</step>

<step name="validate_future_phase">
Verify the phase is a future phase (not started):

1. Compare target phase to current phase from STATE.md
2. Target must be > current phase number

If target <= current phase:

```
ERROR: Cannot remove Phase {target}

Only future phases can be removed:
- Current phase: {current}
- Phase {target} is current or completed

To abandon current work, use /kata-pause-work instead.
```

Exit.

3. Find and check for SUMMARY.md files in phase directory:

```bash
# Universal phase discovery for target phase
PADDED_TARGET=$(printf "%02d" "$TARGET" 2>/dev/null || echo "$TARGET")
PHASE_DIR=""
for state in active pending completed; do
  PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED_TARGET}-*" 2>/dev/null | head -1)
  [ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${TARGET}-*" 2>/dev/null | head -1)
  [ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility)
if [ -z "$PHASE_DIR" ]; then
  PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED_TARGET}-*" 2>/dev/null | head -1)
  [ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${TARGET}-*" 2>/dev/null | head -1)
fi

find "${PHASE_DIR}" -maxdepth 1 -name "*-SUMMARY.md" 2>/dev/null
```

If any SUMMARY.md files exist:

```
ERROR: Phase {target} has completed work

Found executed plans:
- {list of SUMMARY.md files}

Cannot remove phases with completed work.
```

Exit.
</step>

<step name="gather_phase_info">
Collect information about the phase being removed:

1. Extract phase name from ROADMAP.md heading: `### Phase {target}: {Name}`
2. Phase directory already found via universal discovery: `${PHASE_DIR}`
3. Find all subsequent phases (searching across active/pending/completed subdirectories) (integer and decimal) that need renumbering

**Subsequent phase detection:**

For integer phase removal (e.g., 17):
- Find all phases > 17 (integers: 18, 19, 20...)
- Find all decimal phases >= 17.0 and < 18.0 (17.1, 17.2...) → these become 16.x
- Find all decimal phases for subsequent integers (18.1, 19.1...) → renumber with their parent

For decimal phase removal (e.g., 17.1):
- Find all decimal phases > 17.1 and < 18 (17.2, 17.3...) → renumber down
- Integer phases unchanged

List all phases that will be renumbered.
</step>

<step name="confirm_removal">
Present removal summary and confirm:

```
Removing Phase {target}: {Name}

This will:
- Delete: ${PHASE_DIR}
- Renumber {N} subsequent phases:
  - Phase 18 → Phase 17
  - Phase 18.1 → Phase 17.1
  - Phase 19 → Phase 18
  [etc.]

Proceed? (y/n)
```

Wait for confirmation.
</step>

<step name="delete_phase_directory">
Delete the target phase directory if it exists:

```bash
if [ -d "${PHASE_DIR}" ]; then
  rm -rf "${PHASE_DIR}"
  echo "Deleted: ${PHASE_DIR}"
fi
```

If directory doesn't exist, note: "No directory to delete (phase not yet created)"
</step>

<step name="renumber_directories">
Rename all subsequent phase directories:

For each phase directory that needs renumbering (in reverse order to avoid conflicts):

Find each subsequent phase using universal discovery, then rename within the same state subdirectory:

```bash
# For each subsequent phase, find it across state subdirectories
for state in active pending completed; do
  # Example: renaming 18-dashboard to 17-dashboard within the same state dir
  SRC=$(find .planning/phases/${state} -maxdepth 1 -type d -name "18-dashboard" 2>/dev/null | head -1)
  [ -n "$SRC" ] && mv "$SRC" ".planning/phases/${state}/17-dashboard"
done
# Fallback: flat directory
SRC=$(find .planning/phases -maxdepth 1 -type d -name "18-dashboard" 2>/dev/null | head -1)
[ -n "$SRC" ] && mv "$SRC" ".planning/phases/17-dashboard"
```

Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting.

Also rename decimal phase directories:
- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17)
- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1)
</step>

<step name="rename_files_in_directories">
Rename plan files inside renumbered directories:

For each renumbered directory, rename files that contain the phase number:

```bash
# Inside 17-dashboard (was 18-dashboard):
mv "18-01-PLAN.md" "17-01-PLAN.md"
mv "18-02-PLAN.md" "17-02-PLAN.md"
mv "18-01-SUMMARY.md" "17-01-SUMMARY.md"  # if exists
# etc.
```

Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed).
</step>

<step name="update_roadmap">
Update ROADMAP.md:

1. **Remove the phase section entirely:**
   - Delete from `### Phase {target}:` to the next phase heading (or section end)

2. **Remove from phase list:**
   - Delete line `- [ ] **Phase {target}: {Name}**` or similar

3. **Remove from Progress table:**
   - Delete the row for Phase {target}

4. **Renumber all subsequent phases:**
   - `### Phase 18:` → `### Phase 17:`
   - `- [ ] **Phase 18:` → `- [ ] **Phase 17:`
   - Table rows: `| 18. Dashboard |` → `| 17. Dashboard |`
   - Plan references: `18-01:` → `17-01:`

5. **Update dependency references:**
   - `**Depends on:** Phase 18` → `**Depends on:** Phase 17`
   - For the phase that depended on the removed phase:
     - `**Depends on:** Phase 17` (removed) → `**Depends on:** Phase 16`

6. **Renumber decimal phases:**
   - `### Phase 17.1:` → `### Phase 16.1:` (if integer 17 removed)
   - Update all references consistently

Write updated ROADMAP.md.
</step>

<step name="update_state">
Update STATE.md:

1. **Update total phase count:**
   - `Phase: 16 of 20` → `Phase: 16 of 19`

2. **Recalculate progress percentage:**
   - New percentage based on completed plans / new total plans

Do NOT add a "Roadmap Evolution" note - the git commit is the record.

Write updated STATE.md.
</step>

<step name="update_file_contents">
Search for and update phase references inside plan files:

```bash
# Find files that reference the old phase numbers (search across state subdirectories)
for state in active pending completed; do
  grep -r "Phase 18" .planning/phase