flow-completer

What this skill does

# Flow Completer

Mark tasks and phases complete after verifying all work is done. This skill enforces completion gates to ensure nothing is forgotten before moving forward.

## When to Use This Skill

Activate when the user wants to finish work:
- "Finish this task"
- "Mark task complete"
- "Done with this task"
- "Complete the task"
- "Finish this phase"
- "Mark phase complete"
- "Done with this phase"
- "Close the task"
- "Close the phase"

## Completion Philosophy

**Flow's Core Principle**: Verify before closing. Every completion requires verification that all work is done, tested, and documented.

**Key Gates**:
- **Task Completion Gate**: All iterations ✅ COMPLETE (or ❌ CANCELLED/🔮 DEFERRED)
- **Phase Completion Gate**: All tasks ✅ COMPLETE (or ❌ CANCELLED)
- **Documentation Gate**: All changes documented, notes updated

**Completion Pattern**: Verify → Update Status → Advance Pointer → Report

## Task Completion Workflow

### Step 1: Read Task File

Before marking task complete, read the task file to understand current state:

**READ**: `.flow/phase-N/task-M.md`

**Extract**:
- Task name and status
- All iterations (if task has iterations)
- All action items (if standalone task)
- Current work status

### Step 2: Verify Task Completion

**Verification Checklist**:

```
IF task has iterations:
    FOR EACH iteration:
        IF status = ⏳ PENDING or 🚧 IN PROGRESS:
            ❌ FAIL: "Iteration N: [Name] is not complete"
        IF status = ❌ CANCELLED or 🔮 DEFERRED:
            ✅ PASS (acceptable, not blocking)
        IF status = ✅ COMPLETE:
            ✅ PASS
    IF ALL iterations are ✅/❌/🔮:
        ✅ PASS task verification

ELSE IF standalone task:
    IF any action items unchecked `- [ ]`:
        ❌ FAIL: "X action items incomplete"
    IF all action items checked `- [x]`:
        ✅ PASS task verification
```

**Additional Checks**:
- [ ] Implementation notes updated (if task had implementation)
- [ ] Files modified documented
- [ ] No unresolved blockers mentioned
- [ ] Verification section filled out

### Step 3: Mark Task Complete

If verification passes:

1. **Update task file**:
   ```markdown
   # Task N: Name

   **Status**: ✅ COMPLETE (2025-MM-DD)
   ```

2. **Update DASHBOARD.md**:
   - Find task in "Progress Overview"
   - Change marker: `⏳ Task N: Name` → `✅ Task N: Name`
   - Update phase completion percentage
   - Advance "Current Work" pointer to next pending task

3. **Report to user**:
   ```
   ✅ Task N: [Name] marked complete!

   Completed:
   - [X] iterations complete (or Y cancelled/deferred)
   - All action items verified
   - Documentation updated

   Next: [Next task or phase status]
   ```

### Step 4: Handle Incomplete Work

If verification fails:

1. **Report incomplete items**:
   ```
   ❌ Cannot mark task complete. Incomplete work found:

   Iterations:
   - ⏳ Iteration 2: [Name] - Status: PENDING
   - 🚧 Iteration 3: [Name] - Status: IN PROGRESS

   OR

   Action Items:
   - [ ] 3 unchecked action items

   Complete these first, then use `/flow-task-complete` again.
   ```

2. **Suggest actions**:
   - If iterations pending: "Use `/flow-next-iteration` to continue work"
   - If action items unchecked: "Complete remaining action items"
   - If user wants to defer: "Use `/flow-iteration-add` to mark iteration 🔮 DEFERRED"

## Phase Completion Workflow

### Step 1: List All Tasks in Phase

**READ**: `.flow/phase-N/` directory

**Extract**:
- All task files in phase directory
- Count total tasks
- Determine status of each task

### Step 2: Verify Phase Completion

**Verification Checklist**:

```
FOR EACH task in phase:
    IF task status = ⏳ PENDING or 🚧 IN PROGRESS:
        ❌ FAIL: "Task N: [Name] is not complete"
    IF task status = ❌ CANCELLED:
        ✅ PASS (acceptable, not blocking)
    IF task status = ✅ COMPLETE:
        ✅ PASS

IF ALL tasks are ✅/❌:
    ✅ PASS phase verification
```

**Additional Checks**:
- [ ] Phase goals achieved (check DASHBOARD.md phase description)
- [ ] All deliverables complete
- [ ] No pending work in any task

### Step 3: Mark Phase Complete

If verification passes:

1. **Update DASHBOARD.md**:
   - Find phase in "Progress Overview"
   - Change header: `### Phase N: Name` → `### Phase N: Name ✅`
   - Update phase status line
   - Advance "Current Work" to next phase

2. **Report to user**:
   ```
   ✅ Phase N: [Name] marked complete!

   Completed:
   - [X] tasks complete (Y cancelled)
   - All phase goals achieved

   Next Phase: Phase [N+1]: [Name]
   OR
   Project complete! 🎉
   ```

### Step 4: Handle Incomplete Work

If verification fails:

1. **Report incomplete tasks**:
   ```
   ❌ Cannot mark phase complete. Incomplete tasks found:

   Tasks:
   - ⏳ Task 2: [Name] - Status: PENDING
   - 🚧 Task 3: [Name] - Status: IN PROGRESS

   Complete these first, or cancel if scope changed.
   ```

2. **Suggest actions**:
   - "Use `/flow-task-start` to continue Task N"
   - "Use `/flow-task-complete` to finish Task N"
   - If scope changed: "Consider marking Task N as ❌ CANCELLED"

## Completion Slash Commands

### `/flow-task-complete`

**Use when**: All iterations/action items done for current task

**Prerequisites**:
- All iterations ✅ COMPLETE (or ❌/🔮)
- All action items checked off (if standalone)
- Documentation updated

**Effect**:
- Marks task ✅ COMPLETE with date
- Updates DASHBOARD.md progress
- Advances current work pointer

### `/flow-phase-complete`

**Use when**: All tasks done in current phase

**Prerequisites**:
- All tasks ✅ COMPLETE (or ❌ CANCELLED)
- Phase goals achieved

**Effect**:
- Marks phase ✅ COMPLETE
- Updates DASHBOARD.md
- Advances to next phase or project end

## Edge Cases

### Cancelled or Deferred Work

**Cancelled Iterations** (❌):
- Not blocking for task completion
- Document why cancelled in iteration notes
- Examples: Scope changed, not needed, replaced by better approach

**Deferred Iterations** (🔮):
- Not blocking for task completion
- Document why deferred (V2, future version)
- Examples: Nice-to-have, optimization, future enhancement

**Cancelled Tasks** (❌):
- Not blocking for phase completion
- Document why cancelled in task notes
- Examples: Duplicate work, scope change, no longer needed

### Partial Completion

**Scenario**: Task has 5 iterations, 3 complete, 2 deferred

```
✅ Iteration 1: Basic Implementation - COMPLETE
✅ Iteration 2: Core Features - COMPLETE
✅ Iteration 3: Testing - COMPLETE
🔮 Iteration 4: Advanced Features - DEFERRED (V2)
🔮 Iteration 5: Optimizations - DEFERRED (V2)
```

**Action**: Task can be marked complete! Deferred work doesn't block.

**Report**:
```
✅ Task can be marked complete!

Completed: 3/5 iterations
Deferred to V2: 2 iterations (documented)

This is valid - deferred work doesn't block completion.
```

### Blocked Work

**Scenario**: Task has iteration marked ❌ BLOCKED

```
✅ Iteration 1: Setup - COMPLETE
❌ Iteration 2: Implementation - BLOCKED (external dependency unavailable)
⏳ Iteration 3: Testing - PENDING
```

**Action**: Cannot mark task complete - blocked iteration needs resolution

**Report**:
```
❌ Cannot mark task complete. Found blocked work:

Iteration 2: Implementation - ❌ BLOCKED
Blocker: External dependency unavailable

Resolution options:
1. Unblock iteration and complete it
2. Mark iteration ❌ CANCELLED if no longer needed
3. Mark iteration 🔮 DEFERRED if can be done later
```

## Completion Verification Patterns

### Pattern 1: Task with All Iterations Complete

```
✅ Iteration 1: Skeleton - COMPLETE (2025-10-15)
✅ Iteration 2: Veins - COMPLETE (2025-10-18)
✅ Iteration 3: Flesh - COMPLETE (2025-10-22)
```

**Verification**: ✅ PASS - All iterations complete

**Action**: Mark task complete

### Pattern 2: Task with Mixed Status

```
✅ Iteration 1: Basic Feature - COMPLETE (2025-10-15)
❌ Iteration 2: Advanced Feature - CANCELLED (scope change)
🔮 Iteration 3: Optimization - DEFERRED (V2)
```

**Verification**: ✅ PASS - No pending/in-progress iterations

**Action**: Mark task