NREHub

MedCORE Generator Guide

This file is the durable operating guide for the current MedCORE DOCX generator.

1,574 words ~7 min

MedCORE Generator Guide

This file is the durable operating guide for the current MedCORE DOCX generator.

Use it before generating, debugging, or handing off MedCORE topic-sheet production.

Purpose

The generator creates MedCORE .docx sheets from structured JSON inputs.

It currently supports:

  • study sheets: main topic/conversion notes.
  • review sheets: review plans, rapid-fire tables, error-log tables, mini-mocks.
  • color variant: section-colored version.
  • black variant: grayscale/black-and-white print version.

The generator is designed for large-scale medical-note production, so the workflow must favor correctness, validation, render QA, and traceable source JSON.

Core Files

  • Main runner: Scripts/MedCORE Lesson/generate_daily_sheet.js

  • DOCX layout/template engine: Scripts/MedCORE Lesson/template.js

  • Sample advanced study input: Scripts/MedCORE Lesson/Next Level Sample ACS Input.json

  • Basic study input skeleton: Scripts/MedCORE Lesson/Day 21 Study Input.json

  • Review input example: Scripts/MedCORE Lesson/Day 21 Review Input.json

  • Legacy fixed-content script: Scripts/MedCORE Lesson/Day 21 Obstetrics Preeclampsia APH.js

The legacy script is guarded and no longer writes to a hardcoded old path, but production should prefer generate_daily_sheet.js.

Safe Command Pattern

Run commands from the NRE workspace root:

cd "/Users/ahmdzafr/Library/Mobile Documents/com~apple~CloudDocs/NRE"

Generate a color study sheet:

node "Scripts/MedCORE Lesson/generate_daily_sheet.js" study "INPUT.json" "OUTPUT.docx" --variant color --force

Generate a black-and-white study sheet:

node "Scripts/MedCORE Lesson/generate_daily_sheet.js" study "INPUT.json" "OUTPUT.docx" --variant black --force

Generate a review sheet:

node "Scripts/MedCORE Lesson/generate_daily_sheet.js" review "INPUT.json" "OUTPUT.docx" --variant color --force

Flags

  • --variant color Produces the colored MedCORE version.

  • --variant black Produces the grayscale/black-and-white laser-printer version.

  • --force Allows overwriting an existing DOCX.

If --force is omitted and the output exists, generation stops. This is intentional overwrite protection.

Safety Features

The current runner includes:

  • JSON parse failure reporting.
  • Required-field validation for study and review inputs.
  • .docx output enforcement.
  • Unknown flag rejection.
  • Variant validation: only color or black.
  • Output overwrite protection unless --force is present.
  • Atomic writing through a temporary file before final rename.
  • DOCX buffer sanity checks before writing.

The current template includes:

  • MedCORE header with Med regular and CORE bold.
  • Footer with topic/day context and page number.
  • Section title Reversed Pattern.
  • Color and black variant handling.
  • Grayscale-safe black mode.
  • Guarded optional blocks.
  • Callout no-split behavior to prevent stranded labels at page bottoms.
  • Review table geometry that matches input columns exactly.

Production Output Paths

Use the separate MedCORE production area. Do not use Planner/References for this workflow.

Color DOCX:

MedCORE Production/01 Color DOCX/{Subject}/{Chapter}/{Slug}.docx

Black DOCX:

MedCORE Production/02 Black DOCX/{Subject}/{Chapter}/{Slug}.docx

Source JSON:

MedCORE Production/03 Source JSON/{Subject}/{Chapter}/{Slug}.json

Render QA:

MedCORE Production/04 Render QA/{Subject}/{Chapter}/{Slug}/

Maps and indexes:

MedCORE Production/08 Indexes Maps/

Study JSON Shape

Minimum required fields for study mode:

{
  "topic": {
    "topicName": "ACS Next-Step Logic",
    "topicCode": "DAY 22",
    "category": "Medicine & Allied",
    "subcategory": "Cardiology",
    "colorIndex": 1
  },
  "scenario": {
    "vignette": "Clinical vignette text.",
    "pattern": "Recognition pattern text."
  },
  "trigger": "Recognition trigger text."
}

Recommended full study fields:

{
  "topic": {},
  "scenario": {},
  "trigger": "",
  "pathophysiology": [],
  "terminology": [],
  "comparison": {},
  "management": [],
  "examTraps": [],
  "trapPairs": [],
  "decisionMicroflow": [],
  "examConversion": {},
  "nrePattern": {},
  "fatalMiss": "",
  "keyNumbers": [],
  "recallPrompts": [],
  "evidenceTags": [],
  "pearls": [],
  "callouts": []
}

Study Field Details

topic:

  • topicName: visible title.
  • topicCode: usually DAY 22, SAMPLE, etc.
  • category: broad subject.
  • subcategory: system/chapter.
  • colorIndex: integer for color palette selection.

scenario:

  • vignette: exam-style clinical stem.
  • pattern: one-line recognition pattern.

pathophysiology:

  • Array of short paragraphs.
  • Use only MCQ-relevant mechanisms.
  • Use **bold** for key phrases.

terminology:

Array of 3-column rows:

[
  ["Standard term", "Synonym / variant", "Used in exam context"]
]

comparison:

{
  "title": "STEMI vs NSTEMI vs Stable Angina",
  "columns": ["STEMI", "NSTEMI", "Stable Angina"],
  "features": [
    {
      "feature": "ECG",
      "values": ["ST elevation", "ST depression or T inversion", "Often normal at rest"]
    }
  ]
}

Every features[].values array must have exactly the same number of entries as columns.

management:

[
  {
    "label": "Immediate ACS bundle",
    "urgency": "immediate",
    "items": [
      "Give aspirin unless contraindicated.",
      "Arrange reperfusion pathway."
    ]
  }
]

urgency: "immediate" uses the strongest badge color. Other urgency values use the secondary badge color.

examTraps:

[
  {
    "label": "Trap: wait for troponin",
    "text": "Do not wait for troponin when ECG already shows STEMI."
  }
]

trapPairs:

[
  {
    "correct": "Inferior STEMI with delayed PCI -> fibrinolysis if eligible",
    "trap": "Transfer and wait despite long PCI delay",
    "separator": "The stem gives early presentation and PCI center 3 hours away."
  }
]

decisionMicroflow:

[
  { "label": "Recognize", "text": "Ischemic chest pain plus ST elevation." },
  { "label": "Stabilize", "text": "Aspirin, analgesia, anticoagulation." }
]

examConversion:

{
  "trigger": "Crushing chest pain, sweating, and ST elevation.",
  "discriminator": "PCI center is too far for timely primary PCI.",
  "trap": "Waiting for troponin.",
  "action": "Give ACS bundle and choose fibrinolysis if eligible.",
  "futureAlert": "When ECG already says STEMI, the question is usually timing or contraindication."
}

nrePattern:

{
  "howTested": "How the exam tests this.",
  "disguise": "How the exam hides it.",
  "discrimination": "What clue separates the right answer."
}

keyNumbers:

[
  { "value": "90 min", "param": "Common target for door-to-balloon PCI" }
]

recallPrompts:

[
  { "prompt": "STEMI ECG plus long PCI delay means:", "answer": "Fibrinolysis if eligible" }
]

evidenceTags:

[
  { "label": "Past paper recall", "tier": "Tier 1", "note": "Repeated next-step pattern." }
]

pearls:

[
  { "label": "Do not give nitrates if", "answer": "Hypotension, RV infarct, recent PDE-5 inhibitor" }
]

callouts:

[
  { "type": "E", "text": "**Exam essential:** key point." },
  { "type": "W", "text": "**Why it matters:** key point." },
  { "type": "P", "text": "**Pro tip:** key point." }
]

Callout types:

  • E: Exam Essential.
  • W: Why It Matters.
  • P: Pro Tip.

Review JSON Shape

Minimum required fields for review mode:

{
  "topic": {
    "topicName": "Week 3 Review + Mini-Mock 50",
    "topicCode": "DAY 21",
    "category": "Review",
    "subcategory": "Month 1 Consolidation",
    "colorIndex": 3
  },
  "plan": [
    "Review task 1.",
    "Review task 2."
  ]
}

Optional review fields:

  • rapidFireReviews
  • errorTypes
  • mockQuestions
  • medcoreBuild
  • callouts

rapidFireReviews:

[
  {
    "title": "Week 1-3 Cross-Link Review",
    "columns": ["Anchor", "High-Yield Reminder"],
    "rows": [
      ["Acute abdomen", "Pain migration + anorexia + localized tenderness."]
    ]
  }
]

Every row must contain exactly the same number of values as columns.

errorTypes:

{
  "columns": ["Error Type", "What It Means", "Action"],
  "rows": [
    ["Knowledge Gap", "Rule not known.", "Revise exact topic."]
  ]
}

Every row must contain exactly the same number of values as columns.

mockQuestions:

[
  {
    "stem": "Question stem.",
    "options": ["A option", "B option", "C option", "D option", "E option"],
    "answer": "C",
    "explanation": "Why C is correct."
  }
]

Review-mode mock questions include answers in the same document. For separate MCQ production, use a dedicated MCQ pipeline, not this review-mode block.

Render QA

Every generated DOCX must be rendered before being treated as final.

Use the bundled document renderer when available:

"/Users/ahmdzafr/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3" \
"/Users/ahmdzafr/.codex/plugins/cache/openai-primary-runtime/documents/26.614.11602/skills/documents/render_docx.py" \
"OUTPUT.docx" \
--output_dir "MedCORE Production/04 Render QA/{Subject}/{Chapter}/{Slug}/{Variant}"

Inspect all rendered page-*.png files.

Check for:

  • Clipped text.
  • Overlapping text.
  • Broken tables.
  • Huge awkward blanks caused by preventable page breaks.
  • Stranded section labels or callout labels.
  • Header says MedCORE.
  • Footer shows topic/day context and page number.
  • Section title says Reversed Pattern.
  • Black variant uses grayscale only.

Black Variant Color Scan

For black-and-white files, inspect internal DOCX color values:

unzip -p "OUTPUT_BW.docx" word/document.xml word/header1.xml word/footer1.xml word/styles.xml 2>/dev/null \
| rg -o 'w:(fill|color)="[^"]+"' \
| sort \
| uniq -c

Expected values should be grayscale/white/auto only, such as:

  • 111111
  • 222222
  • 333333
  • BDBDBD
  • D5D8DC
  • E6E6E6
  • F2F2F2
  • F7F7F7
  • FCFCFC
  • FFFFFF
  • auto

If bright colors appear in a black variant, treat it as a generator bug unless the XML source clearly belongs to an allowed non-rendered artifact.

Troubleshooting

Cannot read valid JSON

  • The input file is missing, malformed, or has invalid JSON syntax.
  • Fix the JSON before trying again.

Input validation failed

  • Required fields are missing or empty.
  • Fix the JSON shape.
  • Do not bypass validation.

Output must be a .docx file

  • The output path must end in .docx.

Output already exists. Use --force to overwrite

  • This is intentional.
  • Add --force only when overwriting is expected.

Invalid variant

  • Use only --variant color or --variant black.

Unknown flag

  • Remove unsupported flags.

Render failure:

  • Confirm the DOCX was generated.
  • Confirm LibreOffice/render dependencies are available.
  • If rendering fails for environmental reasons, report clearly that visual QA could not be completed.

Awkward layout after render:

  • Fix JSON density first: shorten long rows, split overlong paragraphs, reduce excessive table prose.
  • Modify template.js only when the defect is systemic and reproducible.

Protected Behavior

Do not modify these without explicit permission:

  • System/Templates/MedCORE_Template.docx
  • System/SOPs/
  • System/Protocols/
  • Existing Planner/References/*.docx
  • Past Papers/
  • Exam Intel/
  • Syllabus/
  • QBank/

Do not use Planner/References for this MedCORE production workflow.

Production Rule

For each topic, create and preserve:

  1. Source JSON.
  2. Color DOCX.
  3. Black DOCX.
  4. Render QA images.
  5. Status update in TOPIC_PRODUCTION_MAP.md or a production log.

Do not mark a topic final until both DOCX variants render cleanly.