xianwen-bug-triage

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:

1. Check server/src/services/quest_service.rs for completion conditions
2. Verify server/src/services/intent_engine.rs intent parsing
3. Check frontend quest state in web-client/src/stores/quest.ts
4. 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:

1. Check NPC spawn data in server/npcs/ config files
2. Verify NPC location logic in server/src/services/npc_service.rs
3. Check movement constraints in server/src/services/movement_service.rs
4. 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:

1. Check asset registration in web-client/src/assets/
2. Verify image mapping logic in components
3. 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:

1. Check server/src/services/combat_service.rs
2. Verify web-client/src/components/CombatPanel.vue
3. 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:

1. Check responsive breakpoints in component CSS
2. Verify WebSocket connection state
3. Check event handler bindings
4. 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:

1. Check server/src/services/sect_service.rs
2. Verify server/src/db/sect_repo.rs data
3. Check frontend web-client/src/stores/sect.ts
4. Verify migration applied correctly

Screenshot Analysis Protocol

When user shares a screenshot:

1. Read the image using the Read tool
2. Identify the specific UI state and error indicators
3. Cross-reference with the relevant Vue component
4. Check both frontend state and backend API response
5. 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:

1. Test the specific reported scenario
2. Check for similar patterns in related features
3. Verify no regression in adjacent systems
4. If database-related: check if existing player data needs migration