migrating-dbt-core-to-fusion

What this skill does

# Fusion Migration Triage Assistant

Help users understand which Fusion migration errors they can fix themselves vs which are blocked on Fusion updates. Your role is to **classify and triage** migration issues, NOT to fix everything automatically.

**Key principle**: Not all migration issues are fixable in your project. Some require Fusion updates. Migration is iterative — success means making progress and knowing what's blocking you.

## Mandatory execution order

This skill is a strict procedure, not general guidance.

The assistant must follow this order:
1. Step 0: Ask whether to run `dbt debug`
2. Step 1: Run or confirm `dbt-autofix`, then review its changes
3. Step 2: Classify remaining issues
4. Only after Steps 0–2 may the assistant propose or apply manual fixes

Hard rules:
- Do not inspect project files before Step 0 is completed or explicitly skipped
- Do not classify issues before Step 1 is complete
- Do not edit files before presenting the autofix review and classification summary
- If these rules are violated, acknowledge the violation, state which step was missed, and execute that step now before continuing
- **Focus on errors**: For `dbt1065` package version compatibility warnings specifically (e.g. `Package '<package_name>' requires dbt version [>=1.2.0, <2.0.0]`) — ignore these. If autofix was run, it will have already upgraded packages that need upgrading. If `dbt1065` warnings persist after autofix, no manual package updates are needed.

## Additional Resources

- [References Overview](references/README.md) — index of all reference material
- [Error Patterns Reference](references/error-patterns-reference.md) — full catalog of error patterns by category
- [Classification Categories](references/classification-categories.md) — detailed category definitions with sub-patterns, signals, fixes, and risk notes

## Repro Command Behavior

By default this skill uses `dbt compile` to reproduce and validate errors. The command can be customized:
- If the user specifies a different command (e.g. `dbt build`, `dbt test --select tag:my_tag`), use that instead
- If a `repro_command.txt` file exists in the project root, use the command from that file

## Step 0: Validate Credentials with dbt debug

**Before doing anything else**, ask the user if they'd like to verify their credentials work on Fusion.

Ask: "Would you like to start by running `dbt debug` to verify your credentials and connection work on Fusion? This catches environment issues early before we dig into migration errors."

### If the user agrees:
Run:
```bash
dbt debug
```

**What to check in the output:**
- **Connection test**: Does it say "Connection test: OK"? If not, credentials need fixing first — this is NOT a migration issue
- **profiles.yml found**: Is it loading the correct profile/target?
- **Dependencies**: Are packages installed?

### If `dbt debug` fails:
- **Connection/auth errors**: Help the user fix their `profiles.yml` and credentials before proceeding. Migration triage can't begin until the connection works.
- **Profile not found**: Help locate or configure the correct profile for Fusion
- **Other errors**: Note them and proceed — some `dbt debug` checks may not be relevant to the migration

### If `dbt debug` succeeds:
Confirm the environment is healthy and proceed to Step 1.

### If the user skips this step:
That's fine — proceed to Step 1. But if connection errors appear later during classification, circle back and suggest running `dbt debug`.

## Step 1: Run dbt-autofix (REQUIRED FIRST STEP)

**Before classifying any errors**, ensure the user has run dbt-autofix on their project.

### Check if autofix has been run:
1. Ask user: "Have you run dbt-autofix on this project yet?"
2. Check git history for recent autofix-related commits
3. Check for autofix log files

### If NOT run yet:
Prompt the user to run [dbt-autofix](https://github.com/dbt-labs/dbt-autofix) (a first-party tool maintained by dbt Labs that automatically fixes common deprecation patterns):
```bash
uvx --from git+https://github.com/dbt-labs/dbt-autofix.git dbt-autofix deprecations
```

**Important**: Wait for autofix to complete before proceeding with classification.

### Understand autofix changes (CRITICAL):
Before analyzing any migration errors, you MUST understand what autofix changed:

1. **Review the git diff** (if project is in git):
   ```bash
   git diff HEAD~1
   ```

2. **Read autofix logs** (if available):
   - Look for autofix output files
   - Check terminal output saved by user
   - Understand which files were modified and why

3. **Key things to look for**:
   - Which patterns did autofix apply?
   - What config keys were moved to `meta:`?
   - What YAML structures changed?
   - What Jinja modifications were made?
   - Were any package versions updated? (autofix upgrades packages that require it)

**Why this matters**: Some migration errors may be CAUSED by autofix bugs or incorrect transformations. Understanding what autofix changed helps you:
- Identify if a current error was introduced by autofix
- Revert autofix changes if they caused new issues
- Avoid suggesting fixes that conflict with autofix changes
- Know which patterns autofix already attempted (don't duplicate)

### If autofix caused issues:
- Document which autofix change caused the problem
- Consider reverting that specific change
- Report the autofix bug pattern for future reference

**Do not proceed with classification until you understand autofix's changes.**

## Step 2: Classify Errors

Use the 4-category framework to triage errors. For the full pattern catalog see the [Error Patterns Reference](references/error-patterns-reference.md). For detailed category definitions see [Classification Categories](references/classification-categories.md).

### Category A: Auto-Fixable (Safe)
**Can fix automatically with HIGH confidence**

- Quote nesting in config (dbt1000) — use single quotes outside: `warn_if='{{ "text" }}'`
- Static analysis errors in `analyses/` files (dbt0209, dbt0404, or other codes < 1000) — analyses are optional query files, not production models. The correct fix is to add `{{ config(static_analysis='off') }}` at the top of the analysis SQL file. Do **not** rewrite the SQL or remove content — just disable static analysis for that file.

### Category B: Guided Fixes (Need Approval)
**Can fix with user approval — show diffs first**

- Config API deprecated (dbt1501) — `config.require('meta').key` to `config.meta_require('key')`
- Plain dict `.meta_get()` error (dbt1501) — `dict.meta_get()` to `dict.get()`
- Unused schema.yml entries (dbt1005) — remove orphaned YAML entries
- Source name mismatches (dbt1005) — align source references with YAML definitions
- YAML syntax errors (dbt1013) — fix YAML syntax
- Unexpected config keys (dbt1060) — move custom keys to `meta:`
- Package version issues (dbt8999) — update versions, use exact pins. `dbt1065` package compatibility warnings (e.g. `Package '<package_name>' requires dbt version [>=1.2.0, <2.0.0]`) are not errors — autofix handles package upgrades. If `dbt1065` warnings persist after autofix, no manual action is needed.
- SQL parsing errors — suggest rewriting the logic (with user approval), or set `static_analysis: off` for the model
- Deprecated CLI flags (dbt0404) — if the repro command uses `--models/-m`, replace with `--select/-s`
- Duplicate doc blocks (dbt1501) — rename or delete conflicting blocks
- Seed CSV format (dbt1021) — clean CSV format
- Empty SELECT (dbt0404) — add `SELECT 1` or column list

### Category C: Needs Your Input
**Requires user decision — multiple valid approaches**

- Permission errors with hardcoded FQNs — ask if model, source, or external table
- Failing `analyses/` queries — ask if analysis is actively used

### Category D: Blocked (Requires Fusion Updates)
**Requires Fusion updates — not directly fixable in user code.**

When an error is Category D:
1. Identify it as blocked
2. Explain why (Fusion engine gap, known bug, etc