3.6 KiB
Session Notes: Assign Archetypes to Tasks - UI System
Executive Summary
Implemented a complete UI system for assigning agent archetypes to tasks via both graph nodes and sidebar panel.
Collaboration Journey
1. Initial Discovery (User Question: "What did we do so far?")
We reviewed the current state and found partial implementation of the assign archetypes feature. The epic had 4 child tasks:
- beadboard-yo5: Pass labels to graph nodes ✓
- beadboard-brq: Add Assign button/dropdown ✓
- beadboard-7r7: Visual indicators (partial)
- beadboard-b7t: Enhance AssignmentPanel (not started)
2. Bug Discovery: Unassign Not Working
User reported: "I see 'unassigned ' but it's still showing as a tag"
Root Cause: DELETE API existed but frontend was calling POST for unassign.
Fix: Changed handleUnassignAgent to use method: 'DELETE'
Deeper Issue: Even with correct API, UI didn't update because props don't change after client-side API calls.
Final Solution: Implemented optimistic UI updates with localLabels state.
3. Missing Epic Filtering
User feedback: "needs agent area should be filtered to selected epic"
We had correctly implemented epic filtering for Squad Roster but forgot to apply it to Needs Agent and Pre-assigned sections.
4. Honest Mistakes Made
- Initially used POST for unassign instead of DELETE
- Forgot epicId filter on new sections (caught by user)
- First implementation didn't consider optimistic updates
Technical Decisions
Why Optimistic Updates?
- Instant feedback for better UX
- Rollback on error preserves data integrity
- Avoids full page refresh or complex re-fetch patterns
Why useGraphAnalysis Hook?
- Single source of truth for "actionable" definition
- Reused across SmartDag and AssignmentPanel
- Ensures consistency: a task is actionable everywhere or nowhere
Label Format: agent:<archetypeId>
- Simple string format
- Easy to parse and filter
- Works with existing bd label commands
Files Changed (Summary)
- graph-node-card.tsx: Assign UI + optimistic updates
- assignment-panel.tsx: Three-section sidebar
- workflow-graph.tsx: Pass labels to nodes
- smart-dag.tsx: Main view with assign mode
- unified-shell.tsx: Wire up sidebar panel
- use-graph-analysis.ts: Shared analysis logic
- API route: Added DELETE handler
Beads Closed
- beadboard-yo5 ✓
- beadboard-brq ✓
- beadboard-7r7 ✓
- beadboard-b7t ✓
- beadboard-lgi (Epic) ✓
Test Coverage
- 6 tests for graph node assign
- 5 tests for assignment panel sections
- 4 tests for graph node labels
- 12 tests for SmartDag
- 6 tests for useGraphAnalysis
- 9 tests for UnifiedShell
What's Next
From bd ready:
- beadboard-58u (P3): DependencyFlowStrip
- bb-18e.1 (P2): Cycle warning card
- bb-18e.2 (P1): Plain-English edge labels
Post-Session Bug Fix
SSE Overwrite Bug
User discovered: "An archetype can only exist on one task at a time - when I try to make the next task have the same arch, it deleted the one I added."
Root Cause
The SSE subscription refreshes data whenever any change happens. This created a race condition:
- User assigns archetype -> optimistic update
- SSE fires -> fetches server data (without new label yet)
- useEffect overwrites localLabels with stale server data
- Label disappears
Solution
Track pending optimistic labels in useRef Set, merge with server data during sync. This prevents SSE overwrites of in-flight operations.
Test Coverage
Added 10 new tests in graph-node-labels-optimistic.test.tsx to ensure this bug doesn't regress.
Commit
bd3b3da - fix(graph): prevent SSE overwrites of optimistic label updates