Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/technical/INTENT_INTELLIGENCE_IMPROVEMENT_REPORT.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

Intent Intelligence Improvement Report

Product: Dental Clinic Revenue Operating System (PRD-001)
Platform: PL-003 Agent Runtime (frozen architecture)
Date: 2026-07-05
Scope: Intent detection, capability routing, conversation understanding — no runtime redesign

---

Executive Summary

Acceptance Lab failures showed the Clinic Agent routing operational snapshots and business tools for Help and Instruction turns. This phase extends the existing intent model and intercepts guidance-only turns before PL-003 tool execution, while preserving operational query behavior.

Failure	Root Cause	Fix
"I need help" → operational snapshot	No Help intent; fell through to platform.general_assist / snapshot	ClinicUserIntent::Help + guidance-only short-circuit
"How create new lead" → empty-turn	Missing signals + vague-message block in goal planner	Instruction intent + step-by-step guidance (no tools)
Greetings broken (risk)	Over-broad conversational detection	Greeting vs Help split; greeting checked before unknown

---

1. Intent Classification Improvements

New taxonomy (ClinicUserIntent)

Extended the existing AssistantMode model without replacing it:

Intent	Tool execution	Example
Greeting	No	"Hello"
Help	No	"I need help", "What can you do?"
Instruction	No	"How do I create a lead?", "How create new lead"
Documentation	No	"Explain more", "Tell me about…"
Navigation	No	"Where can I see today's appointments?"
OperationalQuery	Yes	"Show today's appointments"
Reporting	Yes	"Show today's report"
AnalyticsRequest	Yes	"Which patients missed appointments this month?"
CrudRequest	Yes	"Create a lead named Ahmed"
FollowUp	Contextual	"Show it again" (replays last operational query)
Cancellation	No	"Cancel it"
Confirmation / Approval	No	"Do it", "Approve it"
Unknown / Clarification	No	"asdfgh"
MultiIntent	No	Mixed how-to + data query

Components

Component	Role
ClinicAssistantIntentCatalog	Phrase libraries (help, greeting, navigation, instruction, follow-up, unknown)
ClinicUserIntentClassifier	Priority-ordered classification + follow-up detection
ClinicGuidanceResponseBuilder	Guidance-only responses (steps, links, help menu)
ClinicCapabilitySignalFactory	Emits intent:* and meta:guidance_only; skips business signals for guidance

Safe Tool Policy

ClinicOperationsAgentService::converse() now:

1. Classifies intent via ClinicUserIntentClassifier
2. Resolves follow-up replay ("Show it again" → replays last operational user message)
3. Returns ClinicGuidanceResponseBuilder output when isGuidanceOnly() — never calls PL-003
4. Only operational/reporting/analytics/CRUD intents reach ClinicAgentOrchestrator

Guidance responses include metadata.guidance_only = true and metadata.tool_execution = false.

---

2. Capability Routing Improvements

Before

User message → PL-003 CapabilityMatcher → business capability → tool execution

Help / Instruction messages could match clinic.workflow.create_lead or platform.general_assist and execute get_operational_snapshot or get_admin_navigation.

After

User message → ClinicUserIntentClassifier
  ├─ Guidance-only? → ClinicGuidanceResponseBuilder (no PL-003)
  └─ Operational?    → ClinicAgentOrchestrator → PL-003 → tools

Signal enrichment (backup path)

If a message still reaches PL-003, metadata includes:

• intent: {value}
• guidance_only: true
• meta:guidance_only signal (no workflow/operation signals emitted)

Instruction quality

Instruction responses use existing ClinicAssistantWorkflowGuide with:

• Step-by-step admin UI paths
• Page hints and warnings
• Optional navigation cards (presentation links only — not get_admin_navigation tool execution)

Help quality

Help responses include:

• Capability summary
• Example prompts
• Suggested navigation shortcuts (create lead, calendar, invoices)

---

3. Regression Protection

Unchanged architecture

• No new runtime, planner, or orchestrator
• PL-003 AgentTurnOrchestrator unchanged in this phase
• Frozen platform modules untouched
• Existing capabilities retained for operational turns

Tests updated / added

Suite	Tests	Status
ClinicAgentIntentAcceptanceTest	15	Pass
ClinicAgentConversationRoutingTest	27	Pass
ClinicAgentTest	31	Pass
Total	73	Pass

Verified non-regressions

• Greetings → friendly reply, no snapshot
• Operational appointments → orchestrator + real schedule
• Daily report → structured report metadata
• Unpaid / revenue prompts → orchestrator
• Arabic no-show query → orchestrator
• LLM failure fallback → orchestrator for operational prompts

---

4. Acceptance Test Results

Scenario	Input	Expected	Result
Greeting	Hello	Friendly greeting, no tools	Pass
Help	I need help	Capabilities + examples, no snapshot	Pass
Help	What can you do?	Help menu, no snapshot	Pass
Instruction	How do I create a lead?	Step-by-step, no business tools	Pass
Instruction	How create new lead	Steps, no empty-turn	Pass
Instruction	How can I register a patient?	Patient registration steps	Pass
Navigation	Where can I see today's appointments?	Admin links only	Pass
Navigation	Where do I manage invoices?	Invoice page link	Pass
Operational	Show today's appointments	Orchestrator + schedule	Pass
Operational	Today's report	Daily report metadata	Pass
Follow-up	Cancel it	Acknowledgment, no execution	Pass
Unknown	asdfgh	Clarification prompt	Pass

Not yet automated in acceptance suite

Scenario	Status
Analytics: "Which patients missed appointments this month?"	Routed to orchestrator (manual verify recommended)
CRUD: "Create a lead named Ahmed"	Routed to orchestrator (manual verify recommended)
Follow-up: "Show it again" after operational turn	Replay logic implemented; add dedicated test
Follow-up: "Explain more" after instruction	Returns expanded steps from history

---

5. Remaining Weaknesses

1. Keyword-based classification — Multilingual coverage depends on catalog patterns; edge phrasing may misclassify.
2. CRUD vs Instruction boundary — "Create a lead named Ahmed" still routes to orchestrator; may need explicit CRUD guidance mode.
3. Analytics without live data tools — Complex analytics may fall back to general assist if no capability matches.
4. Follow-up context — Session replay uses conversation history only; no structured turn memory beyond PL-003 session state.
5. Multi-intent — Currently asks clarification rather than partial execution.

---

6. Future Recommendations (non-breaking)

1. Register guidance capabilities in PL-003 as conversational capabilities with empty workflows (defense in depth if product short-circuit is bypassed).
2. Extend CapabilityMatcher::isFollowUpTurn with "show again", "explain more" pronouns aligned with product classifier.
3. Add analytics capability for no-show / missed appointment month queries when data contract exists.
4. Structured turn memory — store last intent + response type in session for richer follow-ups.
5. Acceptance Lab automation — wire remaining manual scenarios into CI.

---

7. Files Changed

File	Change
Domain/Enums/ClinicUserIntent.php	New intent taxonomy
Support/ClinicUserIntentClassifier.php	Classification pipeline
Support/ClinicGuidanceResponseBuilder.php	Guidance-only responses
Support/ClinicAssistantIntentCatalog.php	Extended phrase libraries
Support/ClinicAssistantIntentDetector.php	Greeting/help detection aligned with catalog
Services/ClinicOperationsAgentService.php	Intent short-circuit + follow-up replay
Orchestration/ClinicAgent/ClinicAgentOrchestrator.php	Intent metadata + signals
Compatibility/Capabilities/ClinicCapabilitySignalFactory.php	Intent signals; skip business signals for guidance
Livewire/ClinicAssistantPanel.php	Surface guidance_only as conversational
lang/en/admin.php	Help/instruction/navigation copy
tests/Feature/ClinicAgentIntentAcceptanceTest.php	Acceptance Lab scenarios

---

Certification: Intent intelligence improved within frozen PL-003 architecture. Guidance turns no longer execute business tools. Operational turns unchanged.