--- name: coordinate-changes description: For changes spanning multiple files, ensures correct order and atomicity. Prevents partial migrations and broken intermediate states. Trigger when changing 3+ files or any shared contract. --- # Coordinated Changes ## Purpose Multi-file changes must be atomic and ordered. This skill ensures updates happen in dependency order to prevent broken intermediate states. ## When to Use - Any change touching 3+ files - Contract changes (types, APIs, shared utilities) - Refactors affecting both producer and consumer - Feature additions spanning multiple layers - After `blast-radius` identifies multiple files to update ## Prerequisites - Blast radius assessed (know all files to change) - Update order determined - Repo Prompt + HelixDB connected --- ## Methodology **Why Order Matters:** If you update a consumer before updating the producer, you get: - Type errors (consumer expects new shape, producer returns old) - Runtime errors (consumer accesses field that doesn't exist yet) - Test failures (tests run against inconsistent state) **Correct Order:** ``` Types → Producers → Consumers → Tests (Roots) (Leaves) ``` --- ## Protocol ### Step 1: Build Dependency Order (HelixDB) From your change target: ``` helix: get_references("") helix: get_definitions("") ``` **Build dependency graph:** ``` types\/product.ts (defines Product) ↓ convex\/products.ts (produces Product) ↓ Products.tsx (transforms Product) ↓ SkuPillEditor.tsx (renders Product.skuParts) ``` **Determine order:** 1. Types\/Interfaces (contract definition) 2. Producers (API, queries, mutations) 3. Transformers (hooks, utilities, state) 4. Consumers (components, pages) 5. Tests (assertions, fixtures) ### Step 2: Load All Files (Repo Prompt) ``` manage_selection(op: "set", paths: [], mode: "full") workspace_context(include: ["tokens"]) ``` **If over token budget:** - Work in batches: (types + producers), then (consumers + tests) - Keep type files loaded throughout for reference ### Step 3: Execute Changes Atomically For each file in dependency order: **Apply the change:** ``` apply_edits(path: "", search: "", replace: "") ``` **Verify structure after:** ``` get_code_structure(scope: "paths", paths: [""]) ``` **Check downstream compatibility:** Does new signature match what next file expects? ### Step 4: Cross-Verify Completeness **Search for any remaining old patterns:** ``` helix: search_code("", limit: 20) ``` If results → migration incomplete, find and update. **Run seam verification:** Invoke `verify-seams` skill on modified files. --- ## Output Format ```markdown ## Coordinated Change: [Description] ### Change Summary | Property | Value | |----------|-------| | Change | Add skuSource field to Product | | Files affected | 6 | | Execution time | ~15 min | ### Execution Log | Order | File | Change | Status | Notes | |-------|------|--------|--------|-------| | 1 | types\/product.ts | Add `skuSource` field | ✓ Done | Contract updated | | 2 | convex\/products.ts | Populate `skuSource` | ✓ Done | Default to "auto" | | 3 | Products.tsx | Use `skuSource` for manual flag | ✓ Done | Replaced !!sku | | 4 | SkuPillEditor.tsx | No change needed | ✓ Skipped | Props unchanged | | 5 | Catalog.tsx | Display skuSource badge | ✓ Done | Shows "manual" indicator | | 6 | product.test.ts | Update fixtures | ✓ Done | All tests pass | ### Verification | Check | Result | |-------|--------| | Old pattern search | 0 results | | Seam verification | All match | | Type check | No errors | | Tests | Passing | ### Rollback Plan If issues discovered: 1. `git diff` to see all changes 2. `git checkout -- ` to revert specific files 3. Or `git stash` to save work and revert all ### Status: ✓ COMPLETE ``` --- ## Batch Execution Pattern For large changes (10+ files), work in batches: ### Batch 1: Contract Layer ``` manage_selection(op: "set", paths: ["types\/", "schema\/"], mode: "full") # Apply type changes # Verify types compile ``` ### Batch 2: Producer Layer ``` manage_selection(op: "set", paths: ["api\/", "convex\/", "lib\/"], mode: "full") # Apply producer changes # Verify producers return new shape ``` ### Batch 3: Consumer Layer ``` manage_selection(op: "set", paths: ["components\/", "pages\/"], mode: "full") # Apply consumer changes # Verify consumption works ``` ### Batch 4: Test Layer ``` manage_selection(op: "set", paths: ["tests\/", "*.test.*"], mode: "full") # Update fixtures and assertions # Run tests ``` --- ## Conflict Resolution **If files have circular dependencies:** 1. Identify the cycle 2. Break by introducing interface\/type layer 3. Update interface first, then implementations **If change breaks mid-execution:** 1. Note which files completed 2. Rollback incomplete files: `git checkout -- ` 3. Diagnose what broke 4. Resume from failed step --- ## Limitations - Cannot guarantee runtime correctness (only structural) - Concurrent changes by others may conflict - Very large changes may exceed context limits - Some frameworks have initialization order requirements beyond code ## Anti-Patterns - ❌ Updating consumer before producer - ❌ Skipping type updates "to save time" - ❌ Updating tests before code (tests will fail during execution) - ❌ Leaving migration half-done "to test" ## Next Actions 1. After completion, run `verify-seams` 2. Run test suite 3. If new integration pattern, `extract-contract`