flow-designer

name	flow-designer
description	Design features through brainstorming and make architectural decisions. Use when user wants to brainstorm, design approach, make architecture choices, or update PLAN.md.

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:

   #### 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:

   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)
4. Create subject section with resolution:

   ##### 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)

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:

   #### 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":

   #### 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 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)

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 for detailed patterns. Quick guide:

Architecture Section Update:

### [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:

**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 Items) - the main feature work.

Creating resolution:
**Resolution Type**: D
**Action Items**:
- [ ] Create RetryPolicy class
- [ ] Implement exponential backoff algorithm (base: 1s, max: 32s)
- [ ] Add configuration for max retries (default: 3)
- [ ] Integrate with API client
- [ ] Add tests for retry scenarios

Marked Subject 1 as ✅ RESOLVED. Next subject?

---

User: "Subject about error handler needing async support"

AI Response:
Subject 4: Existing Error Handler - Need Async Support

This sounds like a blocking prerequisite. Let me confirm:
✅ Is it blocking? YES - can't implement retry without async
✅ Is it small? YES - estimated 20-30 minutes
✅ Can be done independently? YES

This is Type A (Pre-Implementation Task).

**Resolution Type**: A
**Action Items**:
- [ ] Update ErrorHandler.ts to support async operations
- [ ] Add retryAsync() method
- [ ] Update 3 existing call sites
- [ ] Add tests for async error handling

This will go into "Pre-Implementation Tasks" - must complete BEFORE main implementation.

---

After all subjects resolved...

User: "Complete brainstorming"

AI Process:
1. Verify all 5 subjects ✅ RESOLVED
2. Collect Type A subjects:
   - Subject 4 action items → Pre-Implementation Tasks section
3. Collect Type D subjects:
   - Subject 1, 2, 3, 5 action items → Iteration Action Items
4. Mark brainstorming ✅ COMPLETE (2025-10-20)
5. Set iteration status: ⏳ PENDING (pre-tasks exist)

AI Response:
✅ Brainstorming complete!

**Pre-Implementation Tasks** (4 items):
Must complete these BEFORE starting main implementation.

**Iteration Action Items** (12 items):
Main retry logic implementation.

**Next Steps**:
1. Complete pre-implementation tasks first
2. Then run implementation on this iteration

Iteration is now ⏳ PENDING (will be 🎨 READY after pre-tasks done).

Example 2: Architecture Decision (Type B)

User: "Should we use REST or GraphQL for our API?"

AI Response:
This is a major architectural decision. Let's brainstorm:

**Subject**: API Technology Choice

**Options**:
- REST: Simple, well-understood, stateless
- GraphQL: Flexible queries, reduces over-fetching

What are your requirements? (data complexity, client needs, team experience)

User: "Team knows REST well, simple CRUD operations, mobile app needs specific fields"

AI Response:
Based on your context:
- Team experience: REST ✅
- Use case: CRUD operations fit REST
- Mobile optimization: Could benefit from GraphQL, but REST + field selection achievable

**Recommendation**: REST with field selection query params

This is Type B (Immediate Documentation) - architectural decision.

**Resolution Type**: B

I'm updating PLAN.md Architecture section now:

**PLAN.md Update**:
```markdown
### API Architecture

**Decision**: RESTful API with field selection via query parameters

**Rationale**:
- Team has strong REST experience (faster development)
- CRUD operations map naturally to REST resources
- Field selection (`?fields=name,email`) addresses mobile bandwidth concerns
- Simpler stack (no GraphQL server/client overhead)

**Trade-offs**:
- **Chosen**: REST + field selection
  - Pros: Simpler, team-ready, adequate for needs
  - Cons: Less flexible than GraphQL for complex queries
- **Not chosen**: GraphQL
  - Pros: Perfect field selection, great for evolving requirements
  - Cons: Learning curve, additional infrastructure

**DO**:
- Use field selection query params for bandwidth optimization
- Follow RESTful resource naming conventions
- Version API endpoints (/v1/users)

**DON'T**:
- Return full objects when mobile clients need subsets
- Create custom endpoint for every use case (use field selection)

✅ PLAN.md updated. Subject marked ✅ RESOLVED.

### Example 3: Auto-Resolved Subject (Type C)

User: "What about the retry delay calculation?"

AI Response: Subject 5: Retry Delay Calculation

Looking at previous decisions...

This was answered by Subject 1 (Retry Strategy):

• You chose exponential backoff with base 1s
• Formula: delay = base_delay * (2 ^ attempt_number)
• Max delay: 32s

Resolution Type: C (Auto-Resolved by Subject 1)

No additional action needed - implementation in Subject 1 covers this.

Subject marked ✅ RESOLVED.

## Files Read/Write

**READ**:
- `.flow/DASHBOARD.md` - Find current work (which iteration to brainstorm)
- `.flow/phase-N/task-M.md` - Current iteration, existing brainstorming
- `.flow/PLAN.md` - Current architecture, DO/DON'T guidelines

**WRITE**:
- `.flow/phase-N/task-M.md` - Add/update brainstorming section, subjects, resolutions
- `.flow/PLAN.md` - Update Architecture section, DO/DON'T guidelines, Technology Choices

## Validation Gates

- Before starting: Verify iteration exists in task file
- Before completing: Verify all subjects have ✅ RESOLVED status
- Before marking iteration READY: Verify no pending pre-tasks (or mark PENDING if pre-tasks exist)
- After Type B resolution: Verify PLAN.md updated correctly

## References

- **Subject Resolution Types**: [RESOLUTION_TYPES.md](RESOLUTION_TYPES.md) - Detailed guide on A/B/C/D types
- **PLAN.md Updates**: [PLAN_UPDATES.md](PLAN_UPDATES.md) - How to update architecture documentation
- **Brainstorming Pattern**: .flow/framework/DEVELOPMENT_FRAMEWORK.md lines 1167-1797
- **Framework Reference**: .flow/framework/DEVELOPMENT_FRAMEWORK.md lines 1-353