Skip to content

Create configuring-state-aware-orchestration Agent Skill - #101

Open
trouze wants to merge 4 commits into
mainfrom
88-sao-configurator-skill
Open

Create configuring-state-aware-orchestration Agent Skill#101
trouze wants to merge 4 commits into
mainfrom
88-sao-configurator-skill

Conversation

@trouze

@trouze trouze commented Apr 10, 2026

Copy link
Copy Markdown

resolves #88

Description

  • Adds a new agent skill that guides configuring State-Aware Orchestration (SAO) for dbt projects, covering the full workflow: discovery (via Admin API/MCP tools), model classification, YAML config generation, and Fusion validation
  • Supports both net-new SAO configuration and further optimization of existing SAO configs
  • Includes 7 reference files covering SAO fundamentals, job config extraction with lineage resolution, dependency analysis, model classification framework, YAML syntax for all config locations, iterative configuration workflow with effectiveness measurement, and Fusion validation
  • Recommends source freshness configuration (required for view sources, recommended for tables) to drive SAO metadata all the way upstream, and treats intermediate views as potential DAG control points rather than blanket-skipping them

Key design decisions

  • Defaults to updates_on: all to drive cost savings
  • Sources first in the iterative workflow — source freshness captures upstream metadata that increases SAO effectiveness
  • Views as leverage points — fan-out hubs and coherence points get build_after to throttle downstream churn, simple passthroughs are opted out
  • Job selector → lineage resolution — uses get_lineage to expand job selectors (e.g., +my_model+) into full model graphs, mapping job schedules to appropriate build_after intervals
  • MCP-driven effectiveness measurement — get_model_performance, get_model_health, and job run comparisons to track skip/reuse rates post-deployment

Checklist

@trouze trouze self-assigned this Apr 10, 2026
@trouze
trouze requested a review from a team as a code owner April 10, 2026 20:03
@will-sargent-dbtlabs

Copy link
Copy Markdown

@claude Do an adversarial review of this pr

@will-sargent-dbtlabs

Copy link
Copy Markdown

Of note, I use adversarial review against all my stuff all the time. Soooo powerful, and not a judgement

@trouze

trouze commented Apr 10, 2026

Copy link
Copy Markdown
Author

@will-sargent-dbtlabs no worries, I love it!

@will-sargent-dbtlabs

Copy link
Copy Markdown

Doesn't look like Claude took the bait. I'll read this manually monday

stg_customers ─┤── fct_order_summary
stg_products ──┘
```
Best candidate for `updates_on: all` — wait for all sources before rebuilding.

@patkearns10 patkearns10 Apr 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thought:
I can see this being an issue when there are many upstream refs and one of them is a slowly updating table. For example, maybe stg_products only update every other day in a smaller business. This means we are waiting to build fct_order_summary until someone on product updates product items, which is probably not what we want.
suggestion:
I wonder if there is a way to figure out where this might be a problem - maybe AI can read the source freshness or make an educated guess based on metadata about data update frequency to make a more informed decision around any vs all.


**If a source is a view:** `loaded_at_field` or `loaded_at_query` is **required** — Fusion treats views as "always fresh" without it.

**If a source is a table:** `loaded_at_field` or `loaded_at_query` is **recommended** — Fusion can detect freshness from warehouse metadata automatically, but explicit config improves accuracy.

@patkearns10 patkearns10 Apr 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue:
In internal analytics we just removed all of these -- it takes longer and cost money to query a loaded_at_field, whereas the metadata queries are free.

1. `list_jobs` → find deploy job "Nightly Marts Refresh" (runs daily at 6am)
2. `get_job_details` → extract `execute_steps: ["dbt build -s +fct_orders+"]`
3. `get_lineage` for `fct_orders` → returns: `stg_orders`, `stg_customers`, `int_order_enriched`, `fct_orders`, `report_daily_sales`
4. Now you know all 5 models run on a daily schedule → recommend `build_after: {count: 1, period: day}` as the baseline for this group

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question:
if you have a job scheduled at 5am daily and build_after 24 hours and assuming perfect timing:
day 1, 5am job runs.
day 2, 5am job doesnt run (build_after = 23:59). models skip.

Would build_after 23 hours make more sense to ensure it does run every 24 hours?


| Job Schedule | Suggested Starting `build_after` | Reasoning |
|-------------|----------------------------------|-----------|
| Every hour | `{count: 4, period: hour}` | Skip 3 out of 4 runs if data hasn't changed |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick:
Skip 3 out of 4 runs if data hasn't changed
In actuality this would be skip 3 out of 4 runs regardless, right?

| Job Schedule | Suggested Starting `build_after` | Reasoning |
|-------------|----------------------------------|-----------|
| Every hour | `{count: 4, period: hour}` | Skip 3 out of 4 runs if data hasn't changed |
| Every 6 hours | `{count: 12, period: hour}` | Skip one full cycle if data is stale |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick:
Skip one full cycle if data is stale
In actuality this would be skip 1 cycle each time, right?

@patkearns10

Copy link
Copy Markdown

This is awesome - would love to see it in action (especially with grabbing jobs schedules and iterating through models/folders. Super cool!
Commented with a couple questions / topics to discuss:

  • internal analytics uses updates_on: 'any' for everything.
  • build_after equal or greater than current job cadence?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[New Skill] SAO Configurator Skill

3 participants