Steps 1 to 3 are practices to apply to your own project. This step is a demo you can run as-is, to see how an agent troubleshoots a pipeline.

self-heal-demo is a local DuckDB practice project for troubleshooting with an AI agent:

1. It seeds realistic raw data.
2. You run it and see the failure.
3. You ask the agent to investigate.
4. It finds the root cause and proposes a fix.
5. You can then instruct it to apply the fix and rerun.

As you go, watch how the agent navigates the pipeline: which files it opens, how it follows lineage, and how it uses the asset context, MCP, and skills to get from a failed check to a specific cause.

Everything happens on your machine: no Bruin Cloud, no production credentials, no agent-dev environment, and nothing to clean up afterwards. The policy from Step 3 applies to your own project, not to this sandbox.

Run the demo

Create an isolated repository and scaffold the project. bruin ai skills all installs the local agent skills and creates a project AGENTS.md:

mkdir self-heal-practice
cd self-heal-practice
git init

bruin ai skills all
bruin init self-heal-demo

Stay in self-heal-practice. The commands below point into the new self-heal-demo/ directory.

Check that .bruin.yml has a DuckDB connection named self-heal-demo, then seed and validate:

bruin run self-heal-demo/demo-seed
bruin validate self-heal-demo/demo-pipeline

The seed should succeed and validation should report five valid assets. Stop here if either fails, because everything after it builds on this baseline.

Break it

This command is supposed to fail, so do not add || true:

bruin run --tag quality-check-investigate self-heal-demo/demo-pipeline

finance.order_margin
└── net_amount.positive - column 'net_amount' has 1 non-positive values

Hand it to the agent

The quality-check-investigate demo run failed. Diagnose it without changing files,
rerunning assets, or changing data.

Use the failed-run output, the finance.order_margin asset definition, lineage, and
read-only queries. Return the failed check, the failing rows, the most likely cause
and the file it is in, the smallest change that would fix it, and a test plan.

It should arrive at this: order_margin.sql groups adjustments by customer_id instead of order_id. Orders 1003 and 1004 belong to the same customer, so the refund of -75 on order 1004 lands on both. Order 1003 has a gross amount of 40, comes out at -35, and fails the positive check.

The fix is one word in two places: group and join on order_id. Once the agent has applied it on a branch:

bruin validate self-heal-demo/demo-pipeline
bruin run --tag quality-check-investigate self-heal-demo/demo-pipeline

Then check the data rather than the exit code:

bruin query \
  --connection self-heal-demo \
  --description "Check for non-positive net amounts after the fix" \
  --query "SELECT order_id, net_amount FROM finance.order_margin WHERE net_amount <= 0;"

Expected result: no rows. A command that exits cleanly is not the same as data that is correct.

The template ships three more scenarios you can run the same way: duplicate-investigate, freshness-check, and schema-drift-check.