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.
A well-structured, domain-dense body that provides real executable Python patterns, a clearly sequenced workflow with a MEAT validation gate, and a genuinely useful gotcha list. The main shortfalls are mild redundancy in framing, illustrative placeholders in the code (empty hierarchy dict, undefined map_to_icd10cm), and the absence of an explicit error-recovery loop.
Suggestions
Trim the rhetorical framing in the intro ('much of that signal lives in the narrative note, exactly what OpenMed reads') and state the decision-support disclaimer once instead of repeating it in the intro, scope paragraph, and Edge cases.
Make the code fully executable: replace the empty illustrative `hierarchy` dict with a loader for the official V28 hierarchy file (parallel to the crosswalk/coefficient loaders), and either import `map_to_icd10cm` from the coding-icd10 skill or show its call signature instead of leaving it as an undefined stand-in.
Add an explicit feedback loop after the MEAT/negation check: e.g., 'if a candidate HCC lacks MEAT support or is negated, re-resolve assertion status and re-check supporting sentences before flagging as unsupported' — converting the one-way validation gate into a fix-and-retry cycle.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, versioned facts Claude cannot be assumed to know ("V28 dropped ~2,000 codes", hierarchy suppression, segment-specific coefficients, MEAT capture rules) and avoids explaining generic concepts. Minor trimmable padding remains: the rhetorical framing "much of that signal lives in the narrative note, exactly what OpenMed reads" and the decision-support disclaimer stated three times (intro, scope paragraph, Edge cases) push it below anchor 5's "every token earns its place" while staying above anchor 3. | 4 / 5 |
Actionability | Two concrete Python blocks (CSV crosswalk/coefficient loading, `apply_hierarchy`, `estimate_raf`, offset-based MEAT context extraction) give mostly executable guidance. It is not anchor 5 because the `hierarchy` dict is an empty illustrative placeholder ("illustrative; use the official V28 hierarchy file"), `map_to_icd10cm(ent["text"])` is an undefined stand-in ("your coding step"), and the CMS CSVs must be user-supplied — the gaps are explicitly signaled but keep the code from being copy-paste ready. | 4 / 5 |
Workflow Clarity | A clear 7-step sequence (Extract → Code → Map → Apply hierarchy → Sum coefficients → Attach MEAT evidence → Emit) with an explicit validation gate at step 6 ("No MEAT → flag as 'unsupported / needs clinician confirmation,' not a captured HCC") and negation resolution required before mapping. Not anchor 5 because there is no validate→fix→retry feedback loop and no explicit error-recovery path if a step yields unsupported or negated candidates. | 4 / 5 |
Progressive Disclosure | Well-organized single-file structure (When to use, Quick start, Workflow, Hand-off, Edge cases, Standards & references) with no bundle files and no references to nonexistent files — only external CMS URLs and companion skills. It sits at anchor 4 rather than 5 because at ~165 lines the crosswalk-loading detail and the nine-item gotcha list are candidates for one-level-deep reference files, though nothing is misfiled. | 4 / 5 |
Total | 16 / 20 Passed |