persona-detection

name	persona-detection
description	Intelligent project persona identification using priority chain detection with LLM and heuristic fallback

Persona Detection Skill

Classification: Inheritable (VS Code heir) | Feature Knowledge Activation: persona, know your customer, project type detection, welcome screen, sidebar persona Inheritance: heir:vscode

---

Purpose

Detect the most appropriate user persona for a workspace to personalize the Alex experience — sidebar branding, skill suggestions, and Active Context configuration.

---

Priority Chain (Highest to Lowest)

Priority	Source	Signal	Confidence
1	Focus	Active Pomodoro session topic	0.95
2	Goal	Stated session objective from goals.json	0.85
3	Phase	Current ROADMAP phase keywords	0.75
4	Project Goals	Learning goals from user-profile.json	0.70
5	Profile Cache	Saved projectPersona (< 7 days old)	cached
6	Profile + Workspace	Tech stack, expertise, file structure scoring	variable
7	Default	Developer fallback	0.50

Detection stops at the first confident match. Lower priorities only run if higher ones return null.

---

Available Personas (as of v5.6.8)

developer, academic, researcher, technical-writer, architect, data-engineer, devops, content-creator, fiction-writer, game-developer, project-manager, security, student, job-seeker, presenter, power-user

---

Workspace Scoring (Priority 6 Heuristics)

Three pattern types with distinct matching logic:

Pattern Type	Example	Match Method
Path (contains /)	src/, .github/workflows/	fs.pathExists() — directory must actually exist
Extension (starts with .)	.tex, .fountain	endsWith() on workspace entries
Filename	Dockerfile, package.json	Exact case-insensitive Set lookup

Critical rule: Never use bidirectional substring matching for workspace patterns. It causes false positives (e.g., .github/workflows/ matching any .github/ entry).

---

LLM Detection Path

When detectAndUpdateProjectPersona() is called (initialize/upgrade):

1. Detect technologies from file structure
2. Gather project context (directory tree, README, package.json, copilot-instructions.md)
3. Send structured prompt to LLM (prefers GPT-4o > Claude Sonnet > any)
4. Parse JSON response → match to existing persona or create dynamic one
5. Save to user-profile.json as projectPersona
6. Update Active Context persona field via updatePersona()

---

Active Context Integration

Persona detection updates the Active Context section in copilot-instructions.md:

## Active Context
Persona: Developer (90% confidence)
Objective: v5.7.1 — Avatar UI Enhanced + Architecture Validation Complete
Focus Trifectas: release-management, quality-assurance, documentation-quality-assurance
Principles: KISS, DRY, Quality-First
Last Assessed: 2026-02-15 — v5.7.1

What gets updated:

• Persona: Name + confidence (e.g., "Developer (90% confidence)")
• Focus Trifectas: NOT auto-assigned during persona detection — managed independently via updateFocusTrifectas()

Why separate?

• Persona = WHO the user is (developer, writer, researcher)
• Focus Trifectas = WHAT I'm working on NOW (3 skills for current task)
• Focus changes frequently (per-session), persona changes rarely (per-project)

The welcome view displays the persona with confidence % and detection source (profile vs. project detection).

---

Adding New Personas

1. Add to PERSONAS array in personaDetection.ts with: id, name, bannerNoun, hook, skill, icon, accentColor, keywords, techStack, projectPatterns
2. Add persona ID to the LLM prompt's personaId enum
3. Add skill to skillNameMap in welcomeView.ts
4. Ensure matching skill exists in .github/skills/

Note: Focus Trifectas are NOT defined per-persona. They're managed independently based on current work context. 3. Add persona ID to the LLM prompt's personaId enum 4. Add skill to getSkillDescription() map and skillNameMap in welcomeView.ts 5. Ensure matching skill exists in .github/skills/

---

Known Pitfalls

Issue	Root Cause	Fix
Every Alex project shows DevOps	.github/ matched via substring	Use fs.pathExists() for path patterns (v5.6.8)
.github/ triggers power-user	Noise signal in every project	Removed from power-user patterns (v5.6.8)
Wrong persona cached	projectPersona in user-profile.json stale	7-day expiry + re-detect on upgrade

Synapses

• [.github/skills/heir-curation/SKILL.md] (High, Integrates, Forward) - "Persona detection ships to heir via inheritance"
• [.github/instructions/alex-core.instructions.md] (Medium, References, Forward) - "Active Context persona field updated by persona detection"
• [.github/skills/release-process/SKILL.md] (Medium, Validates, Forward) - "Persona detection tested during pre-publish"