This document defines the standard pattern for complaint pages so they remain clinic-speed, consistent, and “office-ready.”

Requirements capture (physician + admin)#

Physician (Primary Care): “I’m in a 15-minute visit. I don’t need a textbook. I need: red flags, the 5–10 diagnoses I should pattern-match, what questions/exam maneuvers matter, when to order what, and what to tell the patient—plus follow-up timing.”

Admin (Physician Group Ops): “Across the group, we need consistency. Pages should be scannable, copy/paste-friendly, and aligned to local workflows: common orders, preferred referrals, and realistic follow-up intervals. We also need guardrails to reduce variation and minimize unnecessary imaging/antibiotics.”

Physician: “Also: patient language matters. The differential table should include the words patients use—‘burning,’ ‘pins and needles,’ ’locks,’ ‘giving way.’ That’s how I get to the right bucket quickly.”

Admin: “And it has to be maintainable. Each page should be short, modular, and easy to update. No walls of text. If we add a new complaint page, it should look identical in structure to the others.”

Audience and scope#

• Audience: outpatient adult/geriatric primary care clinicians.
• Default scope: adult and geriatric patients; exclude pediatrics and pregnancy/OB unless explicitly added.
• Local adaptation: when listing tests/meds/referrals, note “verify local protocol/formulary” if specifics vary.
• No PHI: never include patient-identifying details.

Complaint Page Standard (v2)#

Content goals (what a PCP needs)#

Each page should enable a clinician to quickly answer:

1. Is this dangerous right now? (ED/urgent escalation criteria)
2. What are the likely buckets? (pattern recognition differential)
3. What should I ask/exam that changes management today?
4. What workup is appropriate now vs later (and why)?
5. What is the initial plan, by diagnosis?
6. What medication, at what dose, with what monitoring?
7. What follow-up interval and what return precautions?
8. What patient instructions can I paste?

Required structure (headings must match)#

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

1. ## One-liner
2. ## Quick nav (links to each section)
3. ## Red flags / send to ED
4. ## Key history
5. ## Focused exam
6. ## Differential (quick pattern recognition)
7. ## Workup
8. ## Initial management
9. ## Management by diagnosis
10. ## Follow-up
11. ## Patient instructions
12. ## Smartphrase snippets
13. ## Coding/billing notes (optional)

Differential table standard (pattern recognition)#

Always include two tables under ## Differential (quick pattern recognition):

• ### Common/likely (outpatient)
• ### Can't-miss / urgent

Each table uses these exact columns:

Rules:

• Prefer 5–8 rows for common/likely and 3–6 rows for can’t-miss.
• “Keywords patients use” should be natural language, not medical jargon.
• “Initial next step” should be a single action-oriented line (e.g., “no imaging; start PT + return precautions”).

Management-by-diagnosis standard (clinic-ready)#

Under ## Management by diagnosis, include diagnosis “cards” using:

• ### <Diagnosis name>
  • **Education**: 1–3 bullets; expected course; activity guidance; key reassurance/warnings.
  • **Treatment**: brief narrative + medication table when pharmacotherapy is central.
  • **Follow-up**: one line with timing + what to reassess + escalation/referral threshold.

Rules:

• Keep each diagnosis card scannable but complete.
• Include medication tables when pharmacotherapy is central to management.

Medication table standard#

When medications are part of management, include a table with these columns:

Column definitions:

• Drug: Generic name (brand if clinically relevant for patient recognition or formulary).
• Dose: Starting dose, titration if applicable, max dose. Include frequency.
• Contraindications: High-yield absolute/relative contraindications that change prescribing decisions.
• Monitoring: Labs, vitals, or clinical parameters to check and when.
• Cost: Approximate monthly cost tier: $ (<$20), $$ ($20–50), $$$ ($50–150), $$$$ (>$150). Note if generics available.
• Notes: When to prefer this agent over alternatives; special populations; key pearls.

Rules:

• Include first-line, second-line, and key alternatives (typically 3–6 rows).
• Cost tiers are approximate US cash/GoodRx prices; note “verify local formulary.”
• Avoid exhaustive lists—focus on agents a PCP would actually prescribe or need to recognize.

Follow-up and patient instructions (copy/paste ready)#

## Follow-up should include:

• A default reassessment interval (e.g., 1–2 weeks vs 4–6 weeks) and what to reassess.
• A short escalation list (“return sooner if …”).

## Patient instructions should be:

• Plain language, 4–8 bullets, suitable for after-visit summary.
• Include clear return precautions tied to red flags (without alarmist wording).

Smartphrase snippets#

Include 1–3 brief EMR-ready snippets under ## Smartphrase snippets:

• Focus on common documentation patterns for that complaint.
• Keep each snippet to 1–3 sentences.
• Include key elements: chief complaint pattern, pertinent negatives, plan summary.

Writing and formatting rules#

• Prefer bullets over paragraphs; most sections should be scannable in <60 seconds.
• Aim for a “two-screen” mental model:
  • Screen 1: Quick nav + red flags + differential table.
  • Screen 2: workup/management + patient instructions.
• Use consistent, outpatient-first language:
  • “Consider imaging if it will change management” (not “order MRI for everyone”).
  • “Reassess in X weeks” (not vague “follow up PRN”).
• Be explicit about what changes the plan today (history/exam/workup).
• No junior-level content: assume reader is a practicing physician; skip basic definitions and textbook explanations.

Workflow for updating or creating a complaint page#

1. Start from the archetype archetypes/complaint.md.
2. Draft the differential tables first (common/likely + can’t-miss).
3. Add history/exam bullets that specifically discriminate between rows in the table.
4. Write diagnosis cards for the top outpatient patterns with medication tables.
5. Add follow-up + patient instructions last (ensure they match the red flags and plan).
6. Add smartphrase snippets.
7. Quick QA checklist (below).

QA checklist (ship/no-ship)#

• No TODO placeholders.
• “Red flags” exist and are actionable.
• Differential tables exist with the standard columns and reasonable row counts.
• Workup section avoids routine low-value testing and explains “when to expand.”
• Management-by-diagnosis cards include education + treatment (with medication tables where appropriate) + follow-up.
• Medication tables include dose, contraindications, monitoring, cost, and notes.
• Patient instructions are plain-language and include return precautions.
• Smartphrase snippets are included.
• No PHI; no copyrighted pasted material; verify any local protocol assumptions.
• Content is senior-level: no basic definitions or textbook filler.