---
name: forge:insert-phase
description: Insert urgent work as decimal phase between existing phases
argument-hint: <after-phase> <description>
allowed-tools:
  - Read
  - Write
  - Bash
---

<objective>
Insert urgent work as a decimal phase between existing phases in the roadmap.

Use when: Urgent bug fix, hotfix, or critical work must be done before continuing current work.

Decimal phase format: `X.Y` where X is parent phase, Y increments (0.1, 0.2, etc.)
</objective>

<execution_context>
@state/STATE.json
@ROADMAP.md
@CLAUDE.md
</execution_context>

<context>
**After Phase:** First argument (e.g., "72")
**Description:** Second argument

**Decimal Phase Assignment:**
1. Find existing decimal phases under parent
2. Calculate next decimal (0.1, 0.2, 0.3, etc.)
3. Insert into roadmap after parent phase
4. Update phase dependencies if needed
</context>

<process>
**Execute insert-phase workflow:**

1. **Parse Arguments**
   - Extract parent phase number (e.g., "72")
   - Extract phase description

2. **Load State**
   - Read state/STATE.json
   - Read ROADMAP.md
   - Find parent phase entry

3. **Calculate Decimal Phase**
   - Find existing decimals under parent (72.1, 72.2, etc.)
   - Next decimal = highest + 0.1
   - Example: If 72.1, 72.2 exist → next is 72.3

4. **Generate Slug**
   - Create URL-safe slug from description
   - Format: `<decimal-phase>-<slug>`
   - Example: "Hotfix auth bug" → "72.3-hotfix-auth-bug"

5. **Create Directory Structure**
   ```bash
   mkdir -p .planning/phases/<phase-slug>/
   touch .planning/phases/<phase-slug>/CONTEXT.md
   touch .planning/phases/<phase-slug>/PLAN.md
   ```

6. **Update ROADMAP.md**
   - Insert new phase entry immediately after parent phase
   - Use standard phase format with decimal number
   - Note as "INSERTED" for visibility

7. **Update Dependencies**
   - If parent phase had dependents, add decimal phase as new dependency
   - Example: Phase 73 depends on 72, insert 72.3 → 73 now depends on 72.3

8. **Submit Event**
   - Event type: PHASE_INSERTED
   - Include: phaseId, parentPhaseId, milestoneId, description
   - Write to state/events/

9. **Confirm**
   - Show inserted phase info
   - List any updated dependencies
   - Suggest next: `/forge:discuss <phase-number>` or `/forge:plan <phase-number>`
</process>

<deliverables>
- .planning/phases/<phase-slug>/CONTEXT.md (empty template)
- .planning/phases/<phase-slug>/PLAN.md (empty template)
- ROADMAP.md updated with inserted phase
- Updated dependencies for subsequent phases
- Event: PHASE_INSERTED in state/events/
- STATE.json updated
</deliverables>

<next_steps>
- Run `/forge:discuss <phase-number>` to capture phase context
- Run `/forge:plan <phase-number>` to generate task breakdown
- Notify team of dependency changes
- Tip: Use `/clear` to start from a fresh context
</next_steps>