atlas-standard

# 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 ``` 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: 1. **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/ ``` 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):** ```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: 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** ```bash 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** ```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: 1. **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 ``` 2. **Run full validation** ```bash npm run typecheck npm test npm run lint ``` 3. **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 ``` 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: ```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