WhiteBoard Party #117
Updated by Sam Pearson 11 days ago
# Design vs Implementation Gap Analysis ## This Writeup tracks alignment between design documentation and current implementation. ===== Summary ===== | Entity Group | Alignment | Effort to Fix | |--------------|-----------|---------------| |--------------|-----------|--------| | Commitments, Timeframes, Checkins | ~95% | Minor | | Tags and Principles | ~90% | Minor | | Calendars, Routines, Sessions | ~85% | Small | | Tasks and Projects | ~70% | Medium | | Reports | ~20% | Large | ## Tasks ===== Commitments, Timeframes, and Projects Checkins ===== **Alignment: ~70%** **Status: ~95% aligned** Core functionality is fully implemented and matches design. ==== Gaps ==== | Design | Implementation Current State | Gap Fix | |--------|----------------|-----| |--------|---------------|-----| | `status` field (open, waiting, deferred, declined, stale) Checkin target_types include report, tag, principle | Not implemented Service only validates task, project, routine, session | Need to add status field to both models Expand ALLOWED_TARGET_TYPES in CheckinService | ===== Tags and Principles ===== **Status: ~90% aligned** Core CRUD and attach/detach functionality fully implemented. ==== Gaps ==== | Design | Current State | Fix | |--------|---------------|-----| | `active` boolean on Tasks Calendars are taggable | Only Projects have it Calendar model lacks TaggableMixin | Need Add mixin to add active to Task Calendar model | | `completed_at` auto-set on completion Calendars are principled | Unknown Calendar model lacks PrincipledMixin | May need service logic Add mixin to Calendar model | | Project completion blocks if incomplete subtasks Sessions are principled | Unknown Session model lacks PrincipledMixin | May need service logic Add mixin to RoutineSession model | ## ===== Calendars, Routines, and Sessions ===== **Alignment: ~85%** **Status: ~85% aligned** Core entity structure is solid. Missing some behavioral features. ==== Gaps ==== | Design | Implementation Current State | Gap Fix | |--------|----------------|-----| |--------|---------------|-----| | Calendars taggable/principled | No mixins on Calendar model | Need to add TaggableMixin and Add TaggableMixin, PrincipledMixin | | Sessions principled taggable/principled | Only has TaggableMixin | Need to add Add PrincipledMixin | | Session `status` status field (scheduled, completed, skipped, cancelled) | Not implemented | Need Add status column to add status field RoutineSession | | Session auto-creates Commitment | Unknown | May need Verify or add to session generation service logic | | Routine deactivation deletes offers to delete future sessions (optional) | Unknown | May need Verify or add to routine service logic | ## Commitments, Timeframes, ===== Tasks and Checkins Projects ===== **Alignment: ~95%** **Status: ~70% aligned** Basic CRUD works. Missing status system and some behavioral logic. ==== Gaps ==== | Design | Implementation Current State | Gap Fix | |--------|----------------|-----| |--------|---------------|-----| | Core functionality Task status field (open, waiting, deferred, declined, stale) | Fully Not implemented | — Add status column to Task model | | Checkin target_types include report/tag/principle Task active boolean | Service only validates task/project/routine/session Not implemented | Need Add active column to expand ALLOWED_TARGET_TYPES Task model | ## Tags and Principles **Alignment: ~90%** | Design | Implementation | Gap | |--------|----------------|-----| | Core CRUD + attach/detach Project status field | Fully Not implemented | — Add status column to Project model | | Calendars taggable/principled completed_at auto-set on completion | Calendar model lacks mixins Unknown | Need Verify or add to add mixins service layer | | Sessions principled Project completion blocked by incomplete subtasks | Session model lacks PrincipledMixin Unknown | Need Verify or add to add mixin service layer | ## ===== Reports ===== **Alignment: ~20%** **Status: ~20% aligned** Current implementation uses five separate hardcoded models. Design calls for a flexible, template-based system. ==== Gaps ==== | Design | Implementation Current State | Gap Fix | |--------|----------------|-----| |--------|---------------|-----| | Single Report model linked to Timeframe | Five separate models (DayReport, WeekReport, etc.) | Full redesign needed Consolidate into single Report model | | Report links to Timeframe (1:1) | Reports store own date fields | Add timeframe_id FK, remove date columns | | Unified text fields (plan, reason, pre_notes, post_notes) | Inconsistent fields across report types | Standardize fields | | MetricType (user-defined metrics) | Not implemented | New Create new model needed | | MetricValue (metric measurements per report) (per-report measurements) | Not implemented Hardcoded columns (sleep_hours, etc.) | New model needed Create new model, migrate data | | ReportTemplate (metric configurations per timeframe kind) | Not implemented | New Create new model needed | | ReportTemplateMetric (join table) | Not implemented | New Create new model needed | | Unified text fields (plan, reason, pre_notes, post_notes) | Inconsistent fields across report types | Consolidate into unified structure | | 1:1 Timeframe link via timeframe_id | Reports store their own date fields | Need to add timeframe_id FK | | Remove gratitudes field | Currently Exists on BaseReport | Remove field column | ==== Migration Notes ==== * This is a significant refactor requiring data migration * Existing report data will need to be mapped to new structure * Consider: migrate existing column values into MetricValues, or start fresh? ## Implementation Priority ===== Prioritized Backlog ===== ### Priority 1: Minor fixes ==== Quick Wins (Minor effort) ==== * 1. Expand checkin target types target_types to include report, tag, principle * 2. Add TaggableMixin and PrincipledMixin to Calendar model * 3. Add PrincipledMixin to Session RoutineSession model ### Priority 2: ==== Small additions Effort ==== * 4. Add `status` status field to Session RoutineSession model * Implement 5. Verify/implement session auto-creates commitment logic on generation * Implement 6. Verify/implement routine deactivation option to delete future sessions ### Priority 3: ==== Medium changes Effort ==== * 7. Add `status` status field to Task and Project models * 8. Add `active` active field to Task model * 9. Implement `completed_at` completed_at auto-set logic in task/project services * 10. Implement project completion validation (block if incomplete subtasks) ### Priority 4: ==== Large redesign Effort ==== * Design and implement new Report model with timeframe_id FK * Design and implement 11. Reports redesign: a. Create MetricType model * Design and implement b. Create MetricValue model * Design and implement c. Create ReportTemplate model * Design and implement d. Create ReportTemplateMetric join table * model e. Create unified Report model with timeframe_id f. Migrate or deprecate existing report data (if needed) or start fresh * models g. Update report services and API routes