flow-builder

What this skill does

# Flow Builder

Execute implementation work following Flow framework patterns. This skill guides the build phase: verify readiness → start implementation → execute action items → verify completion → mark complete.

## When to Use This Skill

Activate when the user wants to start coding:
- "Let's implement this"
- "Start coding"
- "Build the feature"
- "Time to write code"
- "Ready to implement"
- "Execute the action items"
- "Begin implementation"

## Implementation Philosophy

**Flow's Core Principle**: Design before code. Implementation happens AFTER brainstorming is complete (if needed) and pre-implementation tasks are done.

**Key Gates**:
- **Pre-Implementation Gate**: Brainstorming must be ✅ COMPLETE (if iteration had brainstorming)
- **Pre-Tasks Gate**: All pre-implementation tasks must be ✅ COMPLETE
- **Verification Gate**: All action items done, tests passing, ready for next work

**Implementation Pattern**: Start → Execute → Verify → Complete

## Pre-Implementation Gate Check

Before starting ANY implementation, verify readiness:

### Check 1: Brainstorming Status (if applicable)

```
IF iteration has brainstorming section:
    IF brainstorming status ≠ ✅ COMPLETE:
        ❌ BLOCK implementation
        SUGGEST: "Brainstorming must be completed first. Use `/flow-next-subject` to continue brainstorming."
    ELSE:
        ✅ PASS gate
ELSE:
    ✅ PASS gate (no brainstorming needed)
```

### Check 2: Pre-Implementation Tasks (if applicable)

```
IF iteration has "Pre-Implementation Tasks" section:
    IF any pre-task status ≠ ✅ COMPLETE:
        ❌ BLOCK implementation
        LIST incomplete pre-tasks
        SUGGEST: "Complete pre-tasks first, then use `/flow-implement-start`"
    ELSE:
        ✅ PASS gate
ELSE:
    ✅ PASS gate (no pre-tasks)
```

### Check 3: Iteration Status

```
IF iteration status = 🚧 IN PROGRESS:
    ✅ PASS (already implementing)
IF iteration status = 🎨 READY or ⏳ PENDING:
    SUGGEST: "Use `/flow-implement-start` to begin implementation"
```

## Implementation Workflow

### Step 1: Start Implementation

**Command**: `/flow-implement-start`

**What it does**:
- Marks iteration 🚧 IN PROGRESS
- Creates "Implementation" section in task file
- Updates DASHBOARD.md current work

**When to suggest**: User is ready to code and gates passed

### Step 2: Execute Action Items

**Sequential Execution**:
1. Read action items from iteration (or brainstorming Type D subjects)
2. Execute each action item in order
3. Check off items as completed: `- [x] Action item`
4. Document progress in "Implementation Notes"

**Parallel Execution** (when safe):
- If action items are independent (no dependencies)
- Example: Creating multiple unrelated files
- Still check off sequentially for tracking

**Handling Blockers**:
```
IF encounter blocker during implementation:
    DOCUMENT blocker in Implementation Notes
    ASSESS severity:
        - Minor (< 15 min fix): Handle and continue
        - Major (> 15 min, out of scope): STOP and notify user
        - Blocking (cannot proceed): Mark iteration ❌ BLOCKED, notify user
```

### Step 3: Verify Completion

Before marking iteration complete, verify:

**Verification Checklist**:
- [ ] All action items checked off (✅)
- [ ] Code compiles/runs without errors
- [ ] Tests passing (if applicable)
- [ ] Files modified documented
- [ ] Implementation notes updated
- [ ] No unresolved blockers

**Testing Strategy** (from PLAN.md):
- Follow Testing Strategy section in PLAN.md
- Run tests according to project conventions
- Document test results in Implementation Notes

### Step 4: Complete Implementation

**Command**: `/flow-implement-complete`

**What it does**:
- Marks iteration ✅ COMPLETE
- Updates completion date
- Updates DASHBOARD.md progress
- Advances to next iteration

**When to suggest**: All verification criteria met

## Implementation Slash Commands

### `/flow-implement-start`

**Use when**: Starting implementation for current iteration

**Prerequisites**:
- Brainstorming ✅ COMPLETE (if applicable)
- Pre-tasks ✅ COMPLETE (if applicable)
- Iteration status = 🎨 READY or ⏳ PENDING

**Effect**:
- Changes iteration status to 🚧 IN PROGRESS
- Creates implementation section in task file
- Updates DASHBOARD.md

### `/flow-implement-complete`

**Use when**: All action items done and verified

**Prerequisites**:
- All action items checked off
- Verification criteria met
- No unresolved blockers

**Effect**:
- Marks iteration ✅ COMPLETE
- Updates completion date
- Advances to next iteration or task

## Action Item Execution Patterns

### Pattern 1: Sequential Implementation

**Use when**: Action items depend on each other

```markdown
Action Items:
- [x] Create database schema
- [x] Implement data access layer (depends on schema)
- [x] Add service layer (depends on DAL)
- [x] Create API endpoints (depends on service)
```

**Approach**:
1. Complete item 1
2. Verify item 1 works
3. Move to item 2
4. Repeat until all done

### Pattern 2: Parallel Implementation

**Use when**: Action items are independent

```markdown
Action Items:
- [ ] Create logger utility
- [ ] Create validator utility
- [ ] Create formatter utility
```

**Approach**:
1. Create all three files
2. Verify each works independently
3. Check off all items

### Pattern 3: Incremental Verification

**Use when**: Complex implementation with multiple steps

```markdown
Action Items:
- [x] Implement basic authentication (VERIFY: can login)
- [x] Add JWT token generation (VERIFY: tokens valid)
- [x] Add token refresh (VERIFY: refresh works)
- [x] Add logout (VERIFY: tokens invalidated)
```

**Approach**:
1. Complete one action item
2. Test/verify immediately
3. Document verification in notes
4. Move to next item

## Pre-Implementation Tasks Pattern

### What Are Pre-Implementation Tasks?

Small blocking tasks (< 30 min) that must be completed BEFORE main iteration work starts.

**Examples**:
- Refactor interface to support new pattern
- Update enum with missing values
- Fix bug in legacy code
- Rename file to match convention

### When to Complete Pre-Tasks

```
IF iteration has "Pre-Implementation Tasks" section:
    FOR EACH pre-task:
        Complete pre-task
        Mark ✅ COMPLETE with date
        Document changes in pre-task section
    ONLY AFTER ALL PRE-TASKS DONE:
        Run /flow-implement-start for main iteration
```

### Pre-Task Structure

```markdown
#### Pre-Implementation Tasks

##### ⏳ Pre-Task 1: Update ErrorHandler to support async

**Why Blocking**: Retry logic requires async error handling

**Scope** (< 30 min):
- Update ErrorHandler.ts with async support
- Add retryAsync() method
- Update 3 call sites

**Files**:
- src/utils/ErrorHandler.ts

---

##### ✅ Pre-Task 1: Update ErrorHandler to support async

**Completed**: 2025-10-30

**Changes Made**:
- Added async support to ErrorHandler class
- Implemented retryAsync() method with exponential backoff
- Updated call sites in BillingService, PaymentService, OrderService
- Added unit tests for async error handling

**Files Modified**:
- src/utils/ErrorHandler.ts (+42 lines)
- tests/utils/ErrorHandler.test.ts (+28 lines)
```

## Verification Best Practices

### What to Verify

**Code Quality**:
- [ ] No syntax errors
- [ ] No linting errors
- [ ] Follows project conventions
- [ ] Code is readable and well-structured

**Functionality**:
- [ ] Feature works as intended
- [ ] Edge cases handled
- [ ] Error handling implemented
- [ ] No regressions introduced

**Testing**:
- [ ] Unit tests pass
- [ ] Integration tests pass (if applicable)
- [ ] Manual testing done (if no automated tests)

**Documentation**:
- [ ] Implementation notes updated
- [ ] Files modified list complete
- [ ] Verification results documented

### When to Mark ❌ BLOCKED

Mark iteration ❌ BLOCKED when:
- External dependency not available
- Blocker requires > 1 hour to resolve
- Need user decision before proceeding
- Technical limitation discovered

**Blocked Pattern**:
```markdown
### ❌ Iteration 2: Error Handlin