From dbt-migration
Triages dbt-core to Fusion migration errors by classifying as auto-fixable, guided fixes, needs input, or blocked on engine updates. Runs dbt debug/compile to validate.
npx claudepluginhub dbt-labs/dbt-agent-skills --plugin dbt-migrationThis skill is limited to using the following tools:
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.
Conducts multi-round deep research on GitHub repos via API and web searches, generating markdown reports with executive summaries, timelines, metrics, and Mermaid diagrams.
Dynamically discovers and combines enabled skills into cohesive, unexpected delightful experiences like interactive HTML or themed artifacts. Activates on 'surprise me', inspiration, or boredom cues.
Generates images from structured JSON prompts via Python script execution. Supports reference images and aspect ratios for characters, scenes, products, visuals.
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.
By default this skill uses dbt compile to reproduce and validate errors. The command can be customized:
dbt build, dbt test --select tag:my_tag), use that insteadrepro_command.txt file exists in the project root, use the command from that fileBefore 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."
Run:
dbt debug
What to check in the output:
dbt debug fails:profiles.yml and credentials before proceeding. Migration triage can't begin until the connection works.dbt debug checks may not be relevant to the migrationdbt debug succeeds:Confirm the environment is healthy and proceed to Step 1.
That's fine — proceed to Step 1. But if connection errors appear later during classification, circle back and suggest running dbt debug.
Before classifying any errors, ensure the user has run dbt-autofix on their project.
Prompt the user to run dbt-autofix (a first-party tool maintained by dbt Labs that automatically fixes common deprecation patterns):
uvx --from git+https://github.com/dbt-labs/dbt-autofix.git dbt-autofix deprecations
Important: Wait for autofix to complete before proceeding with classification.
Before analyzing any migration errors, you MUST understand what autofix changed:
Review the git diff (if project is in git):
git diff HEAD~1
Read autofix logs (if available):
Key things to look for:
meta:?Why this matters: Some migration errors may be CAUSED by autofix bugs or incorrect transformations. Understanding what autofix changed helps you:
Do not proceed with classification until you understand autofix's changes.
Use the 4-category framework to triage errors. For the full pattern catalog see the Error Patterns Reference. For detailed category definitions see Classification Categories.
Can fix automatically with HIGH confidence
warn_if='{{ "text" }}'Can fix with user approval — show diffs first
config.require('meta').key to config.meta_require('key').meta_get() error (dbt1501) — dict.meta_get() to dict.get()meta:static_analysis: off for the model--models/-m, replace with --select/-sSELECT 1 or column listRequires user decision — multiple valid approaches
analyses/ queries — ask if analysis is actively usedRequires Fusion updates — not directly fixable in user code.
When an error is Category D:
Category D signals:
github.com/dbt-labs/dbt-fusion/issuespanic!, internal error, RUST_BACKTRACEnot yet implemented: Adapter::methodWhen classifying errors, check in this order:
site:github.com/dbt-labs/dbt-fusion/issues <error_code> <keywords> — Category D if open issue with no workaroundInclude autofix context at the start of your analysis:
Autofix Review:
- Files changed by autofix: X files
- Key changes: [brief summary]
- Potential autofix issues: [if any detected]
Format your analysis clearly:
Analysis Complete - Found X errors
Category A (Auto-fixable - Safe): Y issues
Static analysis in 3 analyses/ — Can disable automatically
Quote nesting in config — Can fix automatically
Category B (Guided fixes - Need approval): Z issues
config.require('meta') API change (3 files) — I'll show exact diffs
Unused schema entries (2 files) — I'll show what to remove
Source name mismatches (1 file) — Needs alignment with YAML
Category C (Needs your input): W issues
Permission error in model orders — Hardcoded table name - is this a ref or source?
Failing analysis — Is this actively used or can we disable it?
Category D (Blocked - Not fixable in project): V issues
MiniJinja conformance gap — Fusion fix needed (issue #1234)
Recording/replay error — Test framework issue, not a product bug
Recommendation: [What should happen next]
Before fixing anything, ensure you've reviewed autofix changes (see Step 1).
After classification:
Critical validation rule: After EVERY fix, re-run the repro command (see Repro Command Behavior) — NOT just dbt parse.
Handle cascading errors: Fixing one error often reveals another underneath. This is expected. Report new errors and classify them.
Track progress:
Progress Update:
Errors resolved: 5
Static analysis in analyses (auto-fixed)
Config API x2 (guided fixes - you approved)
Pending your input: 2
Permission error in orders
Analysis file decision
Blocked on Fusion: 3
MiniJinja issue (#1234)
Framework error (test infrastructure)
Next: [What to do next]
dbt parse alone for validation: Use the repro command (see Repro Command Behavior)dbt debug first: If you see connection or credential errors during triage, suggest running dbt debug to verify the environment