What this proves
I can structure an agent workspace around auditable healthcare support work instead of generic chat.
Healthcare Agent-Workspace Case Study
case-study · healthcare-support-specialist
Healthcare Support Specialist
A drop-in agent workspace for health-plan CSRs. Five staged contracts, verbatim quotes, and three output branches.
// hiring signal
Risk handled
A CSR assistant can paraphrase benefit language, answer out-of-scope questions, or skip the quote needed for review.
Evidence
Public repository, five-stage folder pipeline, verbatim KB quotes, section IDs, three output branches, and worked example runs.
// the pipeline
REP TYPES "Is my MRI covered?" · "Why was my claim denied with CO-197?" · "Does Ozempic need PA?"
- 01 intake normalize · entities · clarify-flag reads 00_question · glossary
- 02 classify intent: benefits / claims / PA / OOS reads intent_taxonomy · rep_persona
- 03 route intent + entities → KB section IDs reads _index.md
- 04 extract verbatim quotes · no paraphrase reads acme_kb/* sections
- 05 compose rep-facing answer · 3 branches reads voice_guide · rep_persona
05_compose · branch selector
KB pointer + verbatim quote + rep talk-track
most runs · 5 of the 7 fixtures
warm-transfer talk-track to the right team
network · eligibility · billing
question for the rep to ask the member
missing entities · ambiguous intent
// repository screenshot
One run, end to end.
A drop-in agent workspace for health-plan CSRs. A rep types a member question; the workspace returns the KB section, the verbatim passage, and a suggested talk track. The folder structure is the pipeline.
Why it exists
Member-services reps spend their day translating a benefit grid, a denial code, or a prior-auth policy into a sentence the member can use. The KB is already written. The hard part is routing to the right section and not paraphrasing the words that matter.
I work that seat at Health First Health Plans. This is the workspace I would want: section ID, quote, and a line the rep can actually say. The fictional payer, Acme Health Plan, keeps the artifact free of PHI and proprietary content.
What made it hard
The lazy version is one big prompt over a knowledge base. That fails when the
model softens after deductible, invents a denial code, or answers a
network question the workspace was never scoped to handle.
So I made it read-first. Separate folders, separate contracts, verbatim quotes with section IDs, and exactly one output branch per run: normal, out-of-scope, or needs clarification.
// ICM layer mapping
Five layers, on purpose.
The structure follows Singer's Interpretable Context Methodology: identity, shared resources, contracts, reference material, and per-run artifacts each get their own layer. A reviewer reads the stable layers once; only the run changes.
- Workspace identity one file orients any reader/ 00_workspace.md
- Shared resources stable per-stage contextshared/ intent_taxonomy.md · glossary.md · rep_persona.md · voice_guide.md
- Stage contracts 5 numbered folders · same 5-section schema01_intake/ … 05_compose/ contract.md · Purpose / Inputs / Process / Outputs / Failure modes
- Reference material the KB itself · canonical section IDsreference/acme_kb/ _index.md · benefits/ · claims/ · prior_auth/
- Per-run artifacts one directory per question · full stage chainruns/<run_id>/ 00_question · 01_intake … 05_compose-answer · _audit.md
// pragmatic decisions
Three trade-offs worth naming.
The short version: choice, reason, cost.
01
The pipeline IS the folder structure
Chose
Five numbered stage folders each carry a contract.md. AGENTS.md is the runbook. Any agentic CLI that loads project instructions can run a committed case.
Why
A reviewer can audit the pipeline by reading the folders. The structure is the spec.
Cost
Convention is the enforcement. If a stage skips part of its output contract, the next stage only sees weaker input.
02
Verbatim quoting at 04_extract, paraphrasing only at 05_compose
Chose
Stage 04 quotes KB passages with section IDs. Stage 05 turns the quote into rep language and preserves guardrails like 'after deductible,' network qualifier, and criteria gate.
Why
A benefit grid is not a vibe. The source quote and the rep line need to be auditable separately.
Cost
It is two stages instead of one call. The voice guards still need review; they are not a regex.
03
Three output branches: normal · out-of-scope · needs-clarification
Chose
05_compose returns exactly one branch: normal answer, out-of-scope transfer, or needs-clarification question.
Why
On a CSR floor, 'ask this follow-up' beats a confident wrong answer.
Cost
Three templates have to stay current with the payer's team boundaries. A fourth branch would need new fixtures.
// the stack
The stack.
- Markdown spec
- ICM methodology
- AGENTS.md runbook
- CLAUDE.md pointer
- Claude Code · drop-in
- Codex · Cursor · Aider compatible
- Anthropic prompt cache · warm-up
- Mermaid diagrams
- 5-stage pipeline
- 7 worked example runs
- Hand-authored Acme KB
- CMS SBC template
- WPC CARC/RARC
- CMS PA-policy guidance
- GitHub
- Claude Code
✦