flow-designer

What this skill does

# Flow Designer

Help users design features through structured brainstorming sessions and make architectural decisions that shape the project.

## When to Use This Skill

Activate when the user wants to design or brainstorm:
- "Let's brainstorm this"
- "Design the approach"
- "How should we architect this?"
- "What's the best way to implement this?"
- "Should we use [technology]?"
- "Update architecture documentation"
- "Add a DO/DON'T rule"

## Design Philosophy

**Flow's Core Principle**: Design before implementation. Use structured brainstorming to explore options, make decisions, and document rationale before writing code.

**Brainstorming Structure**:
- **Subjects**: Questions or decisions to resolve
- **Resolution Types**: How each subject gets resolved (A/B/C/D)
- **Outcomes**: Pre-tasks (Type A), documentation (Type B), or action items (Type D)

## Brainstorming Workflow

### Step 1: Start Brainstorming

When user wants to brainstorm an iteration:

1. Read DASHBOARD.md to find current iteration
2. Read task file to check if brainstorming section exists
3. If doesn't exist, create:
   ```markdown
   #### Brainstorming

   **Status**: 🚧 IN PROGRESS

   **Subjects to Discuss**:
   1. ⏳ [Subject Name] - [Question or decision]
   2. ⏳ [Subject Name] - [Question or decision]
   ```
4. Prompt user for initial subjects if not provided
5. Add subjects as ⏳ PENDING items

### Step 2: Add Subjects

When user wants to add a new subject:

1. Find brainstorming section in current iteration
2. Add to "Subjects to Discuss" list:
   ```markdown
   N. ⏳ Subject Name - Description
   ```
3. Keep list organized (unresolved at top)

### Step 3: Discuss and Resolve Subjects

When user asks "what's next subject" or wants to discuss:

1. Find next ⏳ PENDING or 🚧 IN PROGRESS subject
2. Display subject for discussion
3. After user discusses, help determine resolution type (see [RESOLUTION_TYPES.md](RESOLUTION_TYPES.md))
4. Create subject section with resolution:
   ```markdown
   ##### Subject N: [Name]

   **Status**: ✅ RESOLVED (2025-MM-DD)

   **Question**: [What needed to be decided]

   **Decision**: [What was decided and why]

   **Resolution Type**: [A/B/C/D]

   **Action Items** (if Type A or D):
   - [ ] [Item 1]
   - [ ] [Item 2]
   ```
5. Update subject status in list: ⏳ → ✅
6. If Type B, update PLAN.md immediately (see [PLAN_UPDATES.md](PLAN_UPDATES.md))

### Step 4: Review Brainstorming

When user asks "review brainstorming" or wants to check progress:

1. List all ✅ RESOLVED subjects
2. Show resolution types breakdown:
   - Type A subjects → Pre-Implementation Tasks
   - Type B subjects → PLAN.md updates (already done)
   - Type C subjects → Auto-resolved
   - Type D subjects → Main action items
3. Calculate: Resolved vs Total subjects
4. Suggest completing if all resolved

### Step 5: Complete Brainstorming

When user says "complete brainstorming" or ready to finish:

1. **Verify**: All subjects have ✅ RESOLVED status
2. **Collect Type A subjects** → Create "Pre-Implementation Tasks" section:
   ```markdown
   #### Pre-Implementation Tasks

   **Status**: ⏳ PENDING

   These must be completed BEFORE starting main implementation:

   - [ ] [Pre-task from Subject N]
   - [ ] [Pre-task from Subject M]
   ```
3. **Collect Type D subjects** → Add to iteration's "Action Items":
   ```markdown
   #### Action Items
   - [ ] [Main work from Subject X]
   - [ ] [Main work from Subject Y]
   ```
4. **Update brainstorming status**: `**Status**: ✅ COMPLETE (2025-MM-DD)`
5. **Set iteration status**:
   - If pre-tasks exist: `**Status**: ⏳ PENDING` (must do pre-tasks first)
   - If no pre-tasks: `**Status**: 🎨 READY` (ready to implement)
6. Report to user what's next

## Subject Resolution Types

See [RESOLUTION_TYPES.md](RESOLUTION_TYPES.md) for detailed explanation. Quick reference:

### Type A: Pre-Implementation Task

**When**: Small blocking code change needed BEFORE iteration starts

**Criteria**:
- Required for iteration (blocking)
- Small scope (< 30 min)
- Can be done independently

**Examples**: Fix interface, rename file, update enum

**Outcome**: Goes into "Pre-Implementation Tasks" section, must complete before main work

### Type B: Immediate Documentation

**When**: Architectural decision affecting system design

**Criteria**:
- No code changes yet
- Updates PLAN.md Architecture section NOW
- High-level design decision

**Examples**: Design pattern choice, API contract, data model

**Outcome**: Update PLAN.md immediately during brainstorming (see [PLAN_UPDATES.md](PLAN_UPDATES.md))

### Type C: Auto-Resolved

**When**: Subject answered by another subject's decision

**Criteria**:
- No independent decision needed
- Cascade from another subject

**Examples**: Implementation detail determined by architecture choice

**Outcome**: No action items, just note which subject resolved this

### Type D: Iteration Action Items

**When**: Substantial feature work that IS the iteration

**Criteria**:
- Main implementation work
- Takes significant time (> 30 min)

**Examples**: Build API endpoint, implement validator, create service

**Outcome**: These become the iteration's implementation action items

## Architecture Decision Making

When brainstorming reveals architectural decisions (Type B), update PLAN.md:

### When to Update PLAN.md

**Always update for**:
- Technology choices (libraries, frameworks, tools)
- Design patterns adopted
- System architecture changes
- API contracts or interfaces
- Data model decisions
- DO/DON'T guidelines that emerge

**Don't update for**:
- Implementation details (those go in task notes)
- Temporary decisions (those stay in brainstorming)
- Personal preferences (only team-wide guidelines)

### How to Update PLAN.md

See [PLAN_UPDATES.md](PLAN_UPDATES.md) for detailed patterns. Quick guide:

**Architecture Section Update**:
```markdown
### [Component/Feature Name]

**Decision**: [What was decided]

**Rationale**: [Why this approach]

**Trade-offs**:
- **Chosen**: [Approach X] because [reason]
- **Not chosen**: [Approach Y] because [reason]
```

**DO/DON'T Guidelines**:
```markdown
**DO**:
- [Guideline from experience]

**DON'T**:
- [Anti-pattern to avoid]
```

## Subject Discussion Guidance

### Asking the Right Questions

Help users explore decisions:
- "What are the options?"
- "What are the trade-offs?"
- "What are the constraints?"
- "What's the impact if we choose wrong?"
- "Is this decision reversible?"

### Recommending Resolution Types

**Recommend Type A if**:
- User says "we need to fix [X] first"
- Small blocking change mentioned
- Quick prerequisite work identified

**Recommend Type B if**:
- Major architectural decision
- Technology choice discussion
- System-wide pattern emerging
- User asks "how should we architect"

**Recommend Type C if**:
- Subject is consequence of another decision
- No independent choice to make
- Answer is implied by previous subjects

**Recommend Type D if**:
- Main feature work described
- Core implementation discussed
- User describes "what we're building"

## Examples

### Example 1: Complete Brainstorming Session

```
User: "Let's brainstorm the retry logic for API calls"

AI Process:
1. Find current iteration in task file
2. Create brainstorming section with status 🚧 IN PROGRESS
3. Suggest initial subjects:
   - Retry Strategy (exponential backoff vs fixed delay)
   - Error Classification (which errors retry)
   - Max Retry Attempts (how many before giving up)
   - Existing Error Handler (need async support)
   - Timeout Configuration (per-request vs total)

User provides input, AI adds subjects to list as ⏳ PENDING

---

User: "What's the next subject?"

AI Response:
Subject 1: Retry Strategy

Let's discuss - what are the options?
- Exponential backoff (1s, 2s, 4s, 8s...)
- Fixed delay (1s between each retry)
- Linear backoff (1s, 2s, 3s, 4s...)

Which approach fits your needs?

User: "Exponential backoff with base delay 1 second"

AI Response:
This is Type D (Iteration Action Ite