Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.

Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.

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

Example: /kata:kata-insert-phase 72 Fix critical auth bug

→ after = 72 → description = "Fix critical auth bug"

Validation:

if [ $# -lt 2 ]; then echo "ERROR: Both phase number and description required" echo "Usage: /kata:kata-insert-phase <after> <description>" echo "Example: /kata:kata-insert-phase 72 Fix critical auth bug" exit 1 fi

Parse first argument as integer:

after_phase=$1 shift description="$*"

Validate after_phase is an integer

if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then echo "ERROR: Phase number must be an integer" exit 1 fi

if [ -f .planning/ROADMAP.md ]; then ROADMAP=".planning/ROADMAP.md" else echo "ERROR: No roadmap found (.planning/ROADMAP.md)" exit 1 fi

Read roadmap content for parsing.

Search for "### Phase {after_phase}:" heading

If not found:

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

Exit.

Verify phase is in current milestone (not completed/archived)

• Search for all "### Phase {after_phase}.N:" headings

• Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)

• Find the highest decimal suffix

• Calculate next decimal: max + 1

Examples:

• Phase 72 with no decimals → next is 72.1

• Phase 72 with 72.1 → next is 72.2

• Phase 72 with 72.1, 72.2 → next is 72.3

Store as: decimal_phase="$(printf "%02d" $after_phase).${next_decimal}"

slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')

Phase directory name: {decimal-phase}-{slug}

Example: 06.1-fix-critical-auth-bug (phase 6 insertion)

phase_dir=".planning/phases/pending/${decimal_phase}-${slug}" mkdir -p "$phase_dir"

Confirm: "Created directory: $phase_dir"

Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")

Insert new phase heading with (INSERTED) marker:

Phase {decimal_phase}: {Description} (INSERTED)

Goal: [Urgent work - to be planned] Depends on: Phase {after_phase} Plans: 0 plans

Plans:

• TBD (run /kata:kata-plan-phase {decimal_phase} to break down)

Details: [To be added during planning]

Write updated roadmap back to file

The "(INSERTED)" marker helps identify decimal phases as urgent insertions.

Preserve all other content exactly (formatting, spacing, other phases).

• Read .planning/STATE.md

• Under "## Accumulated Context" → "### Roadmap Evolution" add entry:

• Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)

If "Roadmap Evolution" section doesn't exist, create it.

Add note about insertion reason if appropriate.

Phase {decimal_phase} inserted after Phase {after_phase}:

• Description: {description}
• Directory: .planning/phases/{decimal-phase}-{slug}/
• Status: Not planned yet
• Marker: (INSERTED) - indicates urgent work

Roadmap updated: {roadmap-path} Project state updated: .planning/STATE.md

▶ Next Up

Phase {decimal_phase}: {description} — urgent insertion

/kata:kata-plan-phase {decimal_phase}

_{/clear first → fresh context window}

Also available:

• Review insertion impact: Check if Phase {next_integer} dependencies still make sense
• Review roadmap

<anti_patterns>

• Don't use this for planned work at end of milestone (use /kata:kata-add-phase)

• Don't insert before Phase 1 (decimal 0.1 makes no sense)

• Don't renumber existing phases

• Don't modify the target phase content

• Don't create plans yet (that's /kata:kata-plan-phase)

• Don't commit changes (user decides when to commit) </anti_patterns>

<success_criteria> Phase insertion is complete when:

• Phase directory created: .planning/phases/pending/{N.M}-{slug}/

• Roadmap updated with new phase entry (includes "(INSERTED)" marker)

• Phase inserted in correct position (after target phase, before next integer phase)

• STATE.md updated with roadmap evolution note

• Decimal number calculated correctly (based on existing decimals)

• User informed of next steps and dependency implications </success_criteria>