Content
71%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 an efficient, highly actionable operator's manual for a complex API, with executable code, hard-won gotchas, and a sequenced checklist with a self-critique step. Its main weakness is bundle integrity: the docs/ files it declares MANDATORY (interpretation guide, report templates, examples) do not exist in the bundle, undermining both navigation and workflow completeness.
Suggestions
Fix reference integrity: either add the missing docs/ files (alphagenome-api.md, interpretation-guide.md, report-templates.md, examples/*) to the bundle or repoint the References section to wherever they actually live, since steps 5 and 6 of the workflow are MANDATORY reads of these files.
Consolidate the uv usage rule into one section (it currently appears in Prerequisites, Core Rules, and Environment Setup) and move the Splicing Zoom Strategy detail out of the References list into the referenced script's documentation.
Add a short executable snippet or command line for the visualization step (Step 4) — e.g., the actual `uv run scripts/visualize_variant_effects.py ...` invocation — so the checklist steps don't depend solely on the missing docs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, hard-won operational knowledge ("Convert boolean masks to integer indices using np.flatnonzero(mask)", GTF column capitalization, "score_variant does NOT accept ontology_terms"), which Claude could not know. Not 5 because the `uv run` rule is repeated in Prerequisites, Core Rules, and Environment Setup, and the nested "Splicing Zoom Strategy" bullets under References restate detail that belongs with the referenced script. | 4 / 5 |
Actionability | The Broad Discovery Scan is a complete, copy-paste-ready executable block (dotenv loading, client creation, scorer filtering, tidy/rank/print), and troubleshooting items give concrete fixes (e.g., "set UV_INDEX_URL=https://pypi.org/simple"). Not 5 because the Extended Search snippet is a fragment assuming prior state, and the visualization and multi-variant "spawn sub-agents" steps lack any inline executable guidance — they rely entirely on referenced materials, two of which are absent from the bundle. | 4 / 5 |
Workflow Clarity | An explicit 8-step sequenced checklist with MANDATORY markers and a genuine validation checkpoint ("Step 7: Self-Critique (view report.md to verify links & claims)"), plus an error-recovery-oriented troubleshooting section. Not 5 because most steps are one-line labels whose mechanics live in referenced docs, and the two MANDATORY documents the workflow depends on (interpretation-guide.md, report-templates.md) are not present in the bundle, leaving steps 5 and 6 underspecified. Not 3 because the sequence and at least one explicit feedback loop are present and this is not a destructive/batch operation requiring stronger validation. | 4 / 5 |
Progressive Disclosure | The References section is well-signaled with one-paragraph descriptions per entry and scripts referenced by relative path that do exist (scripts/lookup_gene_info.py, scripts/visualize_variant_effects.py, etc.). However, scored against the actual bundle: every docs/ path — docs/alphagenome-api.md, docs/interpretation-guide.md, docs/report-templates.md, and all docs/examples/* — is absent (the bundle contains only references/citation.bib and scripts/), so the MANDATORY interpretation guide and report templates are dead links and navigation breaks for the most critical materials. Not 4 because this is more than a minor organization gap; not 2 because the structure and signaling that exist are good and the scripts resolve correctly. | 3 / 5 |
Total | 15 / 20 Passed |