| name | chart-review-methods |
| description | Drafts an academic-paper Methods section describing a chart-review study from a locked guideline plus cohort QA statistics. Use when the user says "write the methods section", "draft paper methods", "academic methods text", "methods paragraph for the manuscript", "describe the chart review for the paper", "STROBE methods", "RECORD methods", or is preparing to publish a study based on a locked phenotype protocol. Produces past-tense, third-person markdown text (~300-500 words) with the four-paragraph structure (protocol overview, criterion structure, reviewer process + reliability, limitations) — extended to a five-paragraph structure with a deployment-stage validation paragraph when a deployment-kappa.json report is provided. Composes with chart-review-calibrate (which produces the calibration kappa) and the cohort + sample-validation workflow (which produces the deployment kappa).
|
| metadata | {"author":"chart-review-platform","version":"0.2.0"} |
Methods Section Drafting
Takes a locked chart-review guideline plus cohort QA statistics and
produces a ready-to-paste Methods section for an academic manuscript. The
output follows journal conventions: past tense, third person, ~300-500 words,
with verbatim criterion definition quotes, reported κ values (from QA stats
only, never inferred), and a limitations paragraph. The output is a draft —
the author does final editing for journal voice and consistency with the rest
of the manuscript.
When to use
- User says "write the methods section", "draft paper methods", "academic methods
text", "methods paragraph for the manuscript", "describe the chart review for
the paper", or is preparing to publish a study
- User specifies a reporting checklist style: STROBE, RECORD, or CONSORT
- After calibration is complete and the guideline is locked
Do not use on draft guidelines. The Methods section describes the production
protocol; a draft has not yet been validated. If the user insists on drafting
from an unvalidated guideline, proceed with an explicit caveat in the output.
Inputs
- guideline_path: a locked guideline (
guidelines/<id>/) — verify that
meta.manual_version does not end in -draft
- qa_stats: path to a QA stats file (e.g.
cohorts/<id>/qa-stats.json)
OR confirmation to call the platform's computeQAStats endpoint. Required
fields: total_records, records_locked, records_validated,
by_criterion[<id>].kappa, kappa_n_shared, kappa_reviewers,
by_criterion[<id>].override_rate
- Optional —
deployment_kappa_path: path to a deployment-stage report
(e.g. cohorts/<cohort_id>/reports/<run_id>/deployment-kappa.json). When
provided, the Methods section gains a fifth paragraph reporting
deployment-stage agent-vs-reviewer agreement on a stratified sample of the
full deployment cohort. The JSON's per_criterion[] carries either
metric_type: "kappa" (with kappa, ci_lower, ci_upper) or
metric_type: "exact_match" (with rate, n_match, n_total); use the
metric the report records — don't substitute one for the other.
- Optional: word count hint (default ~400 words), journal style (STROBE /
RECORD / CONSORT), audience (clinical journal vs informatics journal —
affects technical depth of AI-assistance disclosure)
Procedure
-
Read the guideline end-to-end:
<guideline_path>/meta.yaml for task_type, review_unit, time_windows,
final_output, overview_prose, source_document_priority<guideline_path>/criteria/*.yaml for the rubric structure- Categorize criteria: leaf / derived / gated. Note which are primary (drive
the final output).
-
Read the QA stats. Capture: record count (locked + validated), reviewer
count (from κ pairs), per-primary-criterion κ with n_shared, per-criterion
override rate, any drift events worth mentioning.
If deployment_kappa_path was provided, also read it. The JSON has
cohort_id, n_validated_patients, n_total_sampled, overall_kappa
with 95% CI, and per_criterion[] with mixed metric types (kappa or
exact_match). The deployment cohort manifest at
cohorts/<cohort_id>/manifest.json gives the cohort size N and any
inclusion_criteria_text for paragraph 4 (block 5 of blueprint §7).
-
Draft the Methods section using the four-paragraph structure (or
five-paragraph structure if deployment_kappa_path was provided) —
see references/methods-template.md for sentence templates and fill-in
guidance per paragraph. Follow the writing conventions in
references/journal-conventions.md (past tense, third person, verbatim
quotes in double quotes, n_shared alongside κ, AI assistance disclosure).
-
Add journal-checklist items if the user specified a style (STROBE,
RECORD, CONSORT). See references/methods-template.md §"Journal-specific
additions" and references/journal-conventions.md for the expected items.
-
Output. Return the markdown text. No platform-side write — the user
pastes into their manuscript. If the user explicitly asks to save, write to
manuscripts/<guideline-id>-methods-<ts>.md.
Universal references
- See
skills/chart-review/references/reliability-metrics.md for the κ
interpretation context (which metric applies to which criterion type).
- See
skills/chart-review/references/lifecycle.md for the locked-phase
prerequisite this skill depends on.
Skill-specific references
references/methods-template.md — four-paragraph structure with word-count
targets, sentence templates, and fill-in guidance per paragraph; includes
journal-specific checklist additions (STROBE, RECORD, CONSORT)references/journal-conventions.md — writing conventions (voice, tense,
specificity rules, what to omit, κ interpretation language, limitations
paragraph conventions) with a word-count table by journal type
Hard rules (with reasons)
- The guideline must be locked. Methods text describes the production
protocol; reporting on a draft would misrepresent what was validated. If
meta.manual_version ends in -draft, warn the user and ask for
confirmation before proceeding.
- κ values come from qa_stats only — never inferred. Inferring κ from
non-quantitative descriptions would produce numbers the authors can't defend;
if κ is missing for a criterion, omit it rather than guess.
- Criterion definitions go in verbatim double quotes. Reviewers were trained
on the exact wording; paraphrasing would misrepresent what was abstracted.
- Don't hide a low κ. If a primary criterion has κ < 0.70, report the actual
value in Paragraph 3 and add a sentence to Limitations. Omitting a known
weakness would mislead peer reviewers and readers.
- Word count is a guideline, not a hard limit. Don't pad below 250 words
of real content; don't strip meaningful detail to hit a word count.
Quality over brevity.
Troubleshooting
QA stats missing entirely: Ask the user to either (a) provide a path to
qa-stats.json, or (b) confirm to call the platform's computeQAStats endpoint.
Without stats, the Methods section can't honestly report reliability.
κ is below 0.70 on a primary criterion: Report the actual κ. Add a Limitations
sentence: "Criterion [id] showed κ = [value]; disagreements were adjudicated by
a third reviewer for the primary analysis." Don't hide it.
Guideline still has TODOs in extraction_guidance: Flag this in your summary
to the user. A locked guideline shouldn't have TODO comments; if it does, the
protocol may not be ready for publication-grade reporting.
User wants a specific journal style not covered in the template: Apply the
general four-paragraph structure and note which STROBE/RECORD/CONSORT items
you added. For journal-specific formatting (numbered sections, subheadings,
etc.), note the conventions used and let the author apply house style.
