chart-review-build

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.

1. .claude/skills/chart-review-<task-id>/SKILL.md (skill stub)
2. .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)
3. .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.
4. .claude/skills/chart-review-<task-id>/references/code_sets/<id>.yaml (only if reviewer supplied codes)
5. .claude/skills/chart-review-<task-id>/references/keyword_sets/<id>.yaml (only if reviewer supplied keywords)
6. .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.