| name | chart-review-build |
| description | Builds a chart-review guideline interactively, interviewing the reviewer in plain conversational text then drafting the guideline package once enough is known. Use when the user says "build a guideline with me", "help me design a chart review protocol", "I want to draft this iteratively", "walk me through creating a rubric", or starts the Studio Authoring Builder flow. Subsumes chart-review-author for interactive use: produces the same .claude/skills/chart-review-<task-id>/ package but step-by-step through conversation. Composes with chart-review-calibrate (validate the draft) and chart-review-improve (iterate after calibration).
|
| metadata | {"author":"chart-review-platform","version":"0.2.0"} |
Chart Review Guideline Builder
Interactive two-phase workflow: a structured conversation to gather the
protocol shape (Phase 1 — Gathering), followed by writing the YAML guideline
files once enough is known (Phase 2 — Drafting). Produces the same
.claude/skills/chart-review-<task-id>/ package as chart-review-author, but
step-by-step through conversation rather than in one batch.
When to use
- User says "build a guideline with me", "help me design a chart review
protocol", "I want to draft this iteratively", or "walk me through
creating a rubric"
- User is in the Studio Authoring Builder tab
- User wants to make decisions incrementally with recommendations and
trade-off explanations rather than hand over all materials at once
For batch authoring (user has all materials and wants a fast draft), prefer
chart-review-author instead.
Phase 1 — Gathering
Plain-text conversation with the reviewer. One question per turn. Present
numbered multiple-choice options with a recommendation and the one-sentence
reason it affects later decisions. Read any available references or samples
before asking — ground recommendations in what you find, not general advice.
See references/interview-guide.md for:
- Exact question format template (required — never deviate)
- The 7-phase gathering checklist and "satisfied" conditions
- The stop signal: when phases 1-5 are all satisfied, call
mark_drafted
Core principles:
- One question per turn. Never ask two things at once.
- Multiple choice when possible. Most protocol decisions have standard options.
- Always recommend. State your recommended answer in bold with a reason
BEFORE asking the reviewer to pick.
- Output shape first — pin output_shape BEFORE asking about criteria.
This is a hard gate; it reframes every later question.
- Stop gathering on time. When phases 1-5 are satisfied, don't keep digging.
Call
mark_drafted and write the files.
Phase 2 — Drafting
After mark_drafted(), write guideline files using the Write tool.
See references/file-templates.md for full templates for each file type.
Write these files, populating them from Phase 1 answers. Output goes to
.claude/skills/chart-review-<task-id>/ — all chart-review skills (draft
and locked) live at this canonical path. Draft maturity is signaled by
status: draft in meta.yaml, not by directory location. The legacy
.claude/skills/drafts/chart-review-<id>/ and guidelines/drafts/<id>/
locations are no longer read by the loader; writes there are invisible.
.claude/skills/chart-review-<task-id>/SKILL.md (skill stub).claude/skills/chart-review-<task-id>/meta.yaml (include status: draft
— the loader returns drafts with their status, and UI gates LOCK and
other actions on the flag).claude/skills/chart-review-<task-id>/references/criteria/<field_id>.md
— one markdown file per atomic criterion, with YAML frontmatter +
body sections (## Definition, ## Extraction guidance, ## Examples,
Failure modes). NOT pure YAML, NOT a multi-field blob with nested
fields[]. One field, one file..claude/skills/chart-review-<task-id>/references/code_sets/<id>.yaml
(only if reviewer supplied codes).claude/skills/chart-review-<task-id>/references/keyword_sets/<id>.yaml
(only if reviewer supplied keywords).claude/skills/chart-review-<task-id>/references/edge_cases/<id>.yaml
(only if reviewer flagged edge cases — one file per edge case)
One Write per file. Don't Write meta.yaml then re-Write it with a tweak;
write it once with full content. After the first set of Writes, keep prose to
one sentence — the reviewer can see the document panel.
After the initial Write, respond to reviewer follow-ups (field edits, additions,
corrections) by Reading the affected file and Editing it precisely.
Validation gate
After writing all files (meta.yaml and references/criteria/*.md),
call the validate_package MCP tool
(mcp__chart_review_guideline_builder__validate_package) with the draft path.
If ok is false, do NOT declare "Done" — read each diagnostic in the
returned diagnostics array, fix the file at diagnostic.path per
diagnostic.message, and re-run validation. Iterate until ok: true.
A run with diagnostics is not a successful build; it's a half-finished
one. The user sees a "Done" message and assumes the package is loadable,
then hits ENOENT or a blank Studio page two clicks later.
Reviewer interaction in Phase 2
The reviewer can:
- Type a follow-up ("tighten the time window to 14 days") — Read the file,
Edit it, confirm briefly.
- Edit a YAML file directly — acknowledge the change in one sentence, continue.
- Ask to "add a code set" — Write the new file.
Universal references
- See
skills/chart-review/references/atomic-criteria.md for the atomicity
definition + seven-item authoring checklist + common violations and how to
split them. Required reading before drafting any Criterion. Apply the
pragmatic test ("would two reviewers giving the same answer mean they agree
on the same thing?") at every Criterion you propose to the user.
- See
skills/chart-review/references/lifecycle.md for the draft → locked
pipeline this skill feeds into.
Skill-specific references
references/interview-guide.md — required question format template,
the 7-phase gathering checklist with "satisfied" conditions, push-back
triggers (compound criteria, outcome+reason enums), and a worked
layered recipe for guideline-concordance rubrics (use whenever the
research question mentions concordance / adherence / NCCN / AHA / ADA /
CMS measures / USPSTF or names another clinical guideline)references/file-templates.md — full templates for SKILL.md, meta.yaml,
the per-criterion .md files (frontmatter + body sections), code_sets,
keyword_sets, and edge_cases. Required reading before any Write.references/examples.md — two worked walkthroughs (interactive from scratch;
handling a user YAML edit during Phase 2)
Hard rules (with reasons)
-
Every Criterion must be atomic per the seven-item checklist in
skills/chart-review/references/atomic-criteria.md. When the user proposes a
compound Criterion ("does the patient have X and Y?", "is it A unless B?"),
push back conversationally: surface the split, name the two atomic Criteria,
and offer to express the combination as a derivation. Do not silently accept
a non-atomic Criterion — it breaks per-criterion κ, criterion-level rerun,
and adjudication granularity downstream.
-
Outcome + reason must be split. When a proposed enum bundles outcome
values with reason values (e.g. [met, not_met, refused, contraindicated, true_gap]),
surface the split: outcome is one criterion ([met, not_met]); reason is a
sibling criterion gated on is_applicable_when: <outcome> == 'not_met'.
Reason-shaped enum values to detect: refused, declined, contraindicated,
pending, outside_records, undocumented, true_gap, unknown. See
skills/chart-review/references/atomic-criteria.md §G and the worked
push-back dialogue in references/interview-guide.md. Do not silently
accept a compound enum even if the reviewer insists — capture their
intuition as a derivation if they want a single rolled-up label.
-
Output goes ONLY under .claude/skills/chart-review-<task-id>/. All
chart-review skills (draft and locked) live at this canonical path; draft
maturity is signaled by status: draft in meta.yaml. Always include
status: draft for new drafts. Locking is a status flip
(status: locked), not a directory rename — governed by
chart-review-calibrate. The legacy .claude/skills/drafts/chart-review-<id>/
and guidelines/drafts/<task-id>/ locations are dead and NOT read by the
reviewer; writing there produces invisible artifacts.
-
Per-criterion files MUST be markdown (.md) with YAML frontmatter,
not pure YAML. The reviewer's loader walks
references/criteria/*.md, parses frontmatter via the --- delimiters,
and reads the body for prose sections. A .yaml file at the same path
is silently ignored. See references/file-templates.md for the exact
shape.
Troubleshooting
Reviewer wants to skip output_shape: Push back once ("Output shape reframes
every later decision — locking it takes 30 seconds and saves rework."). If they
still insist, default to outcome-first and proceed.
Reviewer pivots mid-conversation: Accept the pivot. Drop your current
question; continue with theirs. Come back to skipped topics when needed.
Two answers contradict each other: Surface the contradiction in plain text:
"Earlier you said X but now Y — which is the rule and which is the exception?"
Reviewer says "draft now" before you'd planned: Do it. They have judgment.
Call mark_drafted and Write with what you have. Record unresolved gaps as
entries in the criterion's open_questions: frontmatter array — never as
# TODO comments in the body prose.
Reviewer wants to change output_shape after drafting: Ask first — "Changing
output shape rewrites every criterion. Want me to do that, or did you mean
something narrower?" If yes, Read every criterion file and rewrite each.
