{"id":14327,"plugin_id":"plugin_asdk_app_69fa07fe5ba48191a4ea47c4d7d55a69","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:09:17.095Z","digest":"9f178767ca45091040ffae8b70b9d7a01379151dd0306bb382d53b1cafc1f4fe","against":null,"payload":{"name":"debug-generated-project","description":"Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.","included_files":[],"skill_md_contents":"---\nname: debug-generated-project\ndescription: Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.\n---\n\n# Debug Tuist Project Issue\n\n## Quick Start\n\n1. Ask the user to describe the issue and the project setup (targets, dependencies, configurations, platform).\n2. Confirm the issue exists with the latest release by running `mise exec tuist@latest -- tuist generate` against a reproduction project.\n3. If confirmed, clone the Tuist repository and build from source to test against main.\n4. Triage: fix the bug and open a PR, advise on misconfiguration, or recommend the user files an issue with a reproduction.\n\n## Step 1: Gather Context\n\nAsk the user for:\n\n- What command they ran (e.g. `tuist generate`)\n- The error message or unexpected behavior\n- **When the issue happens**: generation time, compile time, or runtime (app launch or later)\n- Their project structure: targets, platforms, dependencies (SwiftPM, XCFrameworks, local packages)\n- Their `Project.swift` and `Tuist.swift` content (or relevant excerpts)\n- Their Tuist version (`tuist version`)\n\nThe answer to \"when\" determines the verification strategy:\n\n- **Generation time**: the issue might be a Tuist bug or a project misconfiguration. Reproduce with `tuist generate`.\n- **Compile time**: the generated project has incorrect build settings, missing sources, or wrong dependency wiring. Reproduce with `xcodebuild build` after generation.\n- **Runtime**: the app builds but crashes or misbehaves on launch or during use. Reproduce by installing and launching on a simulator.\n\n## Step 2: Reproduce with the latest release\n\nBefore investigating the source code, confirm the issue is not already fixed in the latest release.\n\n### Set up a temporary reproduction project\n\n```bash\nREPRO_DIR=$(mktemp -d)\ncd \"$REPRO_DIR\"\n```\n\nCreate minimal `Tuist.swift`, `Project.swift`, and source files that reproduce the user's scenario. Keep it as small as possible while still triggering the issue.\n\n### Run generation with the latest Tuist release\n\n```bash\nmise exec tuist@latest -- tuist generate --no-open --path \"$REPRO_DIR\"\n```\n\nIf the issue involves dependencies, install them first:\n\n```bash\nmise exec tuist@latest -- tuist install --path \"$REPRO_DIR\"\n```\n\n### Check the result\n\n- If generation succeeds and the issue is gone, tell the user to update to the latest version.\n- If the issue persists, continue to Step 3.\n\n## Step 3: Build Tuist from Source\n\nClone the repository and build the `tuist` executable and `ProjectDescription` library from source to test against the latest code on `main`.\n\n```bash\nTUIST_SRC=$(mktemp -d)\ngit clone --depth 1 https://github.com/tuist/tuist.git \"$TUIST_SRC\"\ncd \"$TUIST_SRC\"\nswift build --product tuist --product ProjectDescription --replace-scm-with-registry\n```\n\nThe built binary will be at `.build/debug/tuist`. Use it to test the reproduction project:\n\n```bash\n\"$TUIST_SRC/.build/debug/tuist\" generate --no-open --path \"$REPRO_DIR\"\n```\n\n### If the issue is fixed on main\n\nTell the user the fix is already on `main`, and it hasn't been released, tell them it'll be in the nest release and point them to the relevant commit if you can identify it.\n\n### If the issue persists on main\n\nContinue to Step 4.\n\n## Step 4: Triage the Issue\n\nInvestigate the Tuist source code to understand why the issue occurs.\n\n### Outcome A: It is a bug\n\n1. Identify the root cause in the source code.\n2. Apply the fix.\n3. Verify by rebuilding and running against the reproduction project:\n   ```bash\n   cd \"$TUIST_SRC\"\n   swift build --product tuist --product ProjectDescription --replace-scm-with-registry\n   \"$TUIST_SRC/.build/debug/tuist\" generate --no-open --path \"$REPRO_DIR\"\n   ```\n4. Zip the reproduction project and include it in the PR:\n   ```bash\n   cd \"$REPRO_DIR\" && cd ..\n   zip -r reproduction.zip \"$(basename \"$REPRO_DIR\")\" -x '*.xcodeproj/*' -x '*.xcworkspace/*' -x 'Derived/*' -x '.build/*'\n   ```\n5. Open a PR on the Tuist repository with:\n   - The fix\n   - The zipped reproduction project attached or committed as a fixture\n   - A clear description of the root cause and how to verify the fix\n\n### Outcome B: It is a misconfiguration\n\nTell the user what is wrong and how to fix it. Common misconfigurations:\n\n- Missing `tuist install` before `tuist generate` when using external dependencies\n- Incorrect source or resource globs that exclude or double-include files\n- Mismatched build configurations between the project and external dependencies\n- Wrong product types for dependencies (static vs dynamic)\n- Missing `-ObjC` linker flag for Objective-C dependencies\n- Using `sources` and `resources` globs together with `buildableFolders`\n\nProvide the corrected manifest snippet so the user can apply the fix directly.\n\n### Outcome C: Unclear or needs team input\n\nIf you cannot determine whether it is a bug or misconfiguration, recommend the user:\n\n1. Open a GitHub issue at https://github.com/tuist/tuist/issues with:\n   - The reproduction project (zipped)\n   - The error output\n   - Their Tuist version and environment details\n\nProvide a summary of what you investigated and what you ruled out, so the user does not have to repeat the triage.\n\n## Build Verification\n\nWhen testing a fix, always verify the full cycle:\n\n```bash\n# Build the patched tuist\ncd \"$TUIST_SRC\"\nswift build --product tuist --product ProjectDescription --replace-scm-with-registry\n\n# Install dependencies if needed\n\"$TUIST_SRC/.build/debug/tuist\" install --path \"$REPRO_DIR\"\n\n# Generate the project\n\"$TUIST_SRC/.build/debug/tuist\" generate --no-open --path \"$REPRO_DIR\"\n\n# Build the generated project\nxcodebuild build \\\n  -workspace \"$REPRO_DIR\"/*.xcworkspace \\\n  -scheme <scheme> \\\n  -destination \"platform=iOS Simulator,name=iPhone 16 Pro\"\n```\n\n## Runtime Verification\n\nWhen the user reports a runtime issue (crash on launch, missing resources at runtime, wrong bundle structure, or unexpected behavior), you must go beyond building and actually launch the app on a simulator.\n\n### Launch and monitor for crashes\n\n```bash\n# Boot a simulator\nxcrun simctl boot \"iPhone 16 Pro\" 2>/dev/null || true\n\n# Build for the simulator\nxcodebuild build \\\n  -workspace \"$REPRO_DIR\"/*.xcworkspace \\\n  -scheme <scheme> \\\n  -destination \"platform=iOS Simulator,name=iPhone 16 Pro\" \\\n  -derivedDataPath \"$REPRO_DIR/DerivedData\"\n\n# Install the app\nxcrun simctl install booted \"$REPRO_DIR/DerivedData/Build/Products/Debug-iphonesimulator/<AppName>.app\"\n\n# Launch and monitor — this will print crash info if the app terminates abnormally\nxcrun simctl launch --console-pty booted <bundle-identifier>\n```\n\nThe `--console-pty` flag streams the app's stdout/stderr so you can observe logs and crash output directly. Watch for:\n\n- **Immediate crash on launch**: usually a missing framework, wrong bundle ID, missing entitlements, or stripped ObjC categories (`-ObjC` linker flag missing)\n- **Crash after a few seconds**: often missing resources (images, storyboards, XIBs, asset catalogs) or a bundle structure mismatch\n- **Runtime misbehavior without crash**: wrong resource paths, missing localization files, or incorrect Info.plist values\n\n### Check crash logs\n\nIf the app crashes without useful console output, pull the crash log:\n\n```bash\n# List recent crash logs for the app\nfind ~/Library/Logs/DiagnosticReports -name \"<AppName>*\" -newer \"$REPRO_DIR\" -print\n```\n\nRead the crash log to identify the crashing thread and the faulting symbol.\n\n## Done Checklist\n\n- Gathered enough context from the user to reproduce the issue\n- Determined whether the issue is at generation time, compile time, or runtime\n- Confirmed whether the issue exists in the latest release\n- Tested against Tuist built from source (main branch)\n- If runtime issue: launched the app on a simulator and verified the crash or misbehavior\n- Triaged the issue as a bug, misconfiguration, or unclear\n- If bug: applied fix, verified it, and opened a PR with reproduction project\n- If misconfiguration: provided corrected manifest to the user\n- If unclear: gave the user a summary and recommended next steps\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}