Content
90%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A lean, highly actionable CLI reference with executable commands throughout and real validation guidance (list-before-run, run_results.json inspection, selector-typo guards). It falls short of top marks only on structure: the validation steps are not consolidated into an explicit workflow, and some exhaustive lookup tables could be split into a reference file.
Suggestions
Add a short numbered 'Standard workflow' section consolidating the existing checkpoints (preview with `dbt list --select …` → run `dbt build` with warn-error-options → inspect `target/run_results.json` for failures), turning scattered validation guidance into an explicit feedback loop.
Move the exhaustive `--output json` key list and valid resource-type enumeration into a reference file (e.g. `references/list-output.md`) and keep a few common examples inline, slimming the main body toward quick-reference size.
State explicitly in the workflow that on `fail`/`error` status the next step is to re-run the failing node with `dbt build --select <node>` after fixing, closing the error-recovery loop the run_results.json section currently leaves implicit.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense tables and copy-paste command blocks with no explanation of concepts Claude already knows — preferences, a quick reference, and per-topic command snippets where every token earns its place. | 5 / 5 |
Actionability | Commands like "dbt build --select my_model --quiet --warn-error-options '{…}'" and "dbt show --inline \"select * from {{ ref('orders') }}\" --limit 5" are fully executable and cover the common cases (build, show, list, defer, vars, static analysis). | 5 / 5 |
Workflow Clarity | Validation checkpoints are present ("Use `dbt list` to preview what will be selected before running", run_results.json failure checks, warn-error-options for selector typos) but they are scattered across sections rather than presented as one sequenced run→verify→fix loop, so it falls between anchors 4 and 5. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with no bundle files to navigate, but exhaustive inline lists (all --output json keys, all valid resource types, full selector tables) push the body past quick-reference size where a one-level-deep reference file would fit anchor 5. | 4 / 5 |
Total | 18 / 20 Passed |