Content
70%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.
The body is a well-organized, highly actionable overview of the Rill platform with an excellent validated workflow, but it is held back by repeated guidance (the duplicate-explore warning appears three times) and references to resource-specific instruction files that are neither named nor bundled. Adding a small YAML example per key resource type and concrete paths for the deferred documentation would lift it further.
Suggestions
Consolidate the duplicate-explore-dashboard guidance into one authoritative location (the Explores section or the pitfalls list) and reference it from the other spots, trimming roughly a paragraph of repetition.
Make deferred documentation resolvable: name the actual files/paths for the resource-specific instructions (or bundle them under references/) instead of vague pointers like "the metrics view instructions".
Add one minimal example YAML snippet for a model and a metrics view so the most common edits are copy-paste ready.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly platform-specific knowledge Claude would not already have, but it could be tightened: the duplicate-explore-dashboard warning appears three times ("Do NOT also create a stand-alone `type: explore` file", "Do not create a separate `type: explore` file", "Creating a duplicate explore dashboard"), and the expense/caution guidance for models is stated twice. This matches anchor 3 (mostly efficient, some unnecessary explanation) better than 4 given the duplication across a ~300-line body. | 3 / 5 |
Actionability | Guidance is concrete throughout: named tools with usage constraints ("`query_sql` for running SQL ... use `SELECT` statements with `LIMIT` clauses and low timeouts"), specific properties (`olap_connector:`, `managed: true`, `mode: read`, `timeseries:`), a CLI fallback (`rill validate`), and concrete limits ("up to 10 dimensions and up to 5 measures"). It falls short of anchor 5 because no example YAML/SQL snippets for any resource type are included. | 4 / 5 |
Workflow Clarity | The "Recommended workflow" gives a numbered 8-step sequence with pre-flight checks (write access, data access, OLAP mode), explicit per-stage validation ("At each stage, check if there is a parse or reconcile error"), an iterate-until-fixed feedback loop, and `wait_until_idle` to block on reconciliation. This matches anchor 5 (clear sequence, explicit validation steps, feedback loops for error recovery); it exceeds 4 because checkpoints are woven through the process rather than only at the end. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned and correctly defers detail ("The descriptions are high-level; you can find detailed descriptions and examples in the separate resource-specific instruction files"), but those references are not clearly signaled: they name no files or paths ("the metrics view instructions", "the instructions for model development", the `rill-metrics-view` skill) and no references/ bundle exists to back them. This matches anchor 3 (references present but not clearly signaled) rather than 4, where references would be mostly concrete and resolvable. | 3 / 5 |
Total | 15 / 20 Passed |