--- sprint_id: sprint_4 milestone: M1 status: not_started created_date: 2025-11-05 start_date: 2025-11-06 target_end_date: 2025-11-20 --- # Sprint 4: Story Feature Implementation - UX-Driven Development **Milestone**: M1 - Core Project Module (User Experience Enhancement) **Goal**: Implement Story detail page and enhanced Story creation workflows based on comprehensive UX design specifications to provide users with a seamless Epic → Story → Task experience. ## Sprint Context **Background**: Following the completion of M1 core backend features (Sprint 1-2) and frontend quality improvements (Sprint 3), UX team delivered comprehensive Story management design specifications on 2025-11-05. The design focuses on consistency with existing Epic pages while introducing innovative Quick Add and enhanced Kanban workflows. **Current Problem**: 1. **Story detail page does not exist** - Clicking Story cards leads to 404 error 2. **No Story creation from Kanban** - Users cannot create Stories directly from Epic cards 3. **Limited Story form** - Missing acceptance criteria, assignee, and tags fields **UX Design Documents**: - Complete specification: `docs/designs/STORY_UX_UI_DESIGN.md` (1,409 lines) - Summary: `docs/designs/STORY_DESIGN_SUMMARY.md` (488 lines) - Design phase: 5 phases over 5 weeks ## Diagnosis Report ### Backend Status ✅ **Story API**: 100% Complete - Controller: `StoriesController.cs` with 6 endpoints - CQRS: Full Create/Update/Delete/Assign commands - Queries: GetStoryById, GetStoriesByEpicId, GetStoriesByProjectId - Multi-tenant: Security verified (Day 15-16) - Authorization: `[Authorize]` attribute present **Endpoints Available**: ``` GET /api/v1/stories/{id} - Get Story by ID GET /api/v1/epics/{epicId}/stories - List Epic Stories GET /api/v1/projects/{projectId}/stories - List Project Stories POST /api/v1/stories - Create Story POST /api/v1/epics/{epicId}/stories - Create Story (nested) PUT /api/v1/stories/{id} - Update Story DELETE /api/v1/stories/{id} - Delete Story PUT /api/v1/stories/{id}/assign - Assign Story ``` ### Frontend Status ⚠️ (Partial) **✅ Already Implemented**: 1. **Story API Client** (`lib/api/pm.ts`) - All CRUD operations: list, get, create, update, delete - Status change and assign methods - Fully typed with TypeScript 2. **Story Hooks** (`lib/hooks/use-stories.ts`) - `useStories(epicId)` - List stories by epic - `useProjectStories(projectId)` - List all project stories - `useStory(id)` - Get single story - `useCreateStory()`, `useUpdateStory()`, `useDeleteStory()` - `useChangeStoryStatus()`, `useAssignStory()` - Optimistic updates with React Query 3. **Story Form Component** (`components/projects/story-form.tsx`) - Create and Edit modes - Fields: epicId, title, description, priority, estimatedHours - Form validation with Zod - Parent Epic selector - **Missing**: Acceptance criteria, assignee selector, tags 4. **Story Display in Epic Detail** (`app/(dashboard)/epics/[id]/page.tsx`) - Stories list in Epic detail page - Story cards with status and priority badges - Edit and Delete buttons - Create Story dialog - **Working**: Story creation and editing from Epic page 5. **Story Types** (`types/project.ts`) - Full Story interface defined - CreateStoryDto and UpdateStoryDto types - All fields properly typed **❌ Missing Implementation**: 1. **Story Detail Page** - `app/(dashboard)/stories/[id]/page.tsx` does not exist - No route configured - No Story detail UI - Cannot view Story details, Tasks, or Activity 2. **Task Management in Story** - No Task UI components - No Task list component - No Task creation from Story - No Task status updates 3. **Story Quick Add** - No inline creation flow - Only full dialog form exists - Missing rapid Story creation workflow 4. **Kanban Story Creation** - No Epic card Story creation - Cannot add Stories from Kanban - Missing contextual creation 5. **Activity Timeline** - No change history component - Missing audit log display - No real-time activity feed 6. **Enhanced Story Form** - Missing UX fields - No acceptance criteria field - No assignee selector - No tags/labels support ### Gap Analysis Summary | Feature | Backend | Frontend | Gap | |---------|---------|----------|-----| | Story CRUD | ✅ 100% | ✅ 100% | None | | Story Detail Page | ✅ API Ready | ❌ Missing | **CRITICAL** | | Task Management | ✅ API Ready | ❌ Missing | **HIGH** | | Quick Add Story | ✅ API Ready | ❌ Missing | **MEDIUM** | | Kanban Story Create | ✅ API Ready | ❌ Missing | **MEDIUM** | | Activity Timeline | ⚠️ Partial | ❌ Missing | **LOW** | | Acceptance Criteria | ❌ No field | ❌ Missing | **MEDIUM** | | Assignee Selector | ✅ API Ready | ❌ Missing | **MEDIUM** | **Priority Assessment**: - **P0 (Critical)**: Story Detail Page + Task List - Users cannot access Stories - **P1 (High)**: Enhanced Story Form + Quick Add - Incomplete user experience - **P2 (Medium)**: Kanban enhancements + Activity Timeline - Nice to have features ## Sprint Objectives 1. **Story Detail Page** - Enable users to view and manage Story details with full Task support 2. **Enhanced Story Form** - Add missing UX fields (acceptance criteria, assignee, tags) 3. **Quick Add Workflow** - Implement rapid Story creation inline form 4. **Task Management** - Build Task list, creation, and status update UI 5. **Kanban Enhancement** - Add contextual Story creation from Epic cards (optional) ## Implementation Strategy ### Phase-Based Approach (5 Phases from UX Design) **Our Sprint**: Focus on **Phase 1 + Phase 2** (Weeks 1-2) - Phase 1: Core Story Detail (Week 1) - P0 Critical - Phase 2: Story Creation & Editing (Week 2) - P1 High - Phase 3-5: Deferred to future sprints **Rationale**: - Deliver immediate value (fix Story page 404 error) - Iterative approach reduces risk - Align with UX design phasing - Team can gather feedback before Phase 3-5 ### Reuse Epic Pattern Strategy **Key Insight**: Story detail page is 85% similar to Epic detail page - Epic page: `app/(dashboard)/epics/[id]/page.tsx` (534 lines) - Epic form: `components/epics/epic-form.tsx` - Epic hooks: `lib/hooks/use-epics.ts` **Reuse Plan**: 1. Copy Epic detail page structure → Story detail page 2. Adapt Epic form enhancements → Story form 3. Reuse Epic card patterns → Story card component 4. Copy Epic status/priority logic → Story metadata **Benefits**: - **Consistency**: Visual and interaction consistency - **Speed**: 50-60% faster development (reuse code) - **Quality**: Proven patterns, fewer bugs - **Maintenance**: Shared components easier to maintain ## Stories - [ ] [story_1](sprint_4_story_1.md) - Story Detail Page Foundation - `not_started` - **P0 Critical** - 3 days - [ ] [story_2](sprint_4_story_2.md) - Task Management in Story Detail - `not_started` - **P0 Critical** - 2 days - [ ] [story_3](sprint_4_story_3.md) - Enhanced Story Form - `not_started` - **P1 High** - 2 days - [ ] [story_4](sprint_4_story_4.md) - Quick Add Story Workflow - `not_started` - **P1 High** - 2 days - [ ] [story_5](sprint_4_story_5.md) - Story Card Component - `not_started` - **P2 Medium** - 1 day - [ ] [story_6](sprint_4_story_6.md) - Kanban Story Creation Enhancement - `not_started` - **P2 Medium** - 2 days (Optional) **Progress**: 0/6 stories, 0/30+ tasks completed (0%) ## Sprint Scope Summary ### Story 1: Story Detail Page Foundation ⭐ CRITICAL **Estimated**: 3 days (Day 1-3) **Owner**: Frontend Team **Dependencies**: None (API ready) **Scope**: - Create `app/(dashboard)/stories/[id]/page.tsx` route - Implement two-column layout (main content + metadata sidebar) - Display Story header (title, status, priority badges) - Show Story description and metadata (assignee, time, dates) - Display parent Epic card in sidebar - Add Edit and Delete actions - Error handling (404, network errors) - Loading states with skeleton loaders **Acceptance Criteria**: - Clicking Story card navigates to `/stories/{id}` page - Page displays all Story information - Layout matches Epic detail page consistency - Responsive design works on mobile/tablet/desktop - All actions (Edit, Delete) work correctly - Loading and error states display properly **Deliverables**: - Story detail page component - Story metadata sidebar component - Story header component - Route configuration --- ### Story 2: Task Management in Story Detail ⭐ CRITICAL **Estimated**: 2 days (Day 3-4) **Owner**: Frontend Team **Dependencies**: Story 1 (Story detail page must exist) **Scope**: - Create Task list component with expandable Task cards - Implement Task checkbox for quick status toggle - Add "Add Task" button and inline creation form - Display Task metadata (priority, assignee, estimated hours) - Implement Task filtering (status, priority, assignee) - Add Task sorting options - Show Task count badge in header - Empty state when no Tasks exist **Acceptance Criteria**: - Tasks display in Story detail page - Users can create new Tasks inline - Clicking Task checkbox updates status - Task filters and sorting work correctly - Task count updates in real-time - Empty state shows helpful guidance - Task creation form validates inputs **Deliverables**: - `components/projects/task-list.tsx` - `components/projects/task-card.tsx` - `components/projects/task-form.tsx` (inline variant) - Task hooks integration --- ### Story 3: Enhanced Story Form **Estimated**: 2 days (Day 5-6) **Owner**: Frontend Team **Dependencies**: None (independent enhancement) **Scope**: - Add Acceptance Criteria field (checkbox list) - Implement Assignee selector (searchable dropdown) - Add Tags/Labels field (multi-select) - Add Story Points field (optional) - Enhance form validation - Add form field descriptions - Improve form layout (two-column grid) - Add "Save Draft" functionality (optional) **Acceptance Criteria**: - Form includes all new fields - Assignee selector shows user list - Acceptance criteria can be added/removed dynamically - Tags support multi-select - Form validation works for all fields - Form saves correctly with new fields - Backward compatible with existing Stories **Deliverables**: - Enhanced `components/projects/story-form.tsx` - Assignee selector component - Acceptance criteria editor component - Tag selector component --- ### Story 4: Quick Add Story Workflow **Estimated**: 2 days (Day 7-8) **Owner**: Frontend Team **Dependencies**: Story 3 (enhanced form patterns) **Scope**: - Create inline Story form component (Quick Add variant) - Add "+ Quick Add" button at top of Stories list - Implement minimal form (title + priority only) - Add keyboard shortcut (Cmd/Ctrl + N) - Auto-reset form after creation - Add "Add & Create Tasks" button - Implement form animations - Show success toast notifications **Acceptance Criteria**: - Quick Add button appears in Epic detail Stories section - Inline form shows with minimal fields - Story creates on Enter key press - Form resets and stays open for batch creation - Keyboard shortcut works globally - "Add & Create Tasks" navigates to Story detail - Animations smooth and performant **Deliverables**: - `components/projects/quick-add-story.tsx` - Story form "quick mode" variant - Keyboard shortcut handler - Batch creation workflow --- ### Story 5: Story Card Component **Estimated**: 1 day (Day 9) **Owner**: Frontend Team **Dependencies**: Story 1, 2 (understand Story structure) **Scope**: - Create reusable Story card component - Implement three variants (list, kanban, compact) - Add visual states (hover, selected, dragging) - Show Story metadata badges - Add quick actions menu (Edit, Delete, Duplicate) - Implement card hover effects - Add Task count indicator - Support drag-and-drop preparation **Acceptance Criteria**: - Story card works in all three variants - Visual states display correctly - Quick actions appear on hover - Card shows all relevant metadata - Component is reusable across views - Performance optimized with React.memo - TypeScript types fully defined **Deliverables**: - `components/projects/story-card.tsx` - Story card Storybook stories (optional) - Card visual state tests --- ### Story 6: Kanban Story Creation Enhancement (Optional) **Estimated**: 2 days (Day 10-11) **Owner**: Frontend Team **Dependencies**: Story 1, 4 (Story detail + Quick Add patterns) **Status**: Optional (stretch goal) **Scope**: - Add "+ Add Story" button to Epic cards on hover - Implement inline Story form below Epic card - Context-bound Story creation (Epic pre-selected) - Add Story to correct Kanban column by status - Implement form slide-in animation - Add "Cancel" and outside-click close - Update Epic Story count in real-time **Acceptance Criteria**: - Hover Epic card shows "+ Add Story" action - Clicking opens inline Story form - Form creates Story under correct Epic - Story appears in appropriate Kanban column - Epic Story count updates immediately - Animation smooth and intuitive - Can cancel or close form easily **Deliverables**: - Enhanced Kanban Epic card component - Inline Story form integration - Kanban Story creation workflow - Real-time count updates --- ## Timeline **Week 1 (Nov 6-8)**: Core Story Detail - P0 Critical - Day 1-2: Story 1 - Story Detail Page Foundation (Tasks 1-4) - Day 3: Story 2 - Task Management (Tasks 1-3) **Week 2 (Nov 11-15)**: Enhanced Creation Workflows - P1 High - Day 4: Story 2 - Task Management Complete (Tasks 4-6) - Day 5-6: Story 3 - Enhanced Story Form (Tasks 1-6) - Day 7-8: Story 4 - Quick Add Workflow (Tasks 1-5) **Week 3 (Nov 18-20)**: Polish & Optional Features - P2 Medium - Day 9: Story 5 - Story Card Component (Tasks 1-4) - Day 10-11: Story 6 - Kanban Enhancement (Optional) ## Definition of Done - [ ] All P0 and P1 stories completed (Stories 1-4) - [ ] Story detail page accessible and fully functional - [ ] Users can create and manage Tasks within Stories - [ ] Enhanced Story form includes all UX-designed fields - [ ] Quick Add workflow enables rapid Story creation - [ ] All acceptance criteria met for completed stories - [ ] TypeScript types updated for new fields - [ ] No console errors or warnings - [ ] Manual testing passed on Chrome/Firefox/Edge - [ ] Mobile responsive design verified - [ ] Code reviewed and approved - [ ] Documentation updated ## Success Metrics ### User Experience Metrics - **Story Page Load Time**: < 1 second (per UX design target) - **Task Creation Time**: < 20 seconds (per UX design target) - **Quick Add Speed**: < 30 seconds (per UX design target) - **Navigation Clicks**: Epic → Task in < 3 clicks (per UX design) - **Error Rate**: < 5% (per UX design) ### Code Quality Metrics - **TypeScript Coverage**: 100% (no `any` types) - **Component Reusability**: >= 80% (reuse Epic patterns) - **Performance**: Lighthouse score >= 90 (per Sprint 3 standard) - **Accessibility**: WCAG 2.1 Level AA compliance (per UX design) ### Completion Metrics - **P0 Stories**: 2/2 completed (100%) - Story 1, 2 - **P1 Stories**: 2/2 completed (100%) - Story 3, 4 - **P2 Stories**: 1-2/2 completed (50-100%) - Story 5, 6 (optional) - **Overall Sprint**: 4/6 stories minimum (67%), 6/6 ideal (100%) ## Dependencies **Prerequisites**: - ✅ Sprint 1 completed (Frontend Integration) - ✅ Sprint 2 completed (M1 Backend Features) - ✅ Sprint 3 completed (Frontend Code Quality) - ✅ Story API 100% ready (StoriesController) - ✅ Task API 100% ready (TasksController) - ✅ UX design complete (STORY_UX_UI_DESIGN.md) **Technical Requirements**: - Next.js 15+ (already configured) - React 19+ (already configured) - React Query 4.0+ (already configured) - shadcn/ui components (already available) - @dnd-kit/core for drag-drop (already installed) ## Risks & Mitigation ### Risk Matrix | Risk ID | Description | Impact | Probability | Mitigation | Owner | |---------|-------------|--------|-------------|------------|-------| | RISK-001 | Task API not fully tested | High | Medium | Backend team verify Task endpoints Day 1 | Backend Lead | | RISK-002 | Story/Task relationship complexity | Medium | Medium | Reuse Epic/Story pattern, early testing | Frontend Dev | | RISK-003 | UX design phase 1-2 scope too large | High | Low | Focus on P0/P1 only, defer P2 | Product Manager | | RISK-004 | Acceptance criteria backend missing | Medium | High | Defer to future sprint if needed | Product Manager | | RISK-005 | Mobile responsive layout challenging | Medium | Medium | Test early and often on mobile devices | Frontend Dev | ## Related Documents ### UX Design Documents - [Story UX/UI Design Specification](../designs/STORY_UX_UI_DESIGN.md) - [Story Design Summary](../designs/STORY_DESIGN_SUMMARY.md) ### Planning Documents - [Product Roadmap](../../product.md) - [Sprint 1 Plan](sprint_1.md) - Frontend Integration - [Sprint 2 Plan](sprint_2.md) - M1 Backend Features - [Sprint 3 Plan](sprint_3.md) - Frontend Code Quality ### Technical References - [ProjectManagement Module](../../colaflow-api/src/ColaFlow.Modules.ProjectManagement/) - [Epic Detail Page](../../colaflow-web/app/(dashboard)/epics/[id]/page.tsx) - [Story Types](../../colaflow-web/types/project.ts) ## Notes ### Why This Sprint Matters **For Users**: - **Fix Critical Bug**: Story links currently lead to 404 errors - **Complete User Journey**: Epic → Story → Task navigation works end-to-end - **Faster Workflows**: Quick Add enables rapid Story creation - **Better Planning**: Acceptance criteria and assignee tracking **For Product**: - **UX Design Implementation**: Deliver on comprehensive UX specification - **Feature Parity**: Story management on par with Epic management - **User Satisfaction**: Fix reported user complaints about Story access - **M1 Enhancement**: Improve core project management experience **For Development**: - **Reuse Patterns**: 60% code reuse from Epic implementation - **Consistency**: Maintain design system consistency - **Quality**: Build on Sprint 3 quality improvements - **Foundation**: Enable future Phase 3-5 UX enhancements ### Story vs Epic Differences **Key Distinctions**: 1. **Stories have Tasks**, Epics have Stories 2. **Stories are smaller**, typically 1-2 week effort 3. **Stories have acceptance criteria**, Epics have high-level goals 4. **Stories assignable to individuals**, Epics to teams 5. **Stories more granular tracking**, Epics high-level progress **Implementation Impact**: - Story detail shows **Task list** (not Story list) - Story form includes **acceptance criteria** field - Story cards show **Task count** (not Story count) - Story hierarchy: Epic → **Story** → Task ### Backend API Verification Checklist Frontend team should verify these before Day 1: - [ ] GET /api/v1/stories/{id} returns Story with all fields - [ ] GET /api/v1/stories/{id}/tasks returns Task list - [ ] POST /api/v1/tasks with storyId creates Task correctly - [ ] PUT /api/v1/stories/{id} accepts all fields (title, description, priority, etc.) - [ ] DELETE /api/v1/stories/{id} cascades to Tasks - [ ] Multi-tenant isolation works (cannot access other tenant Stories) ### Future Enhancements (Post-Sprint 4) **Phase 3 (Future Sprint)**: Task Management Enhancements - Task drag-and-drop reordering - Task bulk operations (multi-select) - Task filters advanced (custom queries) - Task due dates and reminders **Phase 4 (Future Sprint)**: Kanban Full Integration - Story cards in Kanban (alongside Epic cards) - Story drag-and-drop to change status - Story grouping options - Story swimlanes **Phase 5 (Future Sprint)**: Polish & Accessibility - Keyboard shortcuts (Cmd/Ctrl + N, 1-4 for status, etc.) - Screen reader ARIA labels - Mobile swipe gestures - Activity timeline component - Performance optimization --- **Created**: 2025-11-05 by Product Manager Agent **Next Review**: 2025-11-13 (mid-sprint checkpoint) **Sprint Duration**: 3 weeks (15 working days) **Target Completion**: 2025-11-20 **Minimum Viable**: 2025-11-15 (P0/P1 only, 10 days)