This document defines the standard pattern for problem pages—diagnosis-focused reference pages for ongoing condition management. Problem pages complement complaint pages by providing deep-dive content once a diagnosis is established.

Problem pages vs complaint pages#

Complaint pages answer: “Patient has chest pain—what could it be and what do I do?” Problem pages answer: “Patient has heart failure—how do I understand, manage, and educate about this condition?”

Audience and scope#

• Audience: outpatient adult/geriatric primary care clinicians
• Default scope: adult and geriatric patients; exclude pediatrics and pregnancy/OB unless explicitly added
• Assumed knowledge: reader is a practicing physician; skip basic definitions and textbook filler
• Focus: conditions where PCP is the primary manager (not diagnose-and-refer)
• Local adaptation: note “verify local protocol/formulary” when specifics vary
• No PHI: never include patient-identifying details

Required structure (headings must match exactly)#

Use these headings, in this order, on every problem page:

1. ## One-liner
2. ## Quick nav
3. ## Definition and epidemiology
   • ### Diagnostic criteria
   • ### Epidemiology
4. ## Pathophysiology
   • ### Mechanism (clinical understanding)
   • ### How to explain to patients
5. ## Clinical presentation
   • ### Characteristic symptoms
   • ### Physical exam findings
   • ### Red flags
6. ## Diagnostic workup
   • ### Initial evaluation
   • ### Confirmatory testing
   • ### When to refer for specialist workup
   • ### What NOT to order
7. ## Treatment
   • ### Goals of therapy
   • ### Non-pharmacologic management
   • ### Pharmacologic management
   • ### Patient counseling points
   • ### Monitoring and follow-up
8. ## Patient education
   • ### What is this condition?
   • ### What you can do
   • ### When to seek care
   • ### Questions to ask your doctor
9. ## Prognosis and monitoring
   • ### Expected course
   • ### Monitoring parameters
   • ### Complications to watch for
10. ## Special populations
    • ### Elderly/geriatric
    • ### Chronic kidney disease
    • ### Other populations
11. ## When to refer
    • ### Specialist referral criteria
    • ### Urgency levels
12. ## Smartphrase snippets
13. ## Related pages

Content depth requirements#

Problem pages must contain specific, actionable clinical details—not generic textbook content. Every section should pass the “would this change what I do in clinic?” test.

Specificity standards#

DO include:

• Specific numeric targets: “target A1c <7% for most, <8% if elderly/frail”
• Specific doses: “start metformin 500mg daily with dinner, increase by 500mg weekly to 1000mg BID”
• Specific intervals: “check BMP at 1-2 weeks after ACE-I initiation”
• Specific thresholds: “refer to nephrology if eGFR <30 or declining >5 mL/min/year”
• Real-world prescribing nuances: “metformin causes GI upset in 30%—start low, take with food”
• Actual patient language: “You can tell patients: ‘This medicine helps your heart pump more efficiently’”

DO NOT include:

• Vague language: “optimize glycemic control” ❌
• Generic advice: “start low, go slow” without specific doses ❌
• Unhelpful hedging: “follow up as needed” ❌
• Textbook filler: “diabetes is a chronic metabolic condition characterized by…” ❌

Example: Good vs bad content#

Bad (vague):

Start an ACE inhibitor. Monitor renal function. Follow up as needed.

Good (specific):

Start lisinopril 2.5-5mg daily (lower if elderly, CKD, or on diuretics). Check BMP at 1-2 weeks—expect Cr rise up to 30% (acceptable). Hold if K >5.5 or Cr rises >30%. Follow up in 2-4 weeks to assess BP response and tolerability; titrate to 10-20mg daily if tolerated.

Medication table standards#

Medication tables are central to problem pages. Include a table in ### Pharmacologic management with these exact columns:

Column definitions#

• Drug: Generic name (brand if clinically relevant). Format: “Lisinopril (Zestril)”
• Dose: Starting dose; titration schedule; maximum dose. Be specific: “2.5-5mg daily; titrate q2wk by 5mg; max 40mg”
• Contraindications: High-yield absolute/relative contraindications that change prescribing. Focus on common scenarios, not exhaustive package insert lists.
• Monitoring: Parameters and timing. Be specific: “Cr, K at 1-2 wks; repeat with dose changes”
• Cost: Monthly cost tier using $ symbols. Note generic availability.
  • $ = <$20/month
  • $$ = $20-50/month
  • $$$ = $50-150/month
  • $$$$ = >$150/month
• Notes: Clinical pearls—when to prefer this agent, common pitfalls, patient tips

Medication table rules#

• Include 3-6 agents per indication: first-line, second-line, and key alternatives
• Include renal dose adjustments with specific eGFR thresholds
• Include hepatic dose adjustments when relevant
• Clearly state if a medication requires specialist initiation
• Focus on agents a PCP would actually prescribe or need to recognize

Example medication table (Heart Failure HFrEF)#

Workup section standards#

The workup section must tell clinicians exactly what to order, how to interpret results, and what to do with abnormal findings.

Required elements#

1. Specific test names: “TSH, free T4” not “thyroid function tests”
2. Interpretation guidance: “BNP >100 suggests HF; >400 makes HF very likely; <100 essentially rules out HF”
3. What to do with results: “If TSH elevated with normal free T4, recheck in 6-8 weeks before treating”
4. In-office vs referral: “Spirometry available in most primary care offices; formal PFTs require pulmonology referral”
5. Turnaround times: “TSH results typically available same day; sleep study may take 2-4 weeks to schedule”
6. Cost considerations: “MRI costs $500-2000; reserve for specific indications”
7. False positives/negatives: “BNP can be falsely low in obesity; falsely elevated in CKD, AF”
8. Staging/classification: Include practical application, not just definitions

Example workup section (Heart Failure)#

Initial evaluation:

• BNP or NT-proBNP: BNP >100 pg/mL or NT-proBNP >300 pg/mL suggests HF; higher values = higher likelihood
• CBC: anemia worsens HF symptoms; identify and treat
• BMP: baseline Cr/K before starting ACE-I/ARB; identify CKD
• TSH: thyroid disease is treatable cause of HF
• ECG: identify AF, prior MI, conduction disease

Confirmatory testing:

• Transthoracic echocardiogram (TTE): essential for all new HF—determines EF (HFrEF vs HFpEF), valve disease, wall motion abnormalities
  • EF <40% = HFrEF (reduced); 40-49% = HFmrEF (mildly reduced); ≥50% = HFpEF (preserved)
  • Order “TTE with Doppler” to assess diastolic function
• Chest X-ray: cardiomegaly, pulmonary congestion, pleural effusions

When to refer for specialist workup:

• EF <35% (ICD evaluation)
• Suspected ischemic etiology without prior cath (coronary angiography)
• Valvular disease requiring intervention
• Refractory symptoms despite optimized GDMT

What NOT to order:

• Routine cardiac MRI (reserve for specific indications: infiltrative disease, arrhythmogenic cardiomyopathy)
• Serial BNP for routine monitoring (use clinical assessment instead)
• Coronary CT angiography in known HF (cath is preferred if revascularization considered)

Patient education writing guidelines#

The ## Patient education section must be written at an 8th-grade reading level and be suitable for copy-paste into after-visit summaries or patient portals.

Writing rules#

• Avoid medical jargon: Use “high blood pressure” not “hypertension”; “heart pumping problem” not “systolic dysfunction”
• If jargon is unavoidable, define it immediately: “Your ejection fraction (how well your heart pumps) is low”
• Use short sentences: Average 15 words or fewer
• Use active voice: “Take your medicine every day” not “Medication should be taken daily”
• Be specific and actionable: “Weigh yourself every morning before breakfast” not “Monitor your weight”
• Include numbers when helpful: “Call if you gain more than 3 pounds in one day or 5 pounds in one week”

Forbidden jargon list#

These terms should NOT appear in patient education sections unless immediately defined:

• etiology, pathophysiology, contraindicated, prophylaxis, idiopathic
• exacerbation, decompensation, refractory, titrate
• bilateral, unilateral, proximal, distal
• Any Latin/Greek medical terms

Example patient education section (Heart Failure)#

What is this condition? Heart failure means your heart isn’t pumping blood as well as it should. Think of your heart as a pump—in heart failure, the pump is weak or stiff. This causes fluid to back up in your body, making you feel tired and short of breath.

What you can do:

• Weigh yourself every morning before breakfast, after using the bathroom
• Write down your weight—bring the log to every appointment
• Limit salt to less than 2,000 mg per day (about 1 teaspoon)
• Limit fluids to 2 liters (about 8 cups) per day if your doctor recommends it
• Take all your medicines exactly as prescribed, even when you feel well
• Stay as active as you can—walking is good for your heart

When to seek care: Call your doctor’s office if:

• You gain more than 3 pounds in one day or 5 pounds in one week
• You feel more short of breath than usual
• You need more pillows to sleep or wake up gasping for air
• Your ankles or legs are more swollen than usual
• You feel dizzy or lightheaded

Go to the emergency room if:

• You have severe trouble breathing
• You have chest pain
• You faint or nearly faint

Questions to ask your doctor:

• What caused my heart failure?
• What is my ejection fraction (heart pumping strength)?
• What medicines should I be taking?
• How much salt and fluid should I have each day?
• What activities are safe for me?
• When should I call if I’m getting worse?

Pathophysiology section standards#

The pathophysiology section serves two purposes: (1) deepen clinician understanding of mechanisms that inform treatment, and (2) provide patient-friendly explanations for counseling.

Mechanism (clinical understanding)#

Focus on clinically relevant mechanisms—those that explain why treatments work or inform management decisions. Avoid textbook-level detail that doesn’t change practice.

Good example (HFrEF):

In HFrEF, reduced contractility leads to decreased cardiac output and compensatory neurohormonal activation (RAAS, sympathetic nervous system). While initially adaptive, chronic activation causes fluid retention, vasoconstriction, and cardiac remodeling—worsening HF over time. This explains why GDMT targets these pathways: ACE-I/ARB block RAAS, beta-blockers block sympathetic overdrive, and MRAs block aldosterone-mediated fibrosis.

Bad example:

Heart failure is characterized by the inability of the heart to pump sufficient blood to meet the metabolic demands of the body. The Frank-Starling mechanism describes the relationship between preload and stroke volume… [continues with textbook content that doesn’t inform treatment]

How to explain to patients#

Provide actual phrases clinicians can use in the exam room. Use analogies that resonate with patients.

Good example (HFrEF):

“Think of your heart as a pump. In heart failure, the pump is weak—it can’t push blood out as strongly as it should. When blood backs up, fluid leaks into your lungs and legs. The medicines we use help the pump work more efficiently and prevent fluid buildup.”

Good example (Atrial Fibrillation):

“Your heart has a natural pacemaker that keeps it beating regularly. In AFib, the top chambers of your heart quiver chaotically instead of beating normally. This makes your heart beat fast and irregularly. The main risks are stroke—because blood can pool and clot—and heart weakening over time.”

Cross-linking conventions#

Problem pages and complaint pages should link to each other in the ## Related pages section.

Link format#

## Related pages

- [Chest Pain (complaint)](../../complaints/cardio/chest-pain/) — symptom-based approach to chest pain differential
- [Atrial Fibrillation (problem)](../atrial-fibrillation/) — related cardiac condition often comorbid with HF

Rules#

• Use relative paths (starting with ../ or ./)
• Include (complaint) or (problem) label to clarify page type
• Include a brief description of what the linked page covers
• Links must be bidirectional: if page A links to page B, page B must link back to page A
• Link to all relevant complaint pages where this diagnosis appears in the differential
• Link to related problem pages for common comorbidities

Smartphrase snippet standards#

Include 2-4 smartphrase snippets covering common documentation scenarios. Each snippet should be 2-4 sentences and EMR-ready.

Required scenarios#

1. Stable/controlled: Document stable condition with key parameters and continuation of plan
2. Worsening/uncontrolled: Document worsening with key parameters and plan changes
3. New diagnosis: Document new diagnosis with initial workup and plan

Example smartphrase snippets (Heart Failure)#

Stable HFrEF:

HFrEF (EF 35%) on optimized GDMT with lisinopril 20mg, carvedilol 25mg BID, spironolactone 25mg. Euvolemic today—no orthopnea, PND, or edema. Weight stable at goal. Continue current regimen; f/u 3-6 months.

Worsening HFrEF:

HFrEF with volume overload—2+ pitting edema, 5 lb weight gain, increased dyspnea on exertion. Likely dietary indiscretion vs medication non-adherence. Increase furosemide from 40mg to 80mg daily, strict 2g Na diet, daily weights. Recheck in 1 week; if not improved, consider admission.

New diagnosis HFrEF:

New diagnosis HFrEF with EF 30% on TTE. Initiated lisinopril 5mg daily; will check BMP in 1-2 weeks. Discussed diagnosis, sodium restriction, daily weights, and warning signs. Cardiology referral placed for GDMT optimization and ICD evaluation. F/u 2-4 weeks.

Special populations standards#

The ## Special populations section must address specific adjustments for high-risk groups. This is not optional content—every problem page must include substantive guidance for elderly patients, CKD patients, and polypharmacy considerations.

Required keywords#

Each problem page’s special populations section must contain at least one keyword from each category:

Elderly/geriatric:

• elderly, geriatric, older adult, Beers, age >65, age >75

CKD:

• CKD, renal, eGFR, kidney, nephrotoxic

Polypharmacy:

• polypharmacy, drug interaction, multiple medications

Content requirements#

Elderly/geriatric:

• Beers criteria medications to avoid or use with caution
• Fall risk considerations
• Cognitive considerations (medication complexity, adherence)
• Dose adjustments for age-related changes (renal function, hepatic metabolism)
• Different treatment targets if applicable (e.g., less aggressive BP goals)

CKD:

• Specific eGFR thresholds for dose adjustments
• Medications to avoid at various CKD stages
• Nephrotoxic medications to avoid or monitor closely
• Adjusted monitoring intervals

Other populations (as relevant):

• Pregnancy and lactation
• Heart failure (if not the primary condition)
• Liver disease
• Drug-drug interactions common in the typical patient population

Example special populations section (Type 2 Diabetes)#

Elderly/geriatric:

• Target A1c 7.5-8% in older adults with limited life expectancy, frailty, or high hypoglycemia risk (per ADA guidelines)
• Avoid sulfonylureas (Beers criteria)—high hypoglycemia risk; prefer metformin, SGLT2-i, or GLP-1 RA
• Simplify regimens when possible—once-daily dosing preferred
• Consider cognitive status when choosing self-management expectations

Chronic kidney disease:

• Metformin: reduce dose to 1000mg max if eGFR 30-45; avoid if eGFR <30
• SGLT2 inhibitors: can initiate if eGFR ≥20 for cardiorenal benefit; glucose-lowering effect diminishes below eGFR 45
• GLP-1 RA: no dose adjustment needed; preferred in CKD for cardiorenal protection
• Sulfonylureas: avoid glimepiride/glyburide in CKD (active metabolites accumulate); glipizide safer if SU needed
• Insulin: reduce doses as eGFR declines (decreased renal clearance)

Other populations:

• Heart failure: prioritize SGLT2-i (dapagliflozin, empagliflozin) for mortality benefit; avoid TZDs (fluid retention)
• Polypharmacy: watch for drug interactions with metformin (contrast dye, alcohol) and sulfonylureas (CYP2C9 inhibitors)

Evidence and guideline citation standards#

Problem pages should be grounded in current evidence but translated into practical clinical application.

Citation rules#

• Reference landmark trials by name when they inform management: “per SPRINT trial, target SBP <120 in high-risk patients”
• Include NNT/NNH when available for major interventions to support shared decision-making
• Cite current guidelines with organization and year: “ACC/AHA 2022 HF guidelines”
• Distinguish between guideline recommendations and real-world practice when they differ
• Explicitly state when evidence is weak or conflicting

Example evidence integration#

Statin intensity selection (per ACC/AHA 2018):

• High-intensity (atorvastatin 40-80mg, rosuvastatin 20-40mg): ASCVD, LDL ≥190, or diabetes with multiple risk factors
• Moderate-intensity (atorvastatin 10-20mg, rosuvastatin 5-10mg): diabetes age 40-75, or 10-year ASCVD risk 7.5-20%
• NNT for high-intensity statin in secondary prevention: ~25 over 5 years to prevent one major cardiovascular event (per CTT meta-analysis)

Workflow for creating a problem page#

1. Start from the archetype: hugo new docs/clinical/problems/{system}/{condition}/index.md
2. Research current guidelines: Identify the most recent society guidelines (ACC/AHA, ADA, USPSTF, etc.)
3. Draft pathophysiology first: Ensure you understand the mechanism well enough to explain it simply
4. Build the workup section: Be specific about tests, interpretation, and next steps
5. Create medication tables: Include all required columns with specific values
6. Write treatment goals and non-pharm management: Be specific and actionable
7. Draft patient education: Write at 8th-grade level; test readability
8. Address special populations: Ensure elderly, CKD, and polypharmacy are covered
9. Add smartphrase snippets: 2-4 scenarios, 2-4 sentences each
10. Add cross-links: Link to relevant complaint pages and related problem pages
11. Run QA checklist: Verify all requirements before publishing

QA checklist (ship/no-ship)#

Before publishing any problem page, verify ALL of the following. If any item fails, the page should not be published until corrected.

Structure verification#

• All 13 required top-level sections present in correct order
• All required subsections present under each section
• Frontmatter includes title (string) and weight (integer)
• File path matches pattern: content/docs/clinical/problems/{system}/{condition}/index.md
• System directory has an _index.md file

Content specificity#

• No vague language: No “optimize,” “as needed,” “consider,” without specific guidance
• Numeric targets present: Treatment goals include specific numbers (A1c, BP, etc.)
• Medication doses complete: Starting dose, titration schedule, and max dose for all drugs
• Monitoring intervals specific: Exact timing for labs and follow-up (not “periodically”)
• Referral thresholds concrete: Specific criteria that trigger referral (not “if worsening”)
• Patient counseling includes actual phrases: Not just “counsel on adherence”

Medication tables#

• Table present in ### Pharmacologic management
• All 6 columns present: Drug, Dose, Contraindications, Monitoring, Cost, Notes
• 3-6 agents included (first-line, second-line, alternatives)
• Renal dose adjustments included with eGFR thresholds
• Cost tiers use $ notation with generic availability noted
• Notes column includes clinical pearls (when to prefer, pitfalls)

Workup section#

• Specific test names used (not categories)
• Interpretation guidance with numeric thresholds
• “What to do with results” guidance included
• “What NOT to order” section present with rationale
• Cost considerations for expensive tests

Patient education#

• Written at 8th-grade reading level (verify with readability tool)
• No medical jargon (or jargon is immediately defined)
• All 4 subsections present and substantive
• Actionable self-management steps (not vague advice)
• Clear warning signs with specific symptoms

Special populations#

• Elderly/geriatric section includes Beers criteria considerations
• CKD section includes specific eGFR thresholds
• Polypharmacy/drug interactions addressed
• Dose adjustments integrated into medication tables where appropriate

Evidence and guidelines#

• Current guidelines cited (within 2 years)
• Landmark trials referenced by name where relevant
• “When NOT to” guidance present for workup and treatment
• Conflicting evidence acknowledged where applicable

Cross-linking#

• Related complaint pages linked in ## Related pages
• Related problem pages linked
• Links use relative paths
• Links include brief descriptions
• Bidirectional links verified (linked pages link back)

Smartphrase snippets#

• 2-4 snippets present
• Each snippet is 2-4 sentences
• Covers: stable/controlled, worsening/uncontrolled, new diagnosis

Final checks#

• No TODO placeholders
• No PHI or copyrighted material
• Content is senior-level (no basic definitions or textbook filler)
• Hugo builds successfully with the new page
• Page appears correctly in navigation

Appendix: Body system directory structure#

Problem pages are organized by body system, matching the complaint page structure:

Appendix: Frontmatter reference#

---
title: "Condition Name"      # Required: Display name for the condition
weight: 10                   # Required: Sort order (lower = higher in nav)
bookHidden: false            # Optional: Hide from navigation
bookCollapseSection: false   # Optional: Collapse child pages
bookFlatSection: false       # Optional: Flatten child pages
bookToc: true                # Optional: Show table of contents
bookComments: false          # Optional: Enable comments
---

Only title and weight are required. Other fields are optional hugo-book theme settings.