Content
75%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 highly actionable — executable commands, a complete flag table, jq filters, and validation steps — with a sensible overview-plus-references split. Its weaknesses are repetition of the registry-staleness argument across four sections (hurting token efficiency) and five dangling eval scenario links, plus a decision flow that is assembled from sections rather than presented as one validated sequence.
Suggestions
State the registry-is-stale/live-API-is-authoritative argument once (e.g., in Mindset) and cross-reference it from When to Use, anti-pattern #2, and Troubleshooting instead of re-explaining it in each place.
Remove or fix the Eval Scenarios section: the five links to evals/scenario-*/task.md point to files that do not exist in the bundle, breaking navigation.
Present the core flow as one ordered workflow (query with fetch-models.sh → filter by policy.state == "enabled" → validate with opencode run → only then set defaultModel) with an explicit recovery step if validation fails.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The registry-is-a-stale-cache argument is made at length in the Mindset section ("The model registry OpenCode ships with is a cache, not a source of truth..."), then repeated in When to Use ("may have been added since OpenCode's registry was last updated"), in anti-pattern #2 ("OpenCode's registry is a snapshot baked in at release time"), and again in Troubleshooting. There is no padding about concepts Claude already knows, so this sits at 'mostly efficient but could be tightened' rather than the more-than-minor trimming of anchor 2 or the minor-trim profile of anchor 4. | 3 / 5 |
Actionability | Guidance is copy-paste ready throughout: script invocations with flags ("scripts/fetch-models.sh --json", "--category powerful", "--picker-only"), a complete options table, the auth file path with re-auth commands ("opencode auth add github-copilot"), executable jq filters ("jq '.data[] | select(.policy.state == "enabled")'"), and a post-switch validation command ("opencode run 'Echo back: model working' && echo '✓ Model active'"). These cover the common cases; no pseudocode or missing steps. | 5 / 5 |
Workflow Clarity | The pieces of a sequence exist — Decision Framework criteria (context window, policy state, preview, capabilities), per-command vs. default switching with an explicit validation checkpoint, and a Troubleshooting section for error recovery. But the end-to-end flow (query → filter → select → set → validate) is never laid out as one ordered sequence, and there is no explicit 'if validation fails, do X' retry loop, leaving it at 'clear sequence with most checkpoints present' rather than anchor 5's explicit feedback loops. | 4 / 5 |
Progressive Disclosure | Structure is good: an overview body, details correctly split into two real reference files (references/manual-queries-and-workflows.md and references/troubleshooting.md, both verified present), a script in scripts/, and a references table with a 'When to Use' column giving clear navigation. It falls short of anchor 5 because the Eval Scenarios section lists five links to evals/scenario-1..5/task.md that do not exist in the bundle — a navigation defect that breaks the otherwise easy one-level-deep referencing. | 4 / 5 |
Total | 16 / 20 Passed |