396 lines
14 KiB
Markdown
396 lines
14 KiB
Markdown
# Epic 2 Retrospective: Player Notifications & Director's Board
|
|
|
|
**Date:** 2026-05-23
|
|
**Epic:** 2 - Player Notifications & Director's Board
|
|
**Status:** Completed
|
|
**Facilitator:** Amelia (Developer)
|
|
**Participants:** Morr (Project Lead), Alice (Product Owner), Charlie (Senior Dev), Dana (QA Engineer), Elena (Junior Dev)
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
Epic 2 delivered all 3 stories on time with 100% completion rate. The epic extended the core visibility control system with player-facing notifications and a comprehensive GM control interface. Test coverage improved significantly with 105 new tests added. The team successfully resolved all deferred technical debt from Epic 1 while maintaining architectural consistency.
|
|
|
|
**Epic Metrics:**
|
|
- Stories Completed: 3/3 (100%)
|
|
- New Tests Added: 105
|
|
- Total Tests Passing: 412
|
|
- Production Incidents: 0
|
|
- Critical Blockers: 0
|
|
|
|
---
|
|
|
|
## Epic Overview
|
|
|
|
### Stories Delivered
|
|
|
|
| Story | Title | Status | Tests Added | Key Outcomes |
|
|
|-------|-------|--------|--------------|--------------|
|
|
| 2.1 | NotificationBus & Notification Verbosity | Done | 28 | Coalescing notifications, verbosity settings, i18n integration |
|
|
| 2.2 | Director's Board — Core Layout & Participant Toggle | Done | 48 | ApplicationV2 implementation, per-participant toggle, keyboard nav |
|
|
| 2.3 | Director's Board — Bulk Actions, Spotlight & Keyboard Shortcuts | Done | 29 | Show/Hide All, Spotlight, Undo, keyboard shortcuts, sidebar button |
|
|
|
|
### Functional Requirements Covered
|
|
|
|
- FR-9: Director's Board open via sidebar button + keyboard shortcut
|
|
- FR-10: Director's Board full Visibility Matrix seating-chart layout
|
|
- FR-11: Per-participant toggle from Director's Board
|
|
- FR-12: Bulk Show All / Hide All with one-step Undo
|
|
- FR-13: Spotlight action with pre-spotlight snapshot and Restore
|
|
- FR-14: Full keyboard shortcuts for Director's Board actions
|
|
- FR-20: Toast notification to all participants on GM visibility change
|
|
- FR-21: Notification verbosity configuration per user
|
|
|
|
---
|
|
|
|
## What Went Well
|
|
|
|
### 🎯 Major Successes
|
|
|
|
1. **Proactive Technical Debt Resolution**
|
|
- Story 2.1 proactively addressed all 4 deferred items from Epic 1 retro
|
|
- Memory leak fixes in ScryingPoolController
|
|
- Listener cleanup in both ScryingPoolController and VisibilityManager
|
|
- Echo revision validation
|
|
- **Impact:** Prevented debt accumulation, maintained code health
|
|
|
|
2. **Architecture Decisions Proved Sound**
|
|
- Import boundary enforcement (ESLint `import/no-restricted-paths`) caught violations early
|
|
- Side-effect-free constructors enabled reliable testing
|
|
- Dependency injection pattern allowed easy mocking in tests
|
|
- **Impact:** High testability, maintainable codebase
|
|
|
|
3. **TDD Discipline Maintained**
|
|
- All stories followed strict TDD red-green cycles
|
|
- 105 new tests with comprehensive coverage
|
|
- Tests caught edge cases before production
|
|
- **Impact:** High confidence in code quality
|
|
|
|
4. **Complete i18n Coverage**
|
|
- All user-facing strings properly localized
|
|
- Consistent i18n key naming convention
|
|
- Fallback patterns for edge cases
|
|
- **Impact:** Ready for localization, professional polish
|
|
|
|
5. **Accessibility Built-In**
|
|
- All interactive elements have ARIA labels
|
|
- Full keyboard navigation support
|
|
- Focus management in dialogs and popovers
|
|
- **Impact:** WCAG AA compliant, usable by all players
|
|
|
|
6. **Cross-Browser/Environment Compatibility**
|
|
- Conditional ApplicationV2 pattern for test environment
|
|
- Safe optional chaining for FoundryVTT APIs
|
|
- Graceful degradation when features unavailable
|
|
- **Impact:** Reliable across different environments
|
|
|
|
---
|
|
|
|
## Challenges & Growth Areas
|
|
|
|
### ⚠️ Key Challenges
|
|
|
|
1. **Cross-Story Interface Mismatches**
|
|
- **Issue:** Story 2.2 implemented `_dispatchToggle()` with object parameter `{userId, targetState}` but ScryingPoolController.action() expects positional args `(source, participantId, targetState, opId, baseRevision)`
|
|
- **Resolution:** Fixed in Story 2.3 Task 1, but cost development time
|
|
- **Root Cause:** Insufficient integration testing between stories
|
|
- **Pattern:** 1 story had cross-story interface issues
|
|
|
|
2. **Event Listener Lifecycle Management**
|
|
- **Issue:** Memory leak fixes were deferred from Epic 1 and had to be addressed in Epic 2
|
|
- **Manifestations:**
|
|
- `_revisions` Map leak in ScryingPoolController
|
|
- Missing `teardown()` methods in multiple classes
|
|
- DOM listener cleanup on close/reopen cycles
|
|
- **Resolution:** Story 2.1 Tasks 4.1-4.3, Story 2.3 various fixes
|
|
- **Pattern:** 3 out of 3 stories had to add cleanup/teardown logic
|
|
|
|
3. **Race Conditions in Bulk Operations**
|
|
- **Issue:** Story 2.3 bulk actions (showAll, hideAll, spotlight) had race conditions in state capture
|
|
- **Manifestations:** Inconsistent snapshots when user states changed mid-operation
|
|
- **Resolution:** Atomic state capture before iteration
|
|
- **Pattern:** All bulk operations now capture complete state snapshot first
|
|
|
|
4. **Sidebar Button API Uncertainty**
|
|
- **Issue:** FoundryVTT v14 `getSceneControlButtons` hook API was uncertain
|
|
- **Resolution:** Implemented with safe optional chaining, added fallback CTA button in ScryingPoolStrip
|
|
- **Pattern:** Defensive coding for uncertain APIs
|
|
|
|
---
|
|
|
|
## Patterns Identified
|
|
|
|
### ✅ Positive Patterns (Repeat These)
|
|
|
|
1. **Deferred Debt Folding**
|
|
- Story 2.1 proactively addressed Epic 1 deferred items
|
|
- Pattern: Address deferred work early in the next epic
|
|
- **Recommendation:** Continue this pattern for Epic 3
|
|
|
|
2. **Utility Function Extraction**
|
|
- Story 2.3 created `src/utils/boardUtils.js` for shared context building
|
|
- Pattern: Extract shared logic into utility modules
|
|
- **Recommendation:** Apply this pattern more aggressively
|
|
|
|
3. **State Machine Patterns**
|
|
- Undo/Restore state machine with `_undoSnapshot` and `_spotlightSnapshot`
|
|
- Pattern: Clear state transitions with mutual exclusion
|
|
- **Recommendation:** Document this pattern for reuse
|
|
|
|
4. **Bulk Operation Patterns**
|
|
- Atomic state capture before iteration
|
|
- Ghost state exclusion checks
|
|
- Pending operation guards
|
|
- Pattern: Robust bulk operation handling
|
|
- **Recommendation:** Create reusable bulk operation helper
|
|
|
|
### ⚠️ Negative Patterns (Avoid These)
|
|
|
|
1. **Insufficient Cross-Story Testing**
|
|
- Interface mismatches between stories
|
|
- Pattern: Test story interfaces against their dependencies
|
|
- **Recommendation:** Add integration test step to story creation checklist
|
|
|
|
2. **Late Lifecycle Management**
|
|
- `teardown()` methods added as fixes rather than designed in
|
|
- Pattern: Event cleanup as afterthought
|
|
- **Recommendation:** Include teardown in initial class design template
|
|
|
|
---
|
|
|
|
## Previous Retro Follow-Through (Epic 1)
|
|
|
|
### Epic 1 Action Items Status
|
|
|
|
| Action Item | Status | Evidence |
|
|
|-------------|--------|----------|
|
|
| Memory leak fixes | ✅ Completed | Story 2.1 Tasks 4.1-4.4 |
|
|
| Listener cleanup | ✅ Completed | Story 2.1, refined in Story 2.3 |
|
|
| Test coverage for edge cases | ✅ Completed | 105 new tests in Epic 2 |
|
|
| Documentation improvements | ⚠️ Partial | Dev notes good, module-level docs need work |
|
|
|
|
**Assessment:** 3/4 action items completed (75%). The one partial item (documentation) carries forward.
|
|
|
|
### Lessons Applied from Epic 1
|
|
|
|
✅ **Import Boundaries** - Strictly enforced via ESLint, no violations in Epic 2
|
|
✅ **Side-Effect-Free Constructors** - All new classes follow this pattern
|
|
✅ **TDD Approach** - Maintained throughout Epic 2
|
|
✅ **Dependency Injection** - Enabled comprehensive testing
|
|
⚠️ **Documentation** - Story-level documentation excellent, module-level could improve
|
|
|
|
### Lessons NOT Applied from Epic 1
|
|
|
|
❌ **None identified** - All Epic 1 lessons were successfully applied
|
|
|
|
---
|
|
|
|
## Next Epic Preview: Epic 3 - Scene-Aware Camera Automation
|
|
|
|
### Epic 3 Overview
|
|
|
|
| Story | Title | Status |
|
|
|-------|-------|--------|
|
|
| 3.1 | Save & Load Scene Presets | Backlog |
|
|
| 3.2 | Scene Auto-Apply & ConfirmationBar | Backlog |
|
|
| 3.3 | Preset Import & Export | Backlog |
|
|
|
|
### Dependencies on Epic 2
|
|
|
|
1. **Director's Board UI Patterns**
|
|
- ApplicationV2 usage patterns
|
|
- Event delegation on root element
|
|
- Position persistence via user flags
|
|
- **Status:** ✅ Available and tested
|
|
|
|
2. **NotificationBus Integration**
|
|
- Toast notification infrastructure
|
|
- Coalescing patterns
|
|
- Verbosity settings
|
|
- **Status:** ✅ Available and tested
|
|
|
|
3. **Visibility Matrix Persistence**
|
|
- World setting storage
|
|
- StateStore change events
|
|
- **Status:** ✅ Available from Epic 1
|
|
|
|
4. **Bulk Operation Patterns**
|
|
- Atomic state capture
|
|
- Ghost state handling
|
|
- Pending operation guards
|
|
- **Status:** ✅ Available from Story 2.3
|
|
|
|
### Technical Prerequisites
|
|
|
|
✅ **All prerequisites met** - Epic 2 delivered all required infrastructure
|
|
|
|
### Open Questions (from Architecture)
|
|
|
|
1. **OQ-5: `updateScene` hook timing**
|
|
- Need to verify FoundryVTT v14 hook behavior
|
|
- Risk: Auto-apply may fire at wrong time in scene transition
|
|
- **Action:** Spike before Story 3.2
|
|
|
|
2. **OQ-6: Partial vs unconditional preset application**
|
|
- Decision needed: Apply presets to offline participants?
|
|
- Risk: State inconsistency if participants reconnect
|
|
- **Action:** Architectural decision before Story 3.2
|
|
|
|
### Preparation Needed
|
|
|
|
| Task | Owner | Priority | Estimated Effort | Deadline |
|
|
|------|-------|----------|------------------|----------|
|
|
| Spike `updateScene` hook timing | Charlie | High | 1 day | Before 3.2 |
|
|
| Decide partial preset behavior | Morr + Alice | High | 0.5 day | Before 3.2 |
|
|
| Update architecture.md with Epic 2 patterns | Amelia | Medium | 0.5 day | After retro |
|
|
| Create integration test checklist | Dana | Medium | 0.5 day | Before 3.1 |
|
|
|
|
---
|
|
|
|
## Action Items
|
|
|
|
### Process Improvements
|
|
|
|
1. **Add cross-story integration tests to story creation checklist**
|
|
- **Owner:** Dana (QA Engineer)
|
|
- **Deadline:** Before Story 3.1 starts
|
|
- **Success Criteria:** Checklist item added to `deferred-work.md` or story template
|
|
- **Category:** Process
|
|
|
|
2. **Document event lifecycle patterns in architecture.md**
|
|
- **Owner:** Amelia (Developer)
|
|
- **Deadline:** After Epic 2 retrospective
|
|
- **Success Criteria:** `teardown()` pattern documented, examples provided
|
|
- **Category:** Documentation
|
|
|
|
3. **Create reusable bulk operation helper**
|
|
- **Owner:** Charlie (Senior Dev)
|
|
- **Deadline:** Before Story 3.1 starts
|
|
- **Success Criteria:** Helper module created and tested, used in Story 3.2
|
|
- **Category:** Technical
|
|
|
|
### Technical Debt
|
|
|
|
*No critical debt items - all Epic 1 deferred items resolved in Epic 2*
|
|
|
|
### Documentation
|
|
|
|
1. **Update architecture.md with Epic 2 patterns**
|
|
- **Owner:** Amelia (Developer)
|
|
- **Deadline:** After Epic 2 retrospective
|
|
- **Success Criteria:** New patterns documented: NotificationBus coalescing, Director's Board architecture, bulk operation patterns
|
|
|
|
### Team Agreements
|
|
|
|
- All stories must include integration verification step in their checklist
|
|
- Event listeners must have corresponding `teardown()` methods
|
|
- Cross-story interface changes require peer review from adjacent story authors
|
|
- Bulk operations must capture atomic state snapshots before iteration
|
|
|
|
---
|
|
|
|
## Critical Path
|
|
|
|
### Blockers to Resolve Before Epic 3
|
|
|
|
1. **OQ-5: `updateScene` hook timing spike**
|
|
- **Owner:** Charlie (Senior Dev)
|
|
- **Must complete by:** Before Story 3.2 starts
|
|
- **Dependencies:** None
|
|
|
|
2. **OQ-6: Partial preset application decision**
|
|
- **Owner:** Morr (Project Lead) + Alice (Product Owner)
|
|
- **Must complete by:** Before Story 3.2 starts
|
|
- **Dependencies:** None
|
|
|
|
### Preparation Sprint Tasks
|
|
|
|
- [ ] Spike `updateScene` hook timing
|
|
- [ ] Decide partial vs unconditional preset application
|
|
- [ ] Update architecture.md with Epic 2 patterns
|
|
- [ ] Create integration test checklist
|
|
- [ ] Create reusable bulk operation helper
|
|
|
|
**Total Estimated Effort:** 2-3 days
|
|
|
|
---
|
|
|
|
## Readiness Assessment
|
|
|
|
### Epic 2 Readiness
|
|
|
|
| Area | Status | Notes |
|
|
|------|--------|-------|
|
|
| Testing & Quality | ✅ Complete | 412 tests passing, all ACs verified |
|
|
| Deployment | ⏳ Pending | Module not yet deployed to FoundryVTT |
|
|
| Stakeholder Acceptance | ✅ N/A | Internal module for personal use |
|
|
| Technical Health | ✅ Stable | No critical issues, good architecture |
|
|
| Unresolved Blockers | ✅ None | All stories complete and tested |
|
|
|
|
**Overall:** Epic 2 is **complete and production-ready** from a technical perspective. Deployment timing is at Morr's discretion.
|
|
|
|
---
|
|
|
|
## Files Modified in Epic 2
|
|
|
|
### New Files
|
|
- `src/notifications/NotificationBus.js`
|
|
- `tests/unit/notifications/NotificationBus.test.js`
|
|
- `src/ui/gm/DirectorsBoard.js`
|
|
- `tests/unit/ui/gm/DirectorsBoard.test.js`
|
|
- `src/ui/shared/ParticipantCard.js`
|
|
- `tests/unit/ui/shared/ParticipantCard.test.js`
|
|
- `src/utils/boardUtils.js`
|
|
|
|
### Modified Files
|
|
- `module.js` (settings, keybindings, wiring)
|
|
- `lang/en.json` (i18n keys)
|
|
- `templates/directors-board.hbs`
|
|
- `templates/participant-card.hbs`
|
|
- `styles/components/_directors-board.less`
|
|
- `styles/components/_participant-card.less`
|
|
- `styles/components/_notification.less`
|
|
- `src/core/ScryingPoolController.js` (cleanup methods)
|
|
- `src/core/VisibilityManager.js` (cleanup methods)
|
|
|
|
---
|
|
|
|
## Metrics Summary
|
|
|
|
| Metric | Value | Notes |
|
|
|--------|-------|-------|
|
|
| Stories Completed | 3/3 | 100% |
|
|
| New Tests | 105 | +29 in Story 2.3 alone |
|
|
| Total Tests | 412 | All passing |
|
|
| New Files | 7 | 3 source, 4 test |
|
|
| Modified Files | 11 | Across core, ui, styles, templates |
|
|
| LOC Added | ~1,500 | Estimated |
|
|
| Production Incidents | 0 | |
|
|
| Code Review Iterations | Minimal | Most stories passed first review |
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
Epic 2 was a **successful delivery** that extended the module's core functionality with player notifications and GM control tools. The team maintained architectural discipline, delivered comprehensive test coverage, and proactively resolved technical debt from Epic 1.
|
|
|
|
**Key Achievements:**
|
|
- Complete notification system with coalescing and verbosity control
|
|
- Full-featured Director's Board with keyboard accessibility
|
|
- Bulk operations with undo capability
|
|
- Maintained 100% architectural compliance
|
|
|
|
**Areas for Improvement:**
|
|
- Cross-story integration testing
|
|
- Event lifecycle pattern standardization
|
|
- Earlier detection of interface mismatches
|
|
|
|
**Readiness for Epic 3:** High - All prerequisites met, team experienced, patterns established.
|
|
|
|
---
|
|
|
|
**Next Retrospective:** Epic 3 (after all stories complete)
|
|
**Document Owner:** Morr (Project Lead)
|
|
**Last Updated:** 2026-05-23
|