ColaFlow/docs/plans/sprint_4.md

sprint_id, milestone, status, created_date, start_date, target_end_date

sprint_id	milestone	status	created_date	start_date	target_end_date
sprint_4	M1	not_started	2025-11-05	2025-11-06	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 - Story Detail Page Foundation - not_started - P0 Critical - 3 days
• story_2 - Task Management in Story Detail - not_started - P0 Critical - 2 days
• story_3 - Enhanced Story Form - not_started - P1 High - 2 days
• story_4 - Quick Add Story Workflow - not_started - P1 High - 2 days
• story_5 - Story Card Component - not_started - P2 Medium - 1 day
• story_6 - 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
• Story Design Summary

Planning Documents

• Product Roadmap
• Sprint 1 Plan - Frontend Integration
• Sprint 2 Plan - M1 Backend Features
• Sprint 3 Plan - Frontend Code Quality

Technical References

• ProjectManagement Module
• Epic Detail Page
• Story Types

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)