Update to Tuist

{
  "name": "compare-generations",
  "description": "Compares two `tuist generate` runs to identify cache hit rate changes and root-cause analysis of cache invalidation. Can be invoked with generation IDs, dashboard URLs, or branch names.",
  "included_files": [],
  "skill_md_contents": "---\nname: compare-generations\ndescription: Compares two `tuist generate` runs to identify cache hit rate changes and root-cause analysis of cache invalidation. Can be invoked with generation IDs, dashboard URLs, or branch names.\n---\n\n# Compare Generations\n\n## Quick Start\n\nYou'll typically receive two generation identifiers. Follow these steps:\n\n1. Run `tuist generate list --json` to find generations on each branch.\n2. Run `tuist generate show <id> --json` for both base and head generations.\n3. Compare duration, status, and cache hit rates.\n4. Summarize cache changes with root cause analysis.\n\n## Step 1: Resolve Generations\n\n### If base/head are generation IDs or dashboard URLs\n\nFetch each directly:\n\n```bash\ntuist generate show <base-id> --json\ntuist generate show <head-id> --json\n```\n\n### If base/head are branch names\n\nList recent generations on each branch:\n\n```bash\ntuist generate list --git-branch <base-branch> --json --page-size 1\ntuist generate list --git-branch <head-branch> --json --page-size 1\n```\n\nThen fetch full details with `tuist generate show <id> --json`.\n\n### Defaults\n\n- If no base is provided, use the project's default branch (usually `main`).\n- If no head is provided, detect the current git branch.\n\n## Step 2: Compare Top-Level Metrics\n\nAfter fetching both generations, compare:\n\n| Metric | What to check |\n|---|---|\n| `duration` | Flag if head is >10% slower |\n| `status` | Flag if base succeeded but head failed |\n| `cacheable_targets` | Note if target count changed |\n| `local_cache_target_hits` | Compare local hit counts |\n| `remote_cache_target_hits` | Compare remote hit counts |\n| `is_ci` | Note if one is CI and the other local |\n\nCompute cache hit rates:\n- Base: `(local_hits + remote_hits) / cacheable_targets * 100`\n- Head: same formula\n- Delta: `head_rate - base_rate`\n\n## Step 3: Analyze Cache Invalidation\n\nIf cache hit rate dropped, the key question is: **which target(s) caused the invalidation cascade?**\n\nCache invalidation typically works like this:\n1. A \"root cause\" target has a direct change (source file modified, build setting changed, etc.)\n2. All targets that depend on the root cause target also get invalidated because their `dependencies` hash changes.\n3. This cascade can invalidate many targets from a single root change.\n\n### Identifying root cause targets\n\nWithout the module cache target detail endpoint (available via MCP), use these heuristics:\n\n1. Check `git diff` between the base and head commits to see which files changed.\n2. Map changed files to their Tuist targets/modules.\n3. Targets with direct source changes are likely root causes.\n4. Targets that only changed due to dependency hash cascading are secondary invalidations.\n\n### Common root causes of cache invalidation\n\n| Cause | Description |\n|---|---|\n| Source changes | Files in the target's source directory were modified |\n| Resource changes | Assets, XIBs, storyboards, or other resources changed |\n| Build settings | Target or project build settings were modified |\n| Dependency changes | An external dependency version changed |\n| Info.plist changes | The target's Info.plist was modified |\n| Entitlements changes | The entitlements file was modified |\n| Deployment target | The minimum deployment target changed |\n| Headers | Public or project headers changed |\n| Project settings | Shared project-level settings changed |\n\n## Step 4: Assess Impact\n\nCategorize the cache invalidation:\n\n- **Expected**: Source files were intentionally changed, causing expected cache misses.\n- **Unexpected**: No source changes but cache was invalidated (build settings, Xcode version, etc.).\n- **Cascade**: A small change invalidated many downstream targets.\n\n## Summary Format\n\nProduce a summary with:\n\n1. **Overall verdict**: Cache hit rate improved, regressed, or stable.\n2. **Cache hit rate**: Base rate vs head rate with delta.\n3. **Duration**: Absolute and percentage change.\n4. **Root cause targets**: Which targets had direct changes.\n5. **Cascade impact**: How many targets were invalidated due to dependency cascading.\n6. **Recommendations**: How to minimize cache invalidation.\n\nExample:\n\n```\nGeneration Comparison: base (gen-123 on main) vs head (gen-456 on feature-x)\n\nDuration: 12.5s -> 28.3s (+126%) -- REGRESSION\nCache hit rate: 92% (46/50) -> 64% (32/50) (-28%) -- REGRESSION\nStatus: success -> success\n\nRoot cause: FoundationModule had source changes (3 files modified).\nThis cascaded to 14 downstream targets that depend on FoundationModule.\n\nCache invalidation breakdown:\n- Direct changes: FoundationModule (sources changed)\n- Cascade: NetworkModule, AuthModule, UIModule, + 11 others (dependency hash changed)\n\nRecommendations:\n- Consider splitting FoundationModule into smaller modules to reduce cascade impact\n- The 14 cascaded targets could benefit from more granular dependency declarations\n- If FoundationModule changes frequently, consider interface/implementation module splitting\n```\n\n## Done Checklist\n\n- Resolved both base and head generations\n- Compared duration and cache hit rates\n- Identified root cause targets for cache invalidation\n- Analyzed cascade impact\n- Provided actionable recommendations for reducing cache misses\n"
}