Bullet-Proof, Except Bullets

Alex Streed merged PR #21671, a perfectly reasonable docs reorg with the emotional scope of a kitchen remodel that discovers the previous owner drywalled over a sink. The intent was solid: split a ~620-line prefect-dbt monolith into a slim landing page plus focused guides for install, runner, dbt Cloud, and legacy APIs, so the follow-up PrefectDbtOrchestrator guide would not be bolted onto the bottom like a spare bedroom made of plywood.

That part is good. Unfortunately, while moving the furniture, Alex found several load-bearing lies in the example and decided to preserve the house’s historic character by replacing them with new, more interesting lies.

The headline sin is the “bullet-proof retries” example whose dbt failures did not actually fail. run_dbt_commands had been creating PrefectDbtRunner(raise_on_failure=False), discarding the returned result, and then letting the task exit cleanly. A dbt node could explode, result.success could be false, and Prefect would still mark the task Completed like a toddler hiding behind a curtain. Alex had to add a commit literally titled examples(dbt): let dbt failures actually fail the flow. Nothing says enterprise-grade orchestration like discovering your failure-handling walkthrough has been handling failure by not handling it.

Then came the caching arc. To make the “automatic caching” claim real, the PR first cached the downloaded project path by task inputs. Codex pointed out that replaying a cached Path after the local directory is deleted is not caching; it is a séance. Alex replaced it with _project_cache_key, which folds PROJECT_DIR.exists() into the key. This sounds clever for about four seconds. First run: directory missing, key is exists=False, task downloads the project, result is cached. Later cleanup deletes the directory. Next run: directory missing again, key is still exists=False, Prefect replays the stale path to nowhere. The final merged code still has the whole boolean ouija board sitting in examples/run_dbt_with_prefect.py, confidently documented as the thing that prevents exactly the bug it preserves.

Even the marketing copy had to be walked back. The example promised “no YAML”, then remembered it programmatically writes a profiles.yml, so the slogan became “no hand-authored YAML.” A bold technical distinction for users who apparently hate YAML morally but are fine with a Python function manufacturing it in the other room.

The charitable read is that this PR did real cleanup. The docs structure is much better, the landing page is readable, and the follow-up orchestrator guide had a sane place to live. But the price of that order was watching a documentation PR accidentally become an integration test for every claim the old docs made, and several of those claims immediately fell down a flight of stairs.

Final Verdict: Cache Necromancer — splits docs cleanly, resurrects dead paths