atlas-full

# Atlas Full Workflow ## When to Use This Skill **Perfect for (complex tasks, ~5% of work):** - Major features (6+ files affected) - New modules or services - Security-critical changes - Cross-platform features requiring coordination - Epic-level work requiring formal requirements - Architectural changes affecting multiple systems - Features requiring comprehensive testing strategy **Time estimate**: 2-4 hours **Success criteria**: - 100% of acceptance criteria met - Zero defects in production first week - Complete documentation and evidence - Full test coverage for critical paths - Security audit passed (if applicable) - Cross-platform validation complete ## The 9 Phases ``` Phase 1: Research → Deep exploration, feasibility analysis Phase 2: Story Creation → Formal requirements, acceptance criteria Phase 3: Planning → Technical design, architecture Phase 4: Adversarial Review → Security audit, edge case analysis Phase 5: Implementation → Parallel coding, incremental builds Phase 6: Testing → Comprehensive validation, all platforms Phase 7: Validation → Acceptance criteria verification Phase 8: Clean-up → Documentation, artifacts, debt log Phase 9: Deployment → Full quality gates, staged rollout ``` --- ## Phase 1: Research **Goal**: Deep understanding of requirements, feasibility, and technical landscape. **Time allocation**: 20-30 minutes ### Steps: 1. **Define the problem space** - What problem are we solving? - Who are the users? - What are the business requirements? - What are the technical constraints? 2. **Explore current implementation** ```bash # Find all related code grep -r "related_feature" src/ # Find similar patterns find src/ -name "*similar*" # Check git history for similar features git log --grep="similar feature" --oneline ``` 3. **Research dependencies and integrations** - What external services/APIs are involved? - What internal modules will be affected? - What platform-specific considerations exist? - What are the data flow implications? 4. **Identify risks and constraints** - Technical risks (performance, compatibility, security) - Timeline constraints - Resource constraints - Platform limitations 5. **Evaluate alternatives** - What are different approaches to solve this? - What are the trade-offs? - What's the recommended approach? ### Research Checklist: **Problem Understanding:** - [ ] Clear problem statement - [ ] User stories identified - [ ] Success metrics defined - [ ] Constraints documented **Technical Research:** - [ ] Current implementation mapped - [ ] Similar patterns found - [ ] Dependencies identified - [ ] Platform considerations noted **Risk Analysis:** - [ ] Technical risks listed - [ ] Security implications assessed - [ ] Performance implications considered - [ ] Migration/rollback strategy outlined **Feasibility:** - [ ] Technically feasible - [ ] Timeline realistic - [ ] Resources available - [ ] No blockers identified ### StackMap-Specific Research: **For data/state changes:** - Which stores affected? (`useAppStore`, `useUserStore`, `useSettingsStore`, `useLibraryStore`) - Field naming strategy? (Activities: `text`/`icon`, Users: `name`/`icon`) - Sync implications? (Conflict resolution, encryption, field migration) - Data migration needed? (Existing user data compatibility) **For UI/UX changes:** - Platform-specific files needed? (`.native.js`, `.web.js`, `.ios.js`, `.android.js`) - Platform gotchas? (Check CLAUDE.md: Android FlexWrap, iOS AsyncStorage, Web layouts) - Design rules followed? (No gray text, high contrast, Typography component) - Accessibility requirements? (Screen readers, color contrast, font sizes) **For cross-platform features:** - Native module integration? (iOS, Android) - Platform-specific APIs? (Camera, location, notifications) - Testing strategy per platform? - Performance considerations per platform? **For security-critical changes:** - Authentication/authorization affected? - Data encryption implications? - API security requirements? - Vulnerability assessment needed? ### Research Output Template: ```markdown ## Research Findings: [Feature Name] ### Problem Statement: [Clear description of what we're solving] ### Users Affected: - [User type 1]: [how they benefit] - [User type 2]: [how they benefit] ### Technical Approach: [High-level approach, alternatives considered] ### Files to Create/Modify: - /path/to/new/file.js - [purpose] - /path/to/existing/file.js - [what changes] - /path/to/test/file.test.js - [test coverage] ### Dependencies: - External: [external packages, APIs] - Internal: [internal modules, services] ### Platform Considerations: - **iOS**: [specific notes] - **Android**: [specific notes] - **Web**: [specific notes] ### Data/Store Impact: - Store(s): [which stores] - Fields: [new/modified fields] - Migration: [data migration strategy] - Sync: [sync implications] ### Risks: 1. [Risk 1] - Mitigation: [strategy] 2. [Risk 2] - Mitigation: [strategy] ### Success Metrics: - [Metric 1]: [target] - [Metric 2]: [target] ### Timeline Estimate: - Research: [time] - Implementation: [time] - Testing: [time] - Total: [time] ``` ### Example Research Output: ```markdown ## Research Findings: Photo Attachments for Activities ### Problem Statement: Users want to attach photos to their activities to provide visual context and make activity tracking more engaging and memorable. ### Users Affected: - All users: Can attach photos to activities - Premium users: Can attach unlimited photos (free: max 3 per activity) ### Technical Approach: 1. Use expo-image-picker for photo selection 2. Store photos in Firebase Storage 3. Store photo URLs in activity.photos array 4. Implement thumbnail generation for performance 5. Lazy load photos in activity cards Alternatives considered: - Store base64 in sync data: Rejected (too large, slow sync) - Use device storage only: Rejected (not cross-device) ### Files to Create/Modify: - /src/services/photoService.js - Upload, delete, thumbnail generation - /src/components/ActivityCard.js - Display thumbnail - /src/components/PhotoAttachment.js - Photo picker UI (NEW) - /src/components/PhotoGallery.js - Full screen photo viewer (NEW) - /src/stores/useAppStore.js - Add photos array to activity schema - /src/services/sync/syncService.js - Sync photo URLs (not files) - /tests/services/photoService.test.js - Test upload/delete (NEW) ### Dependencies: - External: expo-image-picker, firebase-storage - Internal: useAppStore, syncService, dataNormalizer ### Platform Considerations: - **iOS**: Requires camera/photo library permissions in Info.plist - **Android**: Requires camera/storage permissions in AndroidManifest.xml - **Web**: Use file input, no native picker ### Data/Store Impact: - Store: useAppStore (activities) - New field: activity.photos (array of { url, thumbnailUrl, timestamp }) - Migration: Add empty photos array to existing activities - Sync: Only sync URLs, not photo files (files stored in Firebase) ### Risks: 1. Storage costs - Mitigation: Thumbnail compression, size limits 2. Photo permissions denial - Mitigation: Clear UI messaging, fallback 3. Upload failures on poor network - Mitigation: Retry logic, offline queue 4. Photo deletion not synced - Mitigation: Include deleted photo URLs in sync ### Success Metrics: - 80%+ of active users attach at least one photo in first week - Average upload time < 3 seconds - Photo display time < 200ms (thumbnail) - Zero storage-related crashes ### Timeline Estimate: - Research: 30 min ✅ - Story Creation: 15 min - Planning: 30 min - Implementation: 90 min - Testing: 45 min - Total: 3.5 hours ``` --- ## Phase 2: Story Creation **Goal**: Create formal user stories with acceptance criteria and success metrics. **Time allocation**: 15-20 minutes ### Steps: 1. **Write user stories** - Use standard format: "As a [user], I want [goal], so that [benefit]" - Break down complex features into multiple stories - Prioritize stories (must-have, should-have, nice-to-have) 2. **Define acceptance criteria** - Specific, measurable, testable criteria - Cover happy path and edge cases - Include performance requirements - Include platform-specific criteria 3. **Set success metrics** - How will we measure success? - What are the targets? - How will we collect data? 4. **Create testing scenarios** - Manual testing checklist - Automated test requirements - Cross-platform testing plan ### Story Template: Use the template in `resources/story-template.md` for consistent formatting. ```markdown # User Story: [Feature Name] ## Story As a [user type] I want [goal] So that [benefit] ## Acceptance Criteria ### Must Have: 1. [ ] [Specific, testable criterion 1] 2. [ ] [Specific, testable criterion 2] 3. [ ] [Specific, testable criterion 3] ### Should Have: 1. [ ] [Nice-to-have criterion 1] 2. [ ] [Nice-to-have criterion 2] ### Platform-Specific: - **iOS**: [ ] [iOS-specific requirement] - **Android**: [ ] [Android-specific requirement] - **Web**: [ ] [Web-specific requirement] ## Success Metrics - [Metric 1]: [Target value] - [Metric 2]: [Target value] ## Testing Scenarios ### Happy Path: 1. [Step 1] 2. [Step 2] 3. Expected: [Result] ### Edge Cases: 1. **Empty state**: [Expected behavior] 2. **Error state**: [Expected behavior] 3. **Offline**: [Expected behavior] ## Dependencies - [Dependency 1] - [Dependency 2] ## Risks - [Risk 1]: [Mitigation] - [Risk 2]: [Mitigation] ``` ### Example Story: ```markdown # User Story: Photo Attachments for Activities ## Story As an active user I want to attach photos to my activities So that I can add visual context and make my activity log more engaging ## Acceptance Criteria ### Must Have: 1. [ ] User can select photo from device gallery 2. [ ] User can take new photo with camera 3. [ ] User can attach up to 3 photos per activity (free tier) 4. [ ] Photos display as thumbnails in activity card 5. [ ] Tapping thumbnail opens full-screen photo viewer 6. [ ] User can delete attached photos 7. [ ] Photos sync across devices (URLs only, not files) 8. [ ] Upload shows progress indicator 9. [ ] Failed uploads show error message with retry option 10. [ ] Photos compressed/thumbnailed for performance ### Should Have: 1. [ ] User can reorder photos (drag and drop) 2. [ ] Photos include timestamp/location metadata 3. [ ] Swipe gesture to navigate between photos in viewer 4. [ ] Share photo to social media ### Platform-Specific: - **iOS**: [ ] Request camera/photo library permissions - **iOS**: [ ] Handle permission denial gracefully - **Android**: [ ] Request camera/storage permissions - **Android**: [ ] Handle permission denial gracefully - **Web**: [ ] Use file input (no native picker) - **Web**: [ ] Support drag-and-drop photo upload ## Success Metrics - **Adoption**: 80%+ of active users attach at least one photo in first week - **Performance**: Average upload time < 3 seconds - **Performance**: Photo thumbnail display < 200ms - **Reliability**: 99%+ upload success rate - **Quality**: Zero storage-related crashes ## Testing Scenarios ### Happy Path: 1. User taps "Add Photo" button 2. User selects photo from gallery 3. Photo uploads with progress indicator 4. Thumbnail displays in activity card 5. Tapping thumbnail opens full-screen viewer Expected: Photo displays correctly, all interactions smooth ### Edge Cases: **Slow network**: - Upload shows progress - User can cancel upload - Retry available on failure **Permissions denied**: - Clear message explaining why permission needed - Link to settings to enable permission - Graceful fallback (no crash) **Large photo file**: - Automatic compression before upload - Warning if file too large (>10MB) - Thumbnail generated for display **Offline mode**: - Photo queued for upload when online - Indicator showing "pending upload" - Retry automatically when connection restored **Storage full (device)**: - Error message shown - Prompt user to free space - Don't crash app **Storage quota exceeded (Firebase)**: - Error message shown - Prompt to upgrade or delete old photos - Graceful degradation ## Dependencies - expo-image-picker (photo selection) - firebase-storage (cloud storage) - react-native-fast-image (thumbnail caching) ## Risks - **Storage costs**: Mitigate with compression, size limits, cleanup policy - **Permission denial**: Mitigate with clear messaging, graceful fallback - **Upload failures**: Mitigate with retry logic, offline queue - **Performance on old devices**: Mitigate with lazy loading, thumbnail optimization ``` ### Story Validation Checklist: - [ ] User story follows "As a...I want...So that" format - [ ] Acceptance criteria are specific and testable - [ ] Edge cases covered - [ ] Platform-specific requirements included - [ ] Success metrics defined with targets - [ ] Testing scenarios documented - [ ] Dependencies identified - [ ] Risks documented with mitigation --- ## Phase 3: Planning **Goal**: Create detailed technical design and implementation plan. **Time allocation**: 20-30 minutes ### Steps: 1. **Architecture design** - How will components interact? - What's the data flow? - Where does state live? - How does it integrate with existing systems? 2. **File-by-file implementation plan** - What files to create? - What files to modify? - What changes in each file? - What order to implement? 3. **Data schema design** - What new fields/structures? - How to migrate existing data? - How does sync handle it? - What validations needed? 4. **Testing strategy** - Unit tests for each module - Integration tests for workflows - Platform-specific tests - Performance tests 5. **Rollout strategy** - Phased rollout plan (QUAL → STAGE → BETA → PROD)