Update to Tuist

{
  "name": "compare-builds",
  "description": "Compares two Xcode build runs to identify duration regressions, cache changes, and new issues. Can be invoked with build IDs, dashboard URLs, or branch names (e.g. `tuist compare-builds --base main --head feature-branch`).",
  "included_files": [],
  "skill_md_contents": "---\nname: compare-builds\ndescription: Compares two Xcode build runs to identify duration regressions, cache changes, and new issues. Can be invoked with build IDs, dashboard URLs, or branch names (e.g. `tuist compare-builds --base main --head feature-branch`).\n---\n\n# Compare Builds\n\n## Quick Start\n\nYou'll typically receive two build identifiers (IDs, dashboard URLs, or branch names). Follow these steps:\n\n1. Run `tuist build list --json` to find builds on each branch.\n2. Run `tuist build show <build-id> --json` for both base and head builds.\n3. Fetch sub-resource details: targets (`tuist build xcode target list <id> --json`), issues (`tuist build xcode issue list <id> --json`), and cache tasks (`tuist build xcode cache-task list <id> --json`).\n4. Compare duration, status, cache hit rates, and other metrics.\n5. Summarize regressions, improvements, and recommendations.\n\nIf only one identifier is provided, use the project's default branch as the baseline.\n\n## Step 1: Resolve Builds\n\n### If base/head are build IDs or dashboard URLs\n\nFetch each directly:\n\n```bash\ntuist build show <base-id> --json\ntuist build show <head-id> --json\n```\n\n### If base/head are branch names\n\nList recent builds on each branch and pick the latest:\n\n```bash\ntuist build list --git-branch <base-branch> --json --page-size 1\ntuist build list --git-branch <head-branch> --json --page-size 1\n```\n\nThen fetch full details with `tuist build 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 with `git rev-parse --abbrev-ref HEAD`.\n\n## Step 2: Fetch Sub-Resource Details\n\nAfter fetching both builds with `tuist build show <id> --json`, drill down into sub-resources for a deeper comparison.\n\n### Compare targets\n\n```bash\ntuist build xcode target list <base-id> --json\ntuist build xcode target list <head-id> --json\n```\n\nLook for targets that changed status (e.g., success to failure) or had significant duration changes.\n\n### Compare issues\n\n```bash\ntuist build xcode issue list <base-id> --json\ntuist build xcode issue list <head-id> --json\n```\n\nLook for new warnings or errors introduced in the head build.\n\n### Compare cache tasks\n\n```bash\ntuist build xcode cache-task list <base-id> --json\ntuist build xcode cache-task list <head-id> --json\n```\n\nIdentify which specific targets had cache misses or hits and whether that changed between builds.\n\n## Step 3: Compare Top-Level Metrics\n\nAfter fetching both builds, compare:\n\n| Metric | What to check |\n|---|---|\n| `duration` | Flag if head is >10% slower than base |\n| `status` | Flag if base succeeded but head failed |\n| `cacheable_tasks_count` | Note if task count changed |\n| `cacheable_task_local_hits_count` | Compare local hit counts |\n| `cacheable_task_remote_hits_count` | Compare remote hit counts |\n| Cache hit rate | `(local_hits + remote_hits) / cacheable_tasks_count * 100` |\n| `category` | Note if one is `clean` and the other `incremental` (makes duration comparison less meaningful) |\n| `scheme` / `configuration` | Ensure both builds used the same scheme and configuration for a fair comparison |\n\nCompute the cache miss delta: `base_misses - head_misses`. Positive means head has fewer misses (improvement). Negative means regression.\n\n## Step 4: Investigate Duration Regressions\n\nIf the head build is significantly slower:\n\n1. Check if the `category` differs (clean vs incremental builds are not directly comparable).\n2. Check if cache hit rate dropped, which would explain longer builds.\n3. If both are incremental with similar cache rates, the regression is likely in compilation time.\n\n## Step 5: Investigate Cache Changes\n\nCompare cache statistics:\n\n- **Hit rate dropped**: Possible causes include dependency changes, build setting changes, or Xcode version updates.\n- **Hit rate improved**: Likely due to better cache warming or fewer source changes.\n- **Task count changed**: New targets added or removed.\n\n## Step 6: Check Build Context\n\nCompare environment details:\n\n- `xcode_version` and `macos_version`: Different versions can affect build times and cache validity.\n- `is_ci`: CI vs local builds may have different performance characteristics.\n- `git_branch` and `git_commit_sha`: Verify the builds are from the expected commits.\n\n## Summary Format\n\nProduce a summary with:\n\n1. **Overall verdict**: Better, worse, or neutral compared to base.\n2. **Duration**: Absolute and percentage change.\n3. **Cache hit rate**: Change in hit rate with explanation.\n4. **Status**: Any status changes (pass to fail or vice versa).\n5. **Environment**: Note any environment differences that affect comparability.\n6. **Recommendations**: Actionable next steps based on findings.\n\nExample:\n\n```\nBuild Comparison: base (abc123 on main) vs head (def456 on feature-x)\n\nDuration: 45.2s -> 62.8s (+39%) -- REGRESSION\nCache hit rate: 85% -> 72% (-13%) -- 8 new cache misses\nStatus: success -> success\n\nRoot cause: Cache hit rate dropped due to 8 targets with invalidated caches.\nThe dependency hash changed for FeatureModule, cascading to 7 downstream targets.\n\nRecommendations:\n- Investigate why FeatureModule's cache was invalidated\n- Consider splitting large targets to reduce cascade impact\n```\n\n## Done Checklist\n\n- Resolved both base and head builds\n- Fetched sub-resource details (targets, issues, cache tasks)\n- Compared duration, cache, and status metrics\n- Identified root causes for any regressions\n- Provided actionable recommendations\n"
}