Atlas Standard

Phase 1: Research

Goal: Understand the current implementation and identify all affected files.

Steps:

1. Find all related files

   # Search for relevant code patterns
   grep -r "featureName" src/
   grep -r "ComponentName" src/
   
   # Find component/function usage
   grep -r "import.*ComponentName" src/
   

2. Understand current implementation

   • Read the main file(s) involved
   • Trace data flow
   • Identify dependencies
   • Note platform-specific code (iOS vs Android vs Web)

3. Check for existing patterns

   • Look for similar implementations
   • Identify coding patterns to follow
   • Review related tests

4. Identify potential impacts

   • Which components use this code?
   • Are there platform-specific considerations?
   • What tests cover this area?

Output:

• List of files to modify
• Understanding of current implementation
• Potential risks identified

StackMap-Specific Research:

For data/state changes:

• Check store usage: Which store? (useAppStore, useUserStore, useSettingsStore, useLibraryStore)
• Verify field naming: Activities use text/icon, Users use icon/name
• Check /src/utils/dataNormalizer.js for normalization logic

For UI changes:

• Check platform-specific files: .native.js, .web.js, .ios.js, .android.js
• Review CLAUDE.md for platform gotchas
• Verify Typography component usage (don't use fontWeight directly on Android)

For sync-related changes:

• Check /src/services/sync/syncService.js
• Review conflict resolution logic
• Verify encryption/decryption handling

Example Research Output:

Files to modify:
- /src/services/sync/syncService.js (main sync logic)
- /src/services/sync/syncStoreIntegration.js (store interaction)
- /src/utils/dataNormalizer.js (field normalization)

Current implementation:
- Conflict resolution uses Object.assign, overwrites nested fields
- Icons stored as `activity.icon` but also `activity.emoji` (legacy)

Risks:
- Must preserve all icon variations during conflict merge
- Need fallback: icon || emoji

Phase 2: Plan

Goal: Design the approach and create a file-by-file implementation plan.

Steps:

1. Design the solution

   • How will you fix the bug / implement the feature?
   • What's the cleanest approach?
   • Are there edge cases to handle?

2. List file changes

   • File 1: What changes?
   • File 2: What changes?
   • Tests: What new tests?

3. Identify dependencies

   • What order to make changes?
   • Any breaking changes?
   • Backwards compatibility needed?

4. Plan testing approach

   • What tests to add/modify?
   • How to verify manually?
   • Platform-specific testing needed?

Output:

• Clear implementation plan
• File-by-file change list
• Testing strategy

StackMap-Specific Planning:

Field naming strategy:

• Reading: Use fallbacks text || name || title, icon || emoji
• Writing: Use canonical fields text, icon
• Normalization: Add to dataNormalizer.js if needed

Store update strategy:

• Identify which store(s) to update
• Use store-specific methods (NOT useAppStore.setState)
• Plan for optimistic updates if applicable

Platform strategy:

• Shared code: Must work on iOS, Android, Web
• Platform-specific: Create separate files (.native.js, .web.js)
• Platform gotchas: Check CLAUDE.md before implementing

Example Plan:

Solution Design:
- Update conflict resolution to deep-merge nested objects
- Add explicit icon field preservation
- Add fallback logic for legacy emoji field

File Changes:
1. /src/services/sync/syncService.js
   - Modify `resolveConflict()` function
   - Add `preserveIconFields()` helper
   - Use deep merge instead of Object.assign

2. /src/utils/dataNormalizer.js
   - Add `normalizeActivityIcon()` function
   - Handle emoji → icon migration

3. /tests/sync/syncService.test.js
   - Add test: "preserves icon during conflict"
   - Add test: "migrates emoji to icon"

Testing Approach:
- Unit tests for conflict resolution
- Integration test for full sync cycle
- Manual test: Create conflict, verify icon preserved

Phase 3: Implement

Goal: Make the changes and update tests.

Steps:

1. Implement changes file-by-file

   • Follow the plan from Phase 2
   • Use store-specific update methods
   • Follow field naming conventions
   • Add code comments for complex logic

2. Update/add tests

   • Add tests for new functionality
   • Update existing tests if behavior changed
   • Ensure tests cover edge cases

3. Verify locally

   • Run tests: npm test
   • Run type checking: npm run typecheck
   • Test manually if UI changes

4. Apply StackMap conventions

   • NO gray text (use #000)
   • Typography component for fonts
   • Store-specific update methods
   • Field naming: text/icon, not name/emoji

Implementation Checklist:

Before writing code:

• Understand the pattern to follow (research phase complete)
• Know which store method to use
• Field naming strategy clear

During implementation:

• Use store-specific methods (useUserStore.getState().setUsers())
• Use canonical field names (text, icon)
• Include fallbacks when reading (text || name || title)
• Remove debug logs or wrap in __DEV__ check
• Add comments for non-obvious logic

After implementation:

• All imports correct
• No console.log statements
• Tests added/updated
• Type checking passes

StackMap-Specific 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 (Android compatibility):

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

// ✅ CORRECT: Use Typography component
<Typography fontWeight="bold">Hello</Typography>
// Typography handles Android font variants automatically

Example Implementation:

// File: /src/services/sync/syncService.js

// Helper function to preserve icon fields
const preserveIconFields = (local, remote) => {
  // Use canonical field names
  const localIcon = local.icon || local.emoji
  const remoteIcon = remote.icon || remote.emoji

  // Prefer newer, fallback to either
  const preservedIcon = remote.icon || localIcon

  return {
    ...remote,
    icon: preservedIcon,
    // Remove legacy field
    emoji: undefined
  }
}

// Update conflict resolution
const resolveConflict = (local, remote) => {
  const resolved = preserveIconFields(local, remote)

  // Use store-specific method
  useUserStore.getState().setUsers(users =>
    users.map(u => u.id === resolved.id ? resolved : u)
  )

  return resolved
}

Phase 4: Review

Goal: Peer review for edge cases and security check.

Steps:

1. Self-review first

   • Re-read all changed files
   • Check for edge cases
   • Verify store update methods used
   • Confirm field naming correct

2. Run validation commands

   npm run typecheck
   npm test
   npm run lint
   

3. Invoke peer-reviewer agent (if available)

   • Provide context: "Review my changes for [feature/bug]"
   • Address feedback
   • Re-run validation after fixes

4. Security check (if applicable)

   • Handling user data? Verify encryption
   • External API calls? Verify authentication
   • User input? Verify sanitization

Review Checklist:

Code quality:

• Follows project coding standards
• No debugging console.logs
• Clear variable/function names
• Comments for complex logic
• No copy-paste duplication

StackMap conventions:

• Store-specific update methods used (not useAppStore.setState)
• Field naming: text/icon (not name/emoji)
• Fallbacks included when reading fields
• Typography component used (not direct fontWeight)
• No gray text colors (use #000)

Platform compatibility:

• Shared code works on iOS, Android, Web
• Platform-specific code in correct files
• No platform-specific APIs in shared code (Alert.alert, etc.)
• FlexWrap on Android uses percentage widths

Edge cases:

• Null/undefined handling
• Empty array/object handling
• Backwards compatibility with old data
• Migration path for legacy fields

Testing:

• Tests cover main functionality
• Tests cover edge cases
• Tests pass (npm test)
• Type checking passes (npm run typecheck)

Example Review Issues:

Issue 1: Direct state update

// ❌ Found during review
useAppStore.setState({ users: updatedUsers })

// ✅ Fixed
useUserStore.getState().setUsers(updatedUsers)

Issue 2: Missing fallback

// ❌ Found during review
<Text>{activity.text}</Text>  // Will break for legacy data

// ✅ Fixed
<Text>{activity.text || activity.name || activity.title}</Text>

Issue 3: Edge case not handled

// ❌ Found during review
const firstActivity = activities[0]  // Crashes if empty

// ✅ Fixed
const firstActivity = activities.length > 0 ? activities[0] : null
if (!firstActivity) return null

Phase 5: Deploy

Goal: Run full test suite and deploy via quality script.

Steps:

1. Update PENDING_CHANGES.md

   ## Title: Fix sync icon preservation
   ### Changes Made:
   - Updated conflict resolution to preserve icon fields
   - Added deep merge for nested objects
   - Migrated legacy emoji field to icon
   - Added tests for icon preservation
   

2. Run full validation

   npm run typecheck
   npm test
   npm run lint
   

3. Deploy using quality script

   # For QUAL (local testing)
   ./scripts/deploy.sh qual --all
   
   # For STAGE (internal validation)
   ./scripts/deploy.sh stage --all
   
   # For BETA (closed testing)
   ./scripts/deploy.sh beta --all
   
   # For PROD (production)
   ./scripts/deploy.sh prod --all
   

4. Verify deployment

   • Check deployment output for errors
   • Verify version incremented
   • Test on target environment

Deployment Checklist:

Pre-deployment:

• PENDING_CHANGES.md updated with clear description
• All tests pass (npm test)
• Type checking passes (npm run typecheck)
• No linting errors (npm run lint)
• Working directory clean (no uncommitted changes for beta/prod)

Deployment:

• Use deployment script (NOT manual git commands)
• Choose correct tier (qual/stage/beta/prod)
• Platform specified if not deploying all (--web, --ios, --android)

Post-deployment:

• Deployment succeeded (no errors in output)
• Version incremented correctly
• Changes visible in deployed environment
• No rollbacks needed

Quality Gates (Enforced by deploy script):

The deployment script automatically enforces:

• ✅ All tests pass (no skipping without approval)
• ✅ TypeScript type checking passes
• ✅ Build succeeds
• ✅ Clean commit with message from PENDING_CHANGES.md
• ✅ Version auto-incremented

If tests fail: Fix them. Don't skip tests. If type checking fails: Fix type errors. Don't bypass. If build fails: Debug build issues. Don't commit broken code.

Example Deployment:

# 1. Update PENDING_CHANGES.md
## Title: Fix activity icon preservation during sync conflicts
### Changes Made:
- Updated syncService conflict resolution to preserve icon fields
- Added deep merge utility for nested object conflicts
- Migrated legacy emoji field to canonical icon field
- Added test coverage for icon preservation scenarios
- Updated dataNormalizer with emoji→icon migration logic

# 2. Run validation
npm run typecheck  # ✅ Pass
npm test          # ✅ Pass

# 3. Deploy to QUAL for testing
./scripts/deploy.sh qual --all

# Output:
# ✅ Type checking: Pass
# ✅ Tests: Pass (15/15)
# ✅ Build: Success
# ✅ Version: 2025.01.18 → 2025.01.19
# ✅ Deployed: qual-api.stackmap.app

Success Indicators

You've succeeded when:

• ✅ Task completed in < 2 hours
• ✅ All 5 phases completed (no skipping)
• ✅ Tests pass
• ✅ Peer review approved (no major issues)
• ✅ Deployed without rollback
• ✅ Edge cases covered
• ✅ StackMap conventions followed

You need to escalate to Full workflow if:

• ⚠️ Scope expanded to 6+ files
• ⚠️ Security concerns emerged
• ⚠️ Formal requirements needed
• ⚠️ Cross-platform issues more complex than expected

Common Pitfalls

❌ Don't Do This:

• Skip research phase ("I know where the bug is")
• Skip planning ("I'll figure it out as I code")
• Skip review phase ("It's a small change")
• Skip deployment script ("Manual commit is faster")
• Use useAppStore.setState() directly
• Use legacy field names (activity.name, activity.emoji)
• Add console.logs without removing them
• Skip platform testing for shared code

✅ Do This Instead:

• Complete all 5 phases (they're quick for Standard tier)
• Use store-specific update methods
• Use canonical field names with fallbacks
• Remove debug logs or wrap in __DEV__
• Test on all platforms if changing shared code
• Use deployment script for quality gates

Resources

• Research patterns: See resources/research-patterns.md
• StackMap conventions: See /CLAUDE.md
• Platform gotchas: See /docs/platform/
• Store architecture: See /docs/STORE_ARCHITECTURE.md
• Field conventions: See /docs/features/field-conventions.md

Example: Full Standard Workflow

Task: "Fix bug where activity icons are lost during sync conflicts"

Phase 1: Research (10 min)

# Find sync-related files
grep -r "resolveConflict" src/
grep -r "icon" src/services/sync/

# Files found:
# - /src/services/sync/syncService.js (conflict resolution)
# - /src/services/sync/syncStoreIntegration.js (store updates)
# - /src/utils/dataNormalizer.js (field normalization)

Understanding:

• Conflict resolution uses Object.assign, overwrites nested fields
• Icons stored as both icon (new) and emoji (legacy)
• Current code doesn't preserve icon during conflicts

Phase 2: Plan (5 min)

Solution:

1. Update resolveConflict() to deep-merge objects
2. Add preserveIconFields() helper
3. Migrate emoji → icon in normalizer

Files to change:

• syncService.js - add icon preservation
• dataNormalizer.js - add migration
• syncService.test.js - add tests

Phase 3: Implement (20 min)

// syncService.js
const preserveIconFields = (local, remote) => {
  const icon = remote.icon || local.icon || local.emoji
  return { ...remote, icon, emoji: undefined }
}

const resolveConflict = (local, remote) => {
  const resolved = preserveIconFields(local, remote)

  // Use store-specific method
  useActivityStore.getState().updateActivity(resolved)

  return resolved
}

// Add tests
test('preserves icon during conflict', () => {
  const local = { id: 1, text: 'Run', icon: '🏃' }
  const remote = { id: 1, text: 'Running' }  // missing icon

  const result = resolveConflict(local, remote)
  expect(result.icon).toBe('🏃')
})

Phase 4: Review (10 min)

Self-review checklist:

• ✅ Store-specific method used (updateActivity)
• ✅ Field naming correct (icon, not emoji)
• ✅ Fallback included (icon || emoji)
• ✅ Tests added
• ✅ No console.logs

Run validation:

npm run typecheck  # ✅ Pass
npm test          # ✅ Pass (16/16)

Phase 5: Deploy (5 min)

# Update PENDING_CHANGES.md
## Title: Fix activity icon preservation during sync conflicts
### Changes Made:
- Updated conflict resolution to preserve icon fields
- Added deep merge for nested objects
- Migrated legacy emoji to icon field
- Added test coverage

# Deploy
./scripts/deploy.sh qual --all
# ✅ Deployed successfully

Total time: ~50 minutes ✅

Summary

The Standard workflow is your daily driver for most development tasks. It provides the right balance of:

• Rigor: All 5 phases ensure quality
• Speed: Completed in 30-60 minutes
• Flexibility: Can escalate to Full if needed

When in doubt, choose Standard workflow - it's correct for 80% of tasks.