Series: Building a Modular Assessment Engine (7/10)
The expert module configures an AI chatbot that users can interact with after completing an assessment. Not a generic "ask me anything" bot — one that knows the user's assessment results and stays within professional boundaries. This post covers the prompt engineering, the behavior red lines, and the consistency problems that made early versions dangerous.
The Configuration Surface
The expert is configured through a single config command plus an avatar command:
assess expert config \
--name "Stress Coach" \
--role "Senior Workplace Psychological Counselor" \
--description "Helps you analyze stress sources and provides personalized advice." \
--style "Warm, empathetic, supportive, and inspiring" \
--welcome "Hi! I'm your stress coach. I can see your results across Workload, Role Stress, and Social Support. What would you like to discuss first?" \
--question1 "What do my scores mean?" \
--question2 "How can I reduce workload stress?" \
--question3 "How do I talk to my manager about this?" \
--theme "Warm" \
--kbText "Workplace stress is caused by..." \
--prompt "【Role】You are a senior counselor with 10 years of experience...
【Knowledge】Based on the user's assessment results...
【Communication】Warm, empathetic, uses guiding questions...
【Boundaries】1. Never provide medical or psychiatric diagnosis.
2. If user shows extreme distress, gently suggest professional help.
3. Keep responses under 200 words." \
--enable
assess expert avatar --url "/page/assets/img/avatar/a4.png" --enable
That's 12 parameters in one command. Omitting any of them leaves the assistant with a gap — no name, no welcome message, no behavior boundaries.
The Four-Element Prompt Framework
The --prompt field is the system prompt for the chatbot. It must contain four elements:
1. Role Definition
"You are a senior workplace psychological counselor with 10 years of experience in cognitive behavioral therapy and stress management."
Specific, not generic. "You are a helpful assistant" is useless. "You are a senior counselor with CBT experience" gives the AI a professional frame.
2. Knowledge Boundary
"Based on the user's Workplace Stress Assessment results, analyze their scores across Workload, Role Stress, and Social Support dimensions."
This tells the AI what it knows and what it doesn't. It knows the assessment results. It doesn't know the user's medical history. It doesn't have access to real-time data. The knowledge boundary prevents hallucination.
3. Communication Style
"Tone is warm, empathetic, and supportive. Use guiding questions. Avoid lecturing."
The style must match the --style parameter. If --style says "professional and rigorous," the prompt shouldn't say "casual and fun." Consistency between these two fields was a recurring bug — the AI would set --style "warm" but write a prompt that says "maintain professional distance."
4. Behavior Red Lines
"1. Never provide medical or psychiatric diagnosis.
- If user shows extreme negative emotions, gently suggest seeking professional medical help.
- Keep each response under 200 words."
Red lines are the most important element. Without them, the AI will happily diagnose depression, recommend medication, or give legal advice. Each red line is a specific, testable constraint.
The Welcome Message Dimension Problem
The welcome message must reference the assessment dimensions by name:
✅ "I can see your results across Workload, Role Stress, and Social Support."
❌ "I can see your assessment results."
Why? Because generic welcome messages feel impersonal. Naming the dimensions tells the user "I actually know your specific results, not just that you took some test."
The trap: the dimension names must come from the scale-dimensions reference, not from the plan agent's knowledge field. The plan agent might say "Workload" but the scale module might have created "Workload Intensity." The welcome message must use the exact name from the scale data.
The SKILL.md enforces this:
Welcome message dimension names MUST be read verbatim from the
scale-dimensionsreference## Scalestablenamecolumn. Never guess from knowledge.
The PATCH Problem
When modifying an existing expert configuration, the AI would frequently rewrite everything — new name, new role, new prompt — even when the user only asked to change the welcome message.
The fix: a [CURRENT] / [PATCH] protocol in the knowledge field:
[CURRENT]
name: Stress Coach
role: Senior Counselor
style: Warm, empathetic
welcome: Hi! I'm your stress coach...
question1: What do my scores mean?
...
[PATCH]
Update the welcome message to be more casual and friendly.
The rule: only modify what [PATCH] explicitly mentions. Everything in [CURRENT] must be preserved verbatim. The AI reads the current config, applies only the patch, and outputs the full config with the changes merged in.
This sounds obvious, but without explicit enforcement, the AI would "improve" the role description while updating the welcome message, or rewrite the behavior red lines because they "could be better phrased."
The Theme Mismatch
The expert has its own --theme parameter (same 12 presets as connect). The rule: it must match the connect/report theme.
If the assessment uses Noir (dark professional), the expert chat should also be Noir. A Fresh (light green) expert chat inside a Noir assessment feels like walking from a dimly lit room into a fluorescent-lit hallway.
The lookAndFeel field from the plan agent carries the theme, and the expert skill must extract it:
lookAndFeel: 'theme:Noir; look:dark professional...'
→ --theme Noir (not Fresh, not Warm, not whatever the AI thinks is "calmer")
The common failure: the AI decides that a stress assessment needs a "warmer" expert theme and overrides Noir with Warm. Now the assessment pages are dark blue and the chat is amber. Visual whiplash.
The Avatar Selection Logic
Nine preset avatars are available, each matching a professional archetype:
| ID | Style | Matches |
|---|---|---|
| 1 | Middle-aged doctor, white coat | Medical, health |
| 2 | Middle-aged male consultant, suit | Business, strategy |
| 3 | Young female teacher, warm | Education, learning |
| 4 | Young male, energetic | Fitness, motivation |
| 5 | Middle-aged male, formal | Legal, compliance |
| 6 | Middle-aged female mentor, casual | Career, coaching |
| 7 | Young female manager, sharp | Leadership, management |
| 8 | Tech engineer, minimal | Technical, IT |
| 9 | Young female, bright | Creative, lifestyle |
When the user doesn't provide a custom avatar URL, the AI must select from this list based on the --role and --style:
- Psychological counselor → avatar 4 (young, energetic) or 6 (female mentor, casual)
- Legal compliance trainer → avatar 5 (formal male)
- Leadership coach → avatar 7 (sharp female manager)
The AI must not skip the avatar command. An expert without an avatar displays a broken image icon in the chat interface.
The --enable Flag
The --enable flag on both config and avatar commands is a bare flag (no value). Its presence means true. Its absence means false.
# Enabled
assess expert config --name "Coach" ... --enable
# Not enabled (config exists but chat is disabled)
assess expert config --name "Coach" ...
The AI would sometimes write --enable true or --enable false. The CLI rejects both — it's a bare flag, not a key-value pair. This was a minor but frequent syntax error.
The Empty Expert Problem
The expert module only runs for consultation plan type. For assessment, exam, and report types, there's no expert task. But sometimes the AI would add an expert task anyway:
# Wrong — assessment doesn't include expert
planType: assessment
tasks:
- skill: form
- skill: scale
- skill: connect
- skill: report
- skill: expert # ← not allowed for assessment
- skill: share
The decision matrix prevents this: assessment maps to form→scale→connect→report→share (no expert). Only consultation includes expert. The plan agent's system prompt explicitly lists which modules each plan type allows.
Lessons Learned
Behavior red lines are not optional. Without explicit "don't do X" rules, the AI will diagnose, prescribe, and advise on things it shouldn't. Each red line must be specific and testable.
Dimension names in the welcome message build trust. "I see your results in Workload and Social Support" beats "I see your results" every time.
PATCH mode requires explicit preservation rules. The AI will rewrite everything if given the chance.
[CURRENT]/[PATCH]separation forces surgical changes.Theme consistency across modules is a lookAndFeel rule, not a style preference. The expert theme must match the assessment theme. No exceptions.
Avatar selection is part of the configuration, not an afterthought. An expert without an avatar is a broken feature, not a minor cosmetic gap.
Next: [The One-Click Pipeline — How one SSE stream orchestrates everything]
Top comments (0)