cps

CPS: Clinical Problem Solving

Models the NEJM Clinical Problem-Solving format. Multi-persona diagnostic rounds apply Bayesian reasoning with likelihood ratios to systematically narrow a differential diagnosis, supported by textbook extraction and literature evidence.

Quick Start

/cps path/to/SCENARIO.md
/cps discover chest pain
/cps round ./case/45f-chest-pain 6
/cps review ./case/45f-chest-pain

Subcommands

Command	Purpose
`/cps SCENARIO.md`	Full 7-phase diagnostic workflow
`/cps discover [topic]`	Search for challenging cases from medical literature
`/cps round [case-dir] N`	Run additional round N on an existing case
`/cps review [case-dir]`	Review and update DDx for an existing case
`/cps retro [case-dir] [correct-dx]`	Retrospective evaluation after answer revealed

Full Workflow (`/cps SCENARIO.md`)

Copy this checklist and track progress:

- [ ] Phase 1: Case Intake & Setup → Validate (Red Flag History HARD GATE)
- [ ] Phase 2: Symptom Mapping & DDx → Validate (MNM coverage, Syndromic Screen)
- [ ] Phase 3: Initial DDx (Attending) → Validate (LR completeness, Rare Cause Search)
- [ ] Phase 4: Multi-Persona Rounds → Validate (Hypothesis Space Audit after EACH round)
- [ ] Phase 5: Evidence Search (Round 4)
- [ ] Phase 6: Bayesian Probability Update
- [ ] Phase 7: Final Diagnosis → Validate (convergence, MNM exclusion, unification test)

Validation: After each phase, complete the corresponding checklist from validation-checklist.md and append to VALIDATION.md. Phase 1 Red Flag History is a HARD GATE — must pass before proceeding.

Phase 1: Case Intake & Setup

Read the SCENARIO.md file
Extract a URL-safe slug from the case (e.g., 45f-chest-pain-dyspnea)

Initialize case directory:

python .claude/skills/cps/scripts/init_case.py "{slug}" "path/to/SCENARIO.md" --base-dir ./case

Parse structured data from the scenario: demographics, chief complaint(s), HPI, PMH, medications, vitals, PE, labs, imaging

Phase 2: Symptom Mapping & Textbook Extraction

Identify chief complaint(s) and map to textbook chapters using references/core/chapter-map.md
Read the relevant pre-distilled chapter references (typically 1-3). For example, chest pain + dyspnea:
- Read references/chapters/ch09-chest-pain.md
- Read references/chapters/ch15-dyspnea.md
Focus on each chapter's:
- Differential diagnosis framework and pivotal findings
- Likelihood ratios (LR+/LR-) for key findings
- Diagnostic algorithms and decision points
- Must-not-miss diagnoses and red flags
Always read references/chapters/ch01-diagnostic-process.md — it contains the core clinical reasoning methodology

Phase 3: Initial DDx — Round 1 (Attending Physician)

Adopt the Attending Physician (Internal Medicine) persona. See references/core/personas.md.

Write a problem representation: "This is a [age][sex] with [key PMH] presenting with [duration] of [chief complaint], associated with [key features], in the setting of [relevant context]"
Generate Top 10 DDx with pre-test probabilities:
- Use epidemiologic prevalence for the symptom in the relevant clinical setting
- Adjust for demographics (age, sex, risk factors)
- Flag all must-not-miss diagnoses regardless of probability — see references/safety/ddx-framework.md
- Use both anatomic and pathophysiologic (VINDICATE) approaches
For each diagnosis, list key supporting and opposing evidence from the scenario
Write output to round-1.md using the template from references/templates/output-templates.md

Phase 4: Diagnostic Testing — Rounds 2-3

Round 2: Radiology & Pathology

Activate personas based on available data (see references/core/personas.md):

Radiologist: If imaging data present (CXR, CT, MRI, US, etc.)
Pathologist: If lab/biopsy data present (CBC, CMP, UA, cultures, histology)

For each finding:

Provide structured interpretation
Look up the likelihood ratio — use references/core/bayesian-reasoning.md for common LRs
Apply LR to update the probability for each relevant diagnosis
Write output to round-2.md

Round 3: Subspecialty Consultation

Select 1-2 subspecialists based on the case presentation:

Symptom Category	Subspecialist
Chest pain, dyspnea, syncope, edema	Cardiologist
Cough, dyspnea, wheezing, hemoptysis	Pulmonologist
Fever, immunocompromised, travel	Infectious Disease
Headache, dizziness, delirium, focal deficits	Neurologist

Each subspecialist:

Provides domain-specific deep analysis
Applies specialty-specific clinical decision rules and risk scores
Recommends additional testing with expected LRs
Writes output to round-3.md

Phase 5: Evidence Synthesis — Round 4 (EBM Specialist)

Adopt the EBM Specialist persona. Two evidence sources:

WebSearch (always available)

Search for current evidence on the leading diagnoses:

"[diagnosis] [key finding] likelihood ratio" — find LR values
"[diagnosis] diagnostic criteria guidelines 2024 2025" — current guidelines
"[symptom] differential diagnosis evidence-based" — DDx evidence

robust-lit-review CLI (optional, requires .env)

If .env is configured with API keys:

lit-review review "[clinical question]" --target 50 --min-citescore 3.0

If .env is not configured or lit-review is not installed, note the limitation and proceed with WebSearch only.

For each piece of evidence found:

Assess level of evidence (systematic review > RCT > cohort > case series > expert opinion)
Extract relevant LR values, sensitivity/specificity data
Note any guideline recommendations that affect the DDx

Write output to round-4.md with an evidence summary table.

Phase 6: Bayesian Probability Update

After all rounds are complete, compile all likelihood ratios applied and run the calculator:

Prepare JSON input with all diagnoses, priors, and findings with LRs

Run the calculator:

echo '{"diagnoses": [...]}' | python .claude/skills/cps/scripts/lr_calculator.py

Review the output probability table
Write to probability-table.md

See references/core/bayesian-reasoning.md for formulas and common LR values.

Phase 7: Final Diagnosis — Round 5 (Diagnostic Conference)

Synthesize all rounds into the final diagnosis:

Write round-5.md as a Diagnostic Conference combining all persona perspectives
Determine the leading diagnosis with its post-test probability
Explain the reasoning chain: how each key finding shifted the probability
Document why not for each alternative in the Top 10
List must-not-miss diagnoses that were ruled out, and how
Provide teaching points from the case
Write FINAL_DX.md using the template from references/templates/output-templates.md

Discover Subcommand (`/cps discover [topic]`)

Search for challenging clinical cases to test the CPS skill.

Use WebSearch with queries from references/discovery/case-discovery.md:
- "clinical problem-solving" site:nejm.org [topic]
- "case records" site:nejm.org [topic]
- "case report" site:casereports.bmj.com [topic]
Present a table of found cases with: title, source, year, difficulty estimate
When the user selects a case, extract key information and format as SCENARIO.md
Offer to run the full CPS workflow on the formatted scenario

Difficulty levels: See references/discovery/case-discovery.md

Round Subcommand (`/cps round [case-dir] N`)

Add an additional diagnostic round to an existing case:

Read the existing scenario and all prior rounds from the case directory
Ask which persona should lead Round N (or auto-select based on case needs)
The new persona reviews all prior work and contributes fresh analysis
Update the probability table with any new LR applications
Write round-N.md to the case directory

Review Subcommand (`/cps review [case-dir]`)

Review and update an existing case:

Read SCENARIO.md and all round files
Identify gaps: missing LRs, unaddressed findings, overlooked diagnoses
Suggest additional rounds or evidence searches
Optionally regenerate FINAL_DX.md with updated reasoning

Retro Subcommand (`/cps retro [case-dir] [correct-dx]`)

Retrospective evaluation when the correct diagnosis is known (e.g., NEJM answer reveal):

Read SCENARIO.md, all round files, and VALIDATION.md from the case directory
Copy template from references/templates/retrospective-template.md
Complete Diagnostic Trajectory Analysis (Q1-Q4: was correct Dx in Top 10? Which pivot? Earliest data?)
Grade each phase A-F with specific failure modes (anchoring, knowledge gap, trigger not fired, etc.)
Complete Safety Check Retrospective table (should-have-fired vs did-fire)
Document Lessons Learned (new safety checks, reference gaps, workflow changes)
Write RETROSPECTIVE.md to the case directory
Write PERFORMANCE.md using template from references/templates/performance-metrics.md
Update case/PERFORMANCE_TRACKER.md with this case's metrics row

SCENARIO.md Input Format

Cases can be free-form text, but this structure is recommended:

# [Brief Case Title]

## Chief Complaint
[Main reason for presentation]

## History of Present Illness
[Narrative of the current episode]

## Past Medical History
[Comorbidities, surgeries]

## Medications
[Current medications]

## Social History
[Smoking, alcohol, occupation, travel]

## Family History
[Relevant family conditions]

## Vital Signs
T: __ HR: __ BP: __/__ RR: __ SpO2: __%

## Physical Examination
[System-by-system findings]

## Laboratory Data
[Labs with values and reference ranges]

## Imaging
[Imaging study descriptions and findings]

## Additional Studies
[ECG, PFTs, cultures, biopsies, etc.]

Reference Files (Sub-Module Structure)

Only core/ loads every run. Others load on demand to minimize context usage.

core/ — Always loaded (~386 lines)

File	Lines	Content
chapter-map.md	73	Symptom → chapter mapping
personas.md	149	8 persona definitions + activation rules
bayesian-reasoning.md	164	LR formulas + common clinical LR table

chapters/ — Load 1-3 per case (~80-120 lines each)

| chapters/ch01-ch33 | 33 files | Evidence-based DDx, LRs, algorithms per symptom |

templates/ — Load when writing output

safety/ — Load during validation

discovery/ — Load only for /cps discover

| case-discovery.md | 80 | Finding challenging cases from literature |

Scripts

Script	Usage
`init_case.py`	`python scripts/init_case.py "slug" SCENARIO.md` — initialize case directory
`lr_calculator.py`	`echo '{"diagnoses":[...]}' \| python scripts/lr_calculator.py` — Bayesian calculator
`extract_chapter.py`	`python scripts/extract_chapter.py 9 15` — re-extract from epub (optional, if epub present)

Safety Checks (Built from Case Retrospectives)

1. Red Flag History Checkpoint

When: Patient has unusual PMH (MI at <40, stroke at <50, aneurysm at <60) Action: Before generating DDx, DEMAND the etiology of the prior event. Do NOT assume the current event shares the same mechanism without evidence.

2. Syndromic Screen

When: Vascular disease etiology is unclear in a patient <50 Action: Trigger a comprehensive review beyond the chief complaint:

Complete skin exam (café-au-lait spots, neurofibromas, xanthomas, skin laxity)
Eye exam (Lisch nodules, lens subluxation, angioid streaks)
Vascular exam of all territories (pulse asymmetry, bruits)
Connective tissue screen (joint hypermobility, arm span, pectus)
3-generation family pedigree with inheritance pattern analysis

3. Rare Cause Search

When: Diagnostic findings (cath, imaging, biopsy) reveal a pattern not matching common DDx Action: WebSearch for comprehensive etiologic reviews before defaulting to the "most common" cause. The textbook chapters cover common diagnoses; rare causes need active search.

4. Hypothesis Space Audit

When: After EVERY round, before finalizing probabilities Action: Ask explicitly: "Is there a diagnosis NOT in our Top 10 that could explain ALL the findings?"

Bayesian updating can only redistribute probability among existing hypotheses
If the true diagnosis isn't in the DDx, no amount of LR application will find it
Force consideration of unifying diagnoses that explain seemingly unrelated findings

5. Genetic Pattern Recognition

When: Family history shows autosomal dominant premature vascular/cardiac disease Action: Consider genetic vasculopathies: NF1, Marfan, vascular Ehlers-Danlos, Loeys-Dietz, FMD, ACTA2

Key Principles

Evidence over intuition: Every probability shift must cite a likelihood ratio with source
Must-not-miss first: Always identify and explicitly rule out dangerous diagnoses
Bayesian discipline: Pre-test → apply LR → post-test. No skipping steps
Multi-perspective: No single persona owns the diagnosis — the conference decides
Transparent reasoning: Every round documents what changed and why
Hypothesis humility: The DDx is never closed. Unexpected findings demand expanding the hypothesis space, not forcing them into existing categories