| name | xianwen-bug-triage |
| description | Triage and fix player-reported bugs in Xianwen Online. Handles screenshot analysis, NPC behavior issues, quest/task failures, UI glitches, combat problems, and image mapping errors. Use when user shares player feedback, screenshots, or reports game issues. |
Xianwen Bug Triage
Systematic workflow for handling player-reported bugs, extracted from 100+ bug-fix sessions.
Bug Categories (by frequency)
1. Quest/Task System (Most Common)
- Tasks not completing despite meeting conditions
- Quest tracker not updating
- Missing quest NPCs or dialogue triggers
- Quest description mismatch with actual requirements
Investigation flow:
- Check
server/src/services/quest_service.rs for completion conditions
- Verify
server/src/services/intent_engine.rs intent parsing
- Check frontend quest state in
web-client/src/stores/quest.ts
- Test the specific quest flow end-to-end
2. NPC Behavior Issues
- NPCs missing from expected locations (especially 引路先師)
- NPCs wandering into wrong faction territory
- NPC dialogue not matching context
- Missing NPC portraits/sprites
Investigation flow:
- Check NPC spawn data in
server/npcs/ config files
- Verify NPC location logic in
server/src/services/npc_service.rs
- Check movement constraints in
server/src/services/movement_service.rs
- Verify portrait mapping in
web-client/src/utils/npc-portraits.ts
3. Image/Asset Mapping
- Monster sprites showing wrong image
- NPC portraits not displaying
- Asset path mismatches
Investigation flow:
- Check asset registration in
web-client/src/assets/
- Verify image mapping logic in components
- Cross-reference server-side entity names with frontend asset keys
4. Combat System
- Cannot select combat target
- Combat cards not showing correctly
- Battle results not applying
- Boss fight issues (one-shot deaths, missing rewards)
Investigation flow:
- Check
server/src/services/combat_service.rs
- Verify
web-client/src/components/CombatPanel.vue
- Check technique/skill data integrity
5. UI/UX Issues
- Input blocked by toolbar
- Dialog overflow on mobile
- Navigation dots not rendering correctly
- Buttons not responding
Investigation flow:
- Check responsive breakpoints in component CSS
- Verify WebSocket connection state
- Check event handler bindings
- Test on mobile viewport (<=480px)
6. Sect/Faction System
- Cannot join/leave sect
- Sect panel showing empty
- Missing sect-specific techniques/dao paths
- Sect master position vacant
Investigation flow:
- Check
server/src/services/sect_service.rs
- Verify
server/src/db/sect_repo.rs data
- Check frontend
web-client/src/stores/sect.ts
- Verify migration applied correctly
Screenshot Analysis Protocol
When user shares a screenshot:
- Read the image using the Read tool
- Identify the specific UI state and error indicators
- Cross-reference with the relevant Vue component
- Check both frontend state and backend API response
- Reproduce by tracing the code path
Common Root Causes
| Symptom | Likely Cause |
|---|
| Feature works then resets | WebSocket reconnection losing state |
| NPC disappeared | NPC location query returning empty |
| Task won't complete | Intent engine not parsing player input |
| Empty dialog/panel | API response missing data, frontend not handling null |
| Disconnection/kick | Server panic or connection pool exhaustion |
| Description/option mismatch | AI response not matching available actions |
Fix Verification
After fixing:
- Test the specific reported scenario
- Check for similar patterns in related features
- Verify no regression in adjacent systems
- If database-related: check if existing player data needs migration
