Clinical Case-Ladder MCQ Add-On Tool

This is a separate add-on tool for building visual Case-Ladder MCQ DOCX and interactive HTML files. It does not replace MedCORE MCQ production, NRE50 rotation logic, or standard standalone MCQs.

What This Tool Does

It turns a structured JSON file into a colorful DOCX and an interactive HTML learning file containing:

One or more NRE-directed topics
A base clinical case for each topic
A decision-flow chart for each topic
Segment-style MCQs
Answer, discriminator, trap, and future alert for each segment
Manual review fields for human correction
Searchable/clickable segment reveal mode in HTML

Files

case_ladder_source.json
The editable source file. Humans or AI agents should edit this file to add, remove, or revise topics.
build_case_ladder_pilot.py
The generator. It reads the JSON source and creates the DOCX.
build_case_ladder_interactive.py
The interactive generator. It reads the JSON source and creates a standalone HTML learning file.
Case-Ladder_MCQ_Add-On_Pilot.docx
The generated sample DOCX.
Case-Ladder_Interactive.html
The generated interactive Case-Ladder file. Open it in a browser.
rendered/
Render QA outputs from the last visual check. These are optional review artifacts.

Design Note

The generator renders the main visual blocks as rounded PNG images and embeds them in the DOCX. The current visual mode is flat rounded cards: white card surfaces, true rounded corners, soft shadows, colored borders/accent rails, and colorful text.

The tradeoff: generated-card text is edited in case_ladder_source.json, not directly inside the DOCX card. To revise a generated visual block, edit the JSON and regenerate the DOCX.

The manual review fields remain normal editable Word content.

How To Regenerate The DOCX

Run this from the NRE workspace root:

/Users/ahmdzafr/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 "Case-Ladder MCQ Add-On/build_case_ladder_pilot.py"

Or run this from inside the tool folder:

/Users/ahmdzafr/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 build_case_ladder_pilot.py

The default output is:

Case-Ladder_MCQ_Add-On_Pilot.docx

How To Regenerate The Interactive HTML

Run this from the NRE workspace root:

/Users/ahmdzafr/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 "Case-Ladder MCQ Add-On/build_case_ladder_interactive.py"

Or run this from inside the tool folder:

/Users/ahmdzafr/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 build_case_ladder_interactive.py

The default output is:

Case-Ladder_Interactive.html

How To Use The Interactive HTML

Open Case-Ladder_Interactive.html in a browser.
Use the left sidebar to jump between topics.
Use search to filter topics, stems, traps, and alerts.
Open a segment card to see the MCQ options.
Use Show answer or Show all reasoning to reveal the answer, discriminator, trap, and future alert.
Use Mark done to track progress locally in that browser.
Use Print for a browser printout if needed.

How To Use As A Human

Open case_ladder_source.json.
Edit only the topic data: title, base case, decision flow, segments, options, answer, discriminator, trap, and future alert.
Keep the JSON structure valid.
Run the generator command.
Open the DOCX and manually review medical accuracy, NRE relevance, and wording.
Use the manual review table at the end of the DOCX to record corrections.

How To Use As An AI Agent

Before editing:

Treat this as an add-on project only.
Do not modify protected NRE workspace folders.
Do not replace MedCORE, NRE50, or existing MCQ production workflows.
Use the evidence hierarchy from the NRE workspace instructions.
Preserve explicit source confidence if evidence is mixed.

When generating content:

Read or sample the official syllabus and relevant NRE/PMDC recall or QBank material.
Create one base case per topic.
Make each segment change exactly one high-yield discriminator.
Keep each MCQ single-best-answer.
Include answer, discriminator, trap, and future alert.
Avoid random low-yield completeness.
Ask for human review before expanding into larger sets.

JSON Topic Shape

Each topic should follow this pattern:

{
  "title": "Topic Name",
  "accent": "emerald",
  "base_case": "One patient scenario...",
  "decision_flow": [
    {"label": "Key clue", "text": "Decision meaning"}
  ],
  "segments": [
    {
      "title": "Segment title",
      "tag": "diagnosis",
      "stem": "Question stem...",
      "options": [
        ["A", "Option A"],
        ["B", "Option B"],
        ["C", "Option C"],
        ["D", "Option D"]
      ],
      "answer": "B. Correct answer",
      "discriminator": "The answer-changing clue.",
      "trap": "Why the tempting wrong answer is tempting.",
      "future_alert": "One-line rule for next time."
    }
  ],
  "final_learning_rule": "The final exam rule for the topic."
}

Supported accent themes currently:

emerald
coral

Recommended Production Pattern

Use this tool slowly:

1 topic -> 1 base case -> 3 to 4 segments -> manual review -> regenerate DOCX

Do not mass-generate large sets without human review.

Quality Checklist

Before calling a generated Case-Ladder file ready:

The base case is clinically coherent.
Each segment changes one meaningful discriminator.
The answer changes only when the discriminator justifies it.
Distractors are plausible but clearly wrong.
The trap explanation is specific.
The future alert is short and reusable.
The DOCX has been opened or rendered for layout QA.

Locked