# Debug Generated Project

Debugs issues users encounter with Tuist-generated projects by reproducing the scenario...

- Repository: https://github.com/tuist/tuist (5859 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add tuist/tuist --skill debug-generated-project -g -a claude-code -y`
Codex: `npx skills add tuist/tuist --skill debug-generated-project -g -a codex -y`
Cursor: `npx skills add tuist/tuist --skill debug-generated-project -g -a cursor -y`
Gemini CLI: `npx skills add tuist/tuist --skill debug-generated-project -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debug Tuist Project Issue

## Quick Start

1. Ask the user to describe the issue and the project setup (targets, dependencies, configurations, platform).
2. Confirm the issue exists with the latest release by running `mise exec tuist@latest -- tuist generate` against a reproduction project.
3. If confirmed, clone the Tuist repository and build from source to test against main.
4. Triage: fix the bug and open a PR, advise on misconfiguration, or recommend the user files an issue with a reproduction.

## Step 1: Gather Context

Ask the user for:

- What command they ran (e.g. `tuist generate`)
- The error message or unexpected behavior
- **When the issue happens**: generation time, compile time, or runtime (app launch or later)
- Their project structure: targets, platforms, dependencies (SwiftPM, XCFrameworks, local packages)
- Their `Project.swift` and `Tuist.swift` content (or relevant excerpts)
- Their Tuist version (`tuist version`)

The answer to "when" determines the verification strategy:

- **Generation time**: the issue might be a Tuist bug or a project misconfiguration. Reproduce with `tuist generate`.
- **Compile time**: the generated project has incorrect build settings, missing sources, or wrong dependency wiring. Reproduce with `xcodebuild build` after generation.
- **Runtime**: the app builds but crashes or misbehaves on launch or during use. Reproduce by installing and launching on a simulator.

## Step 2: Reproduce with the latest release

Before investigating the source code, confirm the issue is not already fixed in the latest release.

### Set up a temporary reproduction project

```bash
REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"
```

Create 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.

### Run generation with the latest Tuist release

```bash
mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"
```

The rest: https://github.com/tuist/tuist/blob/HEAD/skills/skills/debug-generated-project/SKILL.md