Atlas Standard Workflow

When to Use This Skill

Perfect for (80% of tasks):

•Bug fixes (2-5 files affected)
•Small features (clear requirements)
•Code refactoring
•Test additions
•Logic changes with moderate complexity

Time estimate: 30-60 minutes

Success criteria:

•Feature complete in < 2 hours
•All edge cases covered
•Tests pass
•Peer review approved

The 5 Phases

code

Phase 1: Research      → Understand current implementation
Phase 2: Plan          → Design approach
Phase 3: Implement     → Make changes + tests
Phase 4: Review        → Edge cases + security
Phase 5: Deploy        → Full test suite + deployment

Phase 1: Research

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

Steps:

•

Find all related files

bash

# Search for relevant code patterns
grep -r "featureName" src/
grep -r "ComponentName" src/

# Find component/function usage
grep -r "import.*ComponentName" src/

•
Understand current implementation
- •Read the main file(s) involved
- •Trace data flow
- •Identify dependencies
- •Note platform-specific code (iOS vs Android vs Web)
•
Check for existing patterns
- •Look for similar implementations
- •Identify coding patterns to follow
- •Review related tests
•
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:

code

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:

•
Design the solution
- •How will you fix the bug / implement the feature?
- •What's the cleanest approach?
- •Are there edge cases to handle?
•
List file changes
- •File 1: What changes?
- •File 2: What changes?
- •Tests: What new tests?
•
Identify dependencies
- •What order to make changes?
- •Any breaking changes?
- •Backwards compatibility needed?
•
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:

code

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:

•
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
•
Update/add tests
- •Add tests for new functionality
- •Update existing tests if behavior changed
- •Ensure tests cover edge cases
•
Verify locally
- •Run tests: npm test
- •Run type checking: npm run typecheck
- •Test manually if UI changes
•
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):

javascript

// ❌ 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):

javascript

// ❌ 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):

javascript

// ❌ 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:

javascript

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

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

•

Run validation commands

bash

npm run typecheck
npm test
npm run lint

•
Invoke peer-reviewer agent (if available)
- •Provide context: "Review my changes for [feature/bug]"
- •Address feedback
- •Re-run validation after fixes
•
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

javascript

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

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

Issue 2: Missing fallback

javascript

// ❌ 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

javascript

// ❌ 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:

•

Update PENDING_CHANGES.md

markdown

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

•

Run full validation

bash

npm run typecheck
npm test
npm run lint

•

Deploy using quality script

bash

# 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

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

bash

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

bash

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

•Update resolveConflict() to deep-merge objects
•Add preserveIconFields() helper
•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)

javascript

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

bash

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

Phase 5: Deploy (5 min)

bash

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