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

   # 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:

## 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:

## 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.

# 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:

# 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)
   • Feature flags needed?
   • Rollback plan
   • Monitoring strategy

Planning Template:

## Implementation Plan: [Feature Name]

### Architecture

#### Component Structure:

[Draw component hierarchy or describe]

#### Data Flow:

User Action → Component → Service → Store → UI Update [Detailed flow diagram or description]

#### State Management:
- **Store**: [which store(s)]
- **State shape**: [schema]
- **Update methods**: [new methods needed]

### File-by-File Plan

#### New Files:
1. **/src/services/newService.js**
   - Purpose: [what it does]
   - Functions:
     - `function1()`: [description]
     - `function2()`: [description]
   - Dependencies: [what it imports]

2. **/src/components/NewComponent.js**
   - Purpose: [what it does]
   - Props: [prop schema]
   - State: [local state]
   - Platform: [shared/native/web]

#### Modified Files:
1. **/src/stores/useAppStore.js**
   - Add: [new state fields]
   - Modify: [existing functions]
   - Migration: [how to handle existing data]

2. **/src/components/ExistingComponent.js**
   - Add: [new feature integration]
   - Modify: [existing behavior]

#### Test Files:
1. **/tests/services/newService.test.js**
   - Test coverage:
     - [ ] Unit tests for all functions
     - [ ] Edge cases
     - [ ] Error handling

### Data Schema

#### New Fields:
```javascript
activity: {
  // ... existing fields
  newField: {
    type: [type],
    required: [boolean],
    default: [default value],
    validation: [validation rules]
  }
}

Migration Strategy:

// How to handle existing data
const migrateOldData = (activity) => {
  return {
    ...activity,
    newField: activity.legacyField || defaultValue
  }
}

Testing Strategy

Unit Tests:

• newService.function1() - happy path
• newService.function1() - error cases
• newService.function2() - edge cases

Integration Tests:

• Full workflow: [user action → result]
• Error recovery
• Offline/online transitions

Platform Tests:

• iOS: [specific tests]
• Android: [specific tests]
• Web: [specific tests]

Performance Tests:

• Load time < [threshold]
• Memory usage < [threshold]
• No memory leaks

Implementation Order

Iteration 1: Core functionality

1. Create newService.js with basic functions
2. Add tests for newService
3. Add state to store
4. Test store integration

Iteration 2: UI integration

1. Create NewComponent
2. Integrate with existing UI
3. Add platform-specific variations
4. Test on all platforms

Iteration 3: Edge cases

1. Add error handling
2. Add offline support
3. Add loading states
4. Test all edge cases

Iteration 4: Polish

1. Performance optimization
2. Accessibility improvements
3. Documentation
4. Final testing

Rollout Strategy

QUAL (development testing):

• Deploy with feature flag (enabled for testing)
• Test all platforms
• Validate performance
• Fix any issues

STAGE (internal validation):

• Deploy to stage environment
• Internal team testing
• Gather feedback
• Refine based on feedback

BETA (closed beta):

• Deploy to beta users (feature flag 50%)
• Monitor usage metrics
• Monitor error rates
• Collect user feedback

PROD (full release):

• Gradual rollout: 10% → 50% → 100%
• Monitor success metrics
• Monitor error rates
• Rollback plan ready

Rollback Plan

If critical issues arise:

1. Disable feature flag (immediate)
2. Or: Revert to previous deployment (< 15 minutes)
3. Notify users if data affected
4. Fix issues in QUAL/STAGE
5. Re-test before re-enabling

Monitoring

Metrics to track:

• Success rate (uploads, actions)
• Error rate
• Performance (load time, memory)
• User adoption
• User engagement

Alerts:

• Error rate > 5%
• Performance degradation > 20%
• Crash rate increase

StackMap-Specific Planning

Field Naming:

• Writing: Use text, icon (canonical)
• Reading: Use text || name || title, icon || emoji (with fallbacks)
• Add to dataNormalizer.js if migration needed

Store Updates:

• Identify which store: [useUserStore, useSettingsStore, etc.]
• Use store-specific methods: useUserStore.getState().setUsers()
• Never use useAppStore.setState() directly

Platform Considerations:

• Android: FlexWrap cards use 48% widths
• iOS: AsyncStorage debounced, NetInfo disabled
• Web: 3-column layout uses 31%/48%/100% widths
• Use Typography component (not direct fontWeight)

Sync Strategy:

• What data needs to sync?
• Conflict resolution strategy
• Encryption needed?
• Field migration for existing synced data

Design Rules:

• No gray text (use #000 only)
• High contrast required
• Typography component for fonts
• Accessibility: screen reader support, touch targets

### Example Plan:

*(See resources/plan-example.md for full example)*

### Planning Validation Checklist:

- [ ] Architecture clearly defined
- [ ] File-by-file plan complete
- [ ] Implementation order logical
- [ ] Testing strategy comprehensive
- [ ] Rollout strategy defined
- [ ] Rollback plan ready
- [ ] Monitoring plan in place
- [ ] StackMap conventions addressed
- [ ] Platform-specific considerations documented
- [ ] Data migration strategy clear

---

## Phase 4: Adversarial Review

**Goal**: Security audit, edge case analysis, and critical evaluation.

**Time allocation**: 15-20 minutes

### Steps:

1. **Security audit**
   - Use checklist in `resources/adversarial-checklist.md`
   - Identify vulnerabilities
   - Assess attack vectors
   - Validate data encryption
   - Check authentication/authorization

2. **Edge case analysis**
   - What can go wrong?
   - What assumptions might break?
   - What happens under load?
   - What if external dependencies fail?

3. **Performance analysis**
   - Memory usage implications
   - Network bandwidth usage
   - Battery impact (mobile)
   - Startup time impact

4. **Cross-platform compatibility**
   - iOS-specific issues?
   - Android-specific issues?
   - Web-specific issues?
   - Version compatibility?

5. **Maintainability review**
   - Code complexity reasonable?
   - Test coverage sufficient?
   - Documentation clear?
   - Technical debt acceptable?

### Adversarial Review Checklist:

Use the comprehensive checklist in `resources/adversarial-checklist.md`.

**Security** (if applicable):
- [ ] User data encrypted at rest
- [ ] User data encrypted in transit
- [ ] Authentication required where needed
- [ ] Authorization checked for all actions
- [ ] Input validation/sanitization
- [ ] No secrets in code
- [ ] API keys secured
- [ ] No XSS vulnerabilities
- [ ] No SQL injection vulnerabilities

**Edge Cases**:
- [ ] Empty states handled
- [ ] Null/undefined handled
- [ ] Network failures handled
- [ ] Offline mode supported
- [ ] Race conditions prevented
- [ ] Concurrent access handled
- [ ] Large datasets handled
- [ ] Old app versions compatible

**Performance**:
- [ ] Load time acceptable (< 3s)
- [ ] Memory usage reasonable
- [ ] No memory leaks
- [ ] Network bandwidth optimized
- [ ] Battery impact minimal (mobile)
- [ ] Startup time not impacted
- [ ] 60fps maintained (animations)

**Cross-Platform**:
- [ ] iOS testing complete
- [ ] Android testing complete
- [ ] Web testing complete
- [ ] Platform-specific gotchas addressed
- [ ] No platform-specific APIs in shared code
- [ ] Consistent UX across platforms

**Maintainability**:
- [ ] Code complexity reasonable (no 500-line functions)
- [ ] Adequate comments for complex logic
- [ ] Test coverage > 80% for critical paths
- [ ] Documentation complete
- [ ] No copy-paste duplication
- [ ] Follows project patterns

**StackMap-Specific**:
- [ ] Store-specific update methods used
- [ ] Field naming conventions followed
- [ ] Fallbacks included for legacy fields
- [ ] Typography component used (not direct fontWeight)
- [ ] No gray text (only #000)
- [ ] Platform gotchas addressed (CLAUDE.md)

### Adversarial Questions:

Ask yourself tough questions:

1. **"What's the worst that could happen?"**
   - User loses data?
   - App crashes?
   - Security breach?
   - How do we prevent it?

2. **"What if this becomes popular?"**
   - Can it scale?
   - Storage costs?
   - Performance under load?

3. **"What if external service fails?"**
   - Firebase down?
   - Network offline?
   - API timeout?
   - Graceful degradation?

4. **"What if user does unexpected thing?"**
   - Spams button?
   - Enters invalid data?
   - Uses old app version?
   - Switches platforms?

5. **"What will break in 6 months?"**
   - Technical debt?
   - Deprecated APIs?
   - Maintenance burden?
   - Future compatibility?

### Red Flags:

**Stop and reconsider if:**
- 🚩 Security concerns unaddressed
- 🚩 Performance implications unclear
- 🚩 Rollback plan not feasible
- 🚩 Testing strategy inadequate
- 🚩 Technical debt too high
- 🚩 Cross-platform issues unresolved
- 🚩 Edge cases not handled

### Adversarial Review Output:

```markdown
## Adversarial Review: [Feature Name]

### Security Assessment: ✅ PASS / ⚠️ CONCERNS / ❌ FAIL
[Details of security review]

**Concerns found**:
1. [Concern 1] - Mitigation: [plan]
2. [Concern 2] - Mitigation: [plan]

### Edge Case Analysis: ✅ COVERED / ⚠️ PARTIAL / ❌ GAPS
[Details of edge case analysis]

**Edge cases to address**:
1. [Case 1] - Plan: [how to handle]
2. [Case 2] - Plan: [how to handle]

### Performance Assessment: ✅ GOOD / ⚠️ ACCEPTABLE / ❌ CONCERNING
[Details of performance analysis]

**Optimizations needed**:
1. [Optimization 1]
2. [Optimization 2]

### Cross-Platform Compatibility: ✅ READY / ⚠️ NEEDS WORK / ❌ BLOCKED
[Details of cross-platform review]

**Platform issues to address**:
- iOS: [issues]
- Android: [issues]
- Web: [issues]

### Maintainability: ✅ GOOD / ⚠️ ACCEPTABLE / ❌ HIGH DEBT
[Details of maintainability review]

**Debt to address**:
1. [Debt item 1]
2. [Debt item 2]

### Overall Verdict: ✅ PROCEED / ⚠️ PROCEED WITH CAUTION / ❌ REVISE PLAN

**Blocking issues** (must fix before proceeding):
1. [Issue 1]
2. [Issue 2]

**Non-blocking issues** (address during implementation):
1. [Issue 1]
2. [Issue 2]

Example Review Output:

## Adversarial Review: Photo Attachments

### Security Assessment: ✅ PASS

**Reviewed**:
- Photos stored in Firebase Storage (secure, access-controlled)
- Photo URLs in sync data (encrypted with NaCl)
- No direct file access from unauthorized users
- Permissions properly requested on mobile

**Concerns found**: None blocking

### Edge Case Analysis: ⚠️ PARTIAL

**Edge cases covered**:
- Offline upload queue ✅
- Permission denial handling ✅
- Large file compression ✅
- Upload failure retry ✅

**Edge cases to address**:
1. User deletes photo while uploading - Plan: Cancel upload, remove from queue
2. Firebase storage quota exceeded - Plan: Show error, prompt upgrade or cleanup
3. Photo corruption during upload - Plan: Validate file before upload, retry on corruption

### Performance Assessment: ⚠️ ACCEPTABLE

**Measurements**:
- Upload time: ~2.5s for 5MB photo ✅
- Thumbnail display: ~150ms ✅
- Memory usage: +15MB per photo in gallery (concern for many photos)

**Optimizations needed**:
1. Implement photo lazy loading (only load visible photos)
2. Add memory cache with size limit (max 10 photos in memory)
3. Thumbnail pre-caching on scroll

### Cross-Platform Compatibility: ✅ READY

**Platform testing**:
- iOS: Permissions, photo picker work ✅
- Android: Permissions, photo picker work ✅
- Web: File input works ✅

**Platform-specific considerations addressed**:
- iOS Info.plist permissions ✅
- Android manifest permissions ✅
- Web drag-and-drop ✅

### Maintainability: ✅ GOOD

**Code quality**:
- photoService.js well-structured (~200 lines)
- Clear separation of concerns
- Adequate comments
- Test coverage planned at 85%

**Technical debt**: Minimal, acceptable

### Overall Verdict: ⚠️ PROCEED WITH CAUTION

**Blocking issues**: None

**Non-blocking issues** (address during implementation):
1. Memory optimization for photo gallery (lazy loading)
2. Handle storage quota exceeded gracefully
3. Handle photo deletion during upload

**Recommendation**: Proceed to implementation. Address non-blocking issues in Phase 5.

Phase 5: Implementation

Goal: Build the feature incrementally with parallel work where possible.

Time allocation: 60-90 minutes

Steps:

1. Set up implementation tracking

   • Break plan into tasks
   • Identify parallel vs sequential tasks
   • Track progress

2. Implement in iterations

   • Iteration 1: Core functionality (basic feature works)
   • Iteration 2: UI integration (feature accessible to users)
   • Iteration 3: Edge cases (all scenarios handled)
   • Iteration 4: Polish (performance, UX refinements)

3. Follow coding standards

   • StackMap conventions (store methods, field naming, Typography)
   • Code comments for complex logic
   • No debugging logs or wrap in __DEV__
   • Consistent formatting

4. Incremental validation

   • Test after each iteration
   • Fix issues before moving to next iteration
   • Run type checking periodically

Implementation Strategy:

Parallel Work (can be done simultaneously):

• Service layer implementation
• Component development
• Test writing
• Documentation updates

Sequential Work (must be done in order):

1. Core service functions
2. Store integration
3. Component integration
4. Platform-specific implementations
5. Final polish

Implementation Checklist:

Before starting:

• Plan reviewed and approved
• Adversarial review passed
• Development environment ready
• All dependencies installed

During implementation:

• Follow file-by-file plan from Phase 3
• Write tests alongside code
• Use store-specific methods (not setState)
• Use canonical field names (text, icon)
• Include fallbacks for legacy fields
• Use Typography component (not direct fontWeight)
• Remove debug logs or wrap in __DEV__
• Add comments for non-obvious logic
• Run npm run typecheck periodically

After each iteration:

• Iteration functionality works
• Tests pass for iteration
• Type checking passes
• Code reviewed by self
• Ready for next iteration

Iteration Breakdown:

Iteration 1: Core Functionality (20-30 min) Goal: Basic feature works in isolation

• Implement service layer
• Add store state and methods
• Write unit tests
• Verify core logic works

Iteration 2: UI Integration (20-30 min) Goal: Feature accessible to users

• Create/modify UI components
• Integrate with store
• Add loading/error states
• Test user interactions

Iteration 3: Edge Cases (15-20 min) Goal: All scenarios handled gracefully

• Implement error handling
• Add offline support
• Handle empty/null states
• Add retry logic
• Test all edge cases

Iteration 4: Polish (10-15 min) Goal: Performance, UX, accessibility

• Performance optimizations
• Accessibility improvements
• Animation refinements
• Final testing
• Code cleanup

StackMap Implementation Rules:

Store Updates (CRITICAL):

// ❌ WRONG: Direct setState
useAppStore.setState({ users: newUsers })

// ✅ CORRECT: Store-specific method
useUserStore.getState().setUsers(newUsers)

// ✅ CORRECT: Store-specific method for settings
useSettingsStore.getState().updateSettings({ theme: 'dark' })

// ✅ CORRECT: Store-specific method for library
useLibraryStore.getState().setLibrary(newLibrary)

Field Naming (CRITICAL):

// ❌ WRONG: Legacy field names
activity.name = "Running"
activity.emoji = "🏃"

// ✅ CORRECT: Canonical field names
activity.text = "Running"
activity.icon = "🏃"

// ✅ CORRECT: Reading with fallbacks
const text = activity.text || activity.name || activity.title
const icon = activity.icon || activity.emoji

Typography (Platform Compatibility):

// ❌ WRONG: Direct fontWeight on Android
<Text style={{ fontWeight: 'bold' }}>Hello</Text>

// ✅ CORRECT: Use Typography component
<Typography fontWeight="bold">Hello</Typography>

Design Rules:

// ❌ WRONG: Gray text (accessibility)
<Text style={{ color: '#666666' }}>Text</Text>

// ✅ CORRECT: Black text
<Text style={{ color: '#000000' }}>Text</Text>

Platform-Specific Files:

# Shared code (iOS + Android + Web)
Component.js

# Mobile only (iOS + Android)
Component.native.js

# Web only
Component.web.js

# iOS only (rare)
Component.ios.js

# Android only (rare)
Component.android.js

Code Quality Standards:

Function length: < 50 lines (split if longer) File length: < 500 lines (split into modules if longer) Cyclomatic complexity: < 10 (refactor if higher) Comments: For non-obvious logic, not obvious code Variable names: Descriptive, not abbreviated (unless common: id, url) No magic numbers: Use named constants

Example Implementation Progress:

## Implementation Progress: Photo Attachments

### Iteration 1: Core Functionality ✅ COMPLETE (25 min)
- ✅ Created /src/services/photoService.js
  - uploadPhoto(uri, activityId)
  - deletePhoto(url, activityId)
  - generateThumbnail(uri)
- ✅ Added tests to /tests/services/photoService.test.js
- ✅ Added activity.photos to store schema
- ✅ Type checking passes

### Iteration 2: UI Integration ⏳ IN PROGRESS (15/30 min)
- ✅ Created /src/components/PhotoAttachment.js
- ✅ Created /src/components/PhotoGallery.js
- ✅ Updated /src/components/ActivityCard.js to show thumbnails
- 🔄 Integrating with ActivityEditModal
- ⏳ Adding loading/error states

### Iteration 3: Edge Cases ⏳ PENDING
- Handle upload cancellation
- Handle storage quota exceeded
- Offline queue implementation
- Permission denial flow

### Iteration 4: Polish ⏳ PENDING
- Memory optimization (lazy loading)
- Thumbnail pre-caching
- Animation polish
- Accessibility improvements

### Issues Found:
1. ⚠️ Upload progress not showing - Fixed: Added progress callback
2. ⚠️ Large photos cause memory spike - TODO: Implement compression earlier

Validation During Implementation:

Run these commands periodically:

# Type checking (fast, run often)
npm run typecheck

# Linting (fast)
npm run lint

# Tests (slower, run after each iteration)
npm test

# Build (slowest, run before committing)
npm run build:web  # Web build
# iOS/Android builds tested in Phase 6

Phase 6: Testing

Goal: Comprehensive validation across all platforms and scenarios.

Time allocation: 30-45 minutes

Steps:

1. Automated testing

   # Unit tests
   npm test
   
   # Type checking
   npm run typecheck
   
   # Linting
   npm run lint
   
   # Build validation
   npm run build:web
   

2. Manual testing - Happy path

   • Test primary user flow on each platform
   • Verify all acceptance criteria met
   • Check performance (load times, animations)

3. Manual testing - Edge cases

   • Test all edge cases from Phase 2
   • Test error scenarios
   • Test offline behavior
   • Test with poor network

4. Cross-platform testing

   • iOS (simulator + real device)
   • Android (emulator + real device)
   • Web (desktop + mobile browsers)
   • Test platform-specific features

5. Regression testing

   • Verify existing features still work
   • Check for unintended side effects
   • Test related features

Testing Checklist:

Automated Tests:

• All unit tests pass
• All integration tests pass
• Type checking passes
• Linting passes (or only warnings)
• Build succeeds (web, iOS, Android)
• Test coverage > 80% for new code

Manual Testing - Happy Path:

• Primary user flow works on iOS
• Primary user flow works on Android
• Primary user flow works on Web
• All acceptance criteria met
• Performance acceptable (< 3s load, 60fps)
• No console errors

Manual Testing - Edge Cases:

• Empty states display correctly
• Error messages clear and helpful
• Loading states show appropriately
• Offline mode works
• Poor network handled gracefully
• Large data sets handled
• Rapid user actions handled (no crashes)

Platform-Specific Testing:

• iOS: Permissions work
• iOS: Native features work (camera, etc.)
• iOS: UI matches iOS patterns
• Android: Permissions work
• Android: Native features work
• Android: UI matches Material Design
• Web: Responsive design works
• Web: Desktop browser tested
• Web: Mobile browser tested

Regression Testing:

• Existing features unaffected
• No performance degradation
• No new console errors
• Sync still works
• Navigation still works
• Data integrity maintained

StackMap-Specific Testing:

• Store updates work correctly
• Field naming correct (text/icon)
• Typography renders correctly (all platforms)
• No gray text (only #000)
• Sync works with new data structure
• Migration works for existing data

Testing Scenarios:

Use scenarios from Phase 2 story. Example:

### Test Scenario 1: Upload Photo (Happy Path)

**Steps**:
1. Open activity in edit mode
2. Tap "Add Photo" button
3. Select photo from gallery
4. Wait for upload

**Expected**:
- Photo picker opens ✅
- Progress indicator shows ✅
- Thumbnail displays after upload ✅
- Activity updates immediately ✅

**Platforms Tested**:
- iOS Simulator ✅
- Android Emulator ✅
- Web Desktop ✅

**Result**: ✅ PASS

---

### Test Scenario 2: Upload Photo (Offline)

**Steps**:
1. Turn on airplane mode
2. Open activity in edit mode
3. Tap "Add Photo" button
4. Select photo from gallery
5. Turn off airplane mode

**Expected**:
- Photo queued for upload ⚠️
- "Pending upload" indicator shows ⚠️
- Auto-uploads when online ❌ (Not working)
- Notification on success ⏳ (Not tested)

**Platforms Tested**:
- iOS Simulator ⚠️

**Result**: ❌ FAIL - Offline queue not working

**Fix**: Implemented offline queue in photoService.js, retested ✅ PASS

Performance Testing:

Metrics to measure:

• Load time (initial + subsequent)
• Memory usage (baseline + after feature use)
• Network usage (bandwidth, request count)
• Battery drain (mobile only)
• Animation frame rate (should be 60fps)
• App startup time (shouldn't increase)

Tools:

• React DevTools (component render times)
• Chrome DevTools (network, performance)
• Xcode Instruments (iOS performance)
• Android Profiler (Android performance)

Acceptable thresholds (StackMap-specific):

• Page load: < 3 seconds
• API response: < 1 second
• Animation: 60fps (no drops below 50fps)
• Memory: < 200MB total app usage
• Startup: < 5 seconds (cold start)

Testing Output:

## Testing Report: Photo Attachments

### Automated Tests: ✅ PASS
- Unit tests: 42/42 passed
- Integration tests: 8/8 passed
- Type checking: Pass
- Linting: Pass (3 warnings, non-blocking)
- Build: Success (web, iOS, Android)
- Coverage: 87% (target: 80%)

### Manual Testing - Happy Path: ✅ PASS
All acceptance criteria met across all platforms.

**iOS**: ✅ All features work
**Android**: ✅ All features work
**Web**: ✅ All features work

### Manual Testing - Edge Cases: ⚠️ PARTIAL PASS

**Passed** (8/10):
- Empty states ✅
- Error messages ✅
- Loading states ✅
- Poor network ✅
- Large files ✅
- Rapid actions ✅
- Permissions denied ✅
- Old data migration ✅

**Failed** (2/10):
- Offline upload queue ❌ → Fixed, retested ✅
- Storage quota exceeded ❌ → Fixed, retested ✅

### Platform-Specific Testing: ✅ PASS
- iOS: Permissions, camera, UI ✅
- Android: Permissions, camera, UI ✅
- Web: Responsive, desktop, mobile ✅

### Regression Testing: ✅ PASS
- All existing features work ✅
- No performance degradation ✅
- Sync works correctly ✅
- No new errors ✅

### Performance Testing: ✅ PASS
- Upload time: 2.3s avg (target: < 3s) ✅
- Thumbnail display: 140ms avg (target: < 200ms) ✅
- Memory usage: +12MB (acceptable) ✅
- No memory leaks ✅
- 60fps maintained ✅

### Issues Found & Fixed:
1. ❌ Offline queue not working → Fixed in photoService.js
2. ❌ Storage quota not handled → Added error handling
3. ⚠️ Memory spike with many photos → Added lazy loading

### Overall: ✅ READY FOR VALIDATION

All critical issues resolved. Ready for Phase 7 validation.

Phase 7: Validation

Goal: Verify all acceptance criteria met and feature ready for deployment.

Time allocation: 15-20 minutes

Steps:

1. Acceptance criteria review

   • Go through story from Phase 2
   • Check each criterion systematically
   • Provide evidence for each

2. Success metrics validation

   • Can we measure the metrics?
   • Are targets realistic?
   • Is tracking implemented?

3. Documentation review

   • User-facing documentation complete?
   • Developer documentation complete?
   • API documentation (if applicable)?

4. Stakeholder review (if applicable)

   • Demo the feature
   • Gather feedback
   • Address concerns

Validation Checklist:

Acceptance Criteria:

• All "Must Have" criteria met (100%)
• Evidence provided for each criterion
• All "Should Have" criteria met (or deferred)
• All platform-specific criteria met

Success Metrics:

• Metrics measurable
• Tracking implemented
• Targets realistic
• Baseline established (if applicable)

Documentation:

• User guide updated (if user-facing)
• Developer docs updated (if API changes)
• CLAUDE.md updated (if conventions change)
• README updated (if workflow changes)

Quality Gates:

• All tests pass
• Type checking passes
• Build succeeds
• No critical bugs
• Performance acceptable
• Security review passed (if applicable)

Stakeholder Approval (if applicable):

• Feature demoed
• Feedback gathered
• Concerns addressed
• Sign-off received

Validation Output:

## Validation Report: Photo Attachments

### Acceptance Criteria Validation

#### Must Have (10/10) ✅ 100%

1. ✅ User can select photo from gallery
   - Evidence: Tested

…(truncated)