06 troubleshooting agent issues

Coherence APM v4.2.0 Agent-Specific Issues and Solutions

This guide addresses problems specific to Coherence APM agent personas, their activation, behavior, and interactions.

🤖 Agent System Overview

Coherence APM v4.2.0 Architecture

• Unified Context Engineering: All agents use coherence orchestrator system
• Enhanced TTS Audio Experience: 5 TTS providers (system, piper, elevenlabs, discord, none)
• Native Sub-Agent Integration: Built on Claude Code's native architecture
• 67 Available Commands: Complete command suite for all personas
• Session Management: Automatic session archiving and recovery

Available Agents (11 Personas)

• Coherence Orchestrator (/coherence): Primary unified context engineering activation
• Coherence Orchestrator (/coherence): Legacy central coordination (redirects to coherence)
• Analyst (/analyst): Research and data analysis
• Architect (/architect): System architecture and design
• Design Architect (/design-architect): UI/UX architecture
• Developer (/developer): Code implementation and technical tasks
• Dev (/dev): Legacy developer command
• Project Manager (/pm): Project coordination and planning
• Product Owner (/po): Product requirements and priorities
• QA Engineer (/qa): Quality assurance and testing
• Scrum Master (/sm): Agile process facilitation

---

🚨 Agent Activation Issues

1. Persona Not Activating

Symptoms:

Agent command executes but persona doesn't activate
Response comes from generic Claude instead of specific agent
No voice notification plays
Agent doesn't follow persona-specific behavior patterns

Root Causes:

• Session management not initialized
• Missing persona configuration files
• Voice system not configured
• Session state corruption

Solution:

Immediate Diagnosis:

# Check if Coherence APM is properly initialized
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/

# Verify persona files exist (11 personas)
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/personas/
ls /mnt/c/Code/agentic-persona-mapping/.apm/agents/personas/*.md | wc -l  # Should be 11+

# Test TTS voice system (5 providers available)
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakDeveloper.sh "Test message"
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakOrchestrator.sh "Orchestrator test"

# Check TTS providers
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/
# Should show: discord.sh, elevenlabs.sh, none.sh, piper.sh, system.sh

Resolution Steps:

# 1. Initialize Coherence Orchestrator properly
cd /mnt/c/Code/agentic-persona-mapping
/coherence  # Primary initialization command

# 2. Verify session creation
ls -lt /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/ | head -3

# 3. Then activate specific agent
/developer  # Developer persona
/analyst    # Analyst persona
/architect  # Architect persona

# 4. Verify persona activation with TTS voice
# Should hear appropriate persona activation message

Prevention:

• Always use /coherence first to initialize the unified context engineering system
• Don't skip the orchestrator initialization sequence
• Verify TTS system during Coherence APM setup
• Use direct persona commands (/developer, /analyst, etc.)

---

2. Multiple Agents Responding

Symptoms:

More than one agent responds to commands
Conflicting advice from different personas
Session state confusion between agents

Root Causes:

• Improper session handoff
• Parallel operations not properly coordinated
• Session state not properly cleared

Solution:

Immediate Action:

# Clear session state
rm -f {{APM_ROOT}}/state/*.lock
rm -f {{APM_ROOT}}/session_notes/current_session.md

# Force session cleanup
/wrap --force

# Start fresh with single agent
/coherence
/handoff dev  # Single agent activation

Proper Handoff Procedure:

# Current agent should wrap up
/wrap

# Explicit handoff to new agent
/handoff architect

# Or use switch for complex transitions
/switch qa --compact-session

---

3. Agent Behavior Inconsistencies

Symptoms:

Agent doesn't follow expected behavior patterns
Responses don't match persona characteristics
Agent switches behavior mid-conversation

Root Causes:

• Corrupted persona configuration
• Session context interference
• Mixed agent state

Solution:

Verify Persona Configuration:

# Check persona definition files
cat {{APM_ROOT}}/agents/personas/developer.json
cat {{APM_ROOT}}/agents/personas/architect.json

# Validate JSON configuration
python3 -m json.tool {{APM_ROOT}}/agents/personas/developer.json

# Check for configuration corruption
find {{APM_ROOT}}/agents/personas/ -name "*.json" -exec python3 -m json.tool {} \; > /dev/null

Reset Agent Configuration:

# Backup current configuration
cp -r {{APM_ROOT}}/agents/personas {{APM_ROOT}}/agents/personas.backup

# Restore default configuration
cp -r {{APM_ROOT}}/config/default/personas/* {{APM_ROOT}}/agents/personas/

# Test agent activation
/coherence
/dev --test-mode

---

4. Voice Notification Issues

Symptoms:

Agent activates but no voice notification
Voice notifications are garbled or incomplete
Wrong agent voice plays for different personas

Root Causes:

• Text-to-speech system not configured
• Voice script permissions
• Audio system issues

Solution:

Voice System Diagnosis:

# Test text-to-speech system
espeak "Testing voice system" 2>/dev/null || say "Testing voice system" 2>/dev/null

# Check voice script permissions
ls -la {{APM_ROOT}}/agents/voice/*.sh

# Test specific agent voice
bash {{APM_ROOT}}/agents/voice/speakDeveloper.sh "Developer test"
bash {{APM_ROOT}}/agents/voice/speakArchitect.sh "Architect test"

Voice System Repair:

# Fix voice script permissions
chmod +x {{APM_ROOT}}/agents/voice/*.sh

# Install/update TTS system
# Linux:
sudo apt-get install espeak espeak-data
# macOS: Built-in say command should work

# Test voice configuration
{{APM_ROOT}}/scripts/test-voice-system.sh

Alternative Solutions:

# Disable voice if problematic
export VOICE_ENABLED=false

# Use visual notifications instead
echo "NOTIFICATION_MODE=visual" >> {{APM_ROOT}}/config/voice.conf

# Enable debug mode for voice issues
export VOICE_DEBUG=true

---

🔄 Session Management Issues

5. Session Handoff Failures

Symptoms:

/handoff command doesn't switch agents
Context lost during agent transitions
New agent doesn't have previous conversation context

Root Causes:

• Session serialization issues
• Context size too large
• File permission problems

Solution:

Handoff Diagnosis:

# Check session notes directory
ls -la {{APM_ROOT}}/session_notes/

# Check session file sizes
find {{APM_ROOT}}/session_notes/ -name "*.md" -exec ls -lh {} \;

# Verify write permissions
touch {{APM_ROOT}}/session_notes/test-write.md && rm {{APM_ROOT}}/session_notes/test-write.md

Handoff Repair:

# Use proper handoff sequence
/coherence  # Start with orchestrator
/handoff dev  # Explicit handoff

# For problematic handoffs, use switch with compaction
/switch architect --compact-session

# If handoffs consistently fail, archive large sessions
mv {{APM_ROOT}}/session_notes/*.md {{APM_ROOT}}/session_notes/archive/

---

6. Context Preservation Issues

Symptoms:

New agent doesn't remember previous conversation
Agent asks for information already provided
Context appears incomplete or corrupted

Root Causes:

• Session note corruption
• Context size limits exceeded
• File system issues

Solution:

Context Analysis:

# Check session note integrity
tail -20 {{APM_ROOT}}/session_notes/*.md

# Check for session file corruption
find {{APM_ROOT}}/session_notes/ -name "*.md" -exec head -1 {} \; | grep -v "^#"

# Verify context size
wc -c {{APM_ROOT}}/session_notes/*.md

Context Repair:

# Compact existing session
/switch dev --compact-session

# Or create fresh context summary
/wrap --create-summary
/coherence

---

⚡ Parallel Agent Issues

7. Parallel Operation Failures

Symptoms:

/parallel commands don't show expected Some parallel agents fail to execute
Coordination between parallel agents breaks down

Root Causes:

• Resource constraints
• Native sub-agent coordination issues
• System limitations

Solution:

Parallel System Diagnosis:

# Check system resources
nproc  # Available CPU cores
free -h  # Available memory

# Test parallel capability
/parallel-test --benchmark --verbose

# Monitor parallel execution
top -p $(pgrep -f claude)

Parallel Optimization:

# Adjust parallel worker count
export APM_PARALLEL_WORKERS=$(nproc)

# Reduce parallel load for resource-constrained systems
export APM_PARALLEL_WORKERS=2
export APM_WORKER_MEMORY=50M

# Test optimized parallel operation
/planning-architecture --workers=2

---

8. Native Sub-Agent Coordination Issues

Symptoms:

Parallel agents work independently without coordination
Results from parallel agents conflict
Sub-agents don't properly merge results

Root Causes:

• Coordination protocol issues
• Communication between sub-agents failing
• Result merging problems

Solution:

Coordination Analysis:

# Check coordination logs
tail -f {{APM_ROOT}}/logs/coordination.log

# Test sub-agent communication
{{APM_ROOT}}/scripts/test-subagent-coordination.sh

# Verify result merging capability
{{APM_ROOT}}/scripts/test-result-merging.sh

Coordination Repair:

# Reset coordination state
rm -f {{APM_ROOT}}/state/coordination/*.lock

# Use explicit coordination
/parallel-development --explicit-coordination

# Fall back to sequential mode if needed
export APM_FORCE_SEQUENTIAL=true

---

🎯 Persona-Specific Issues

9. Developer Agent Issues

Common Developer Problems:

Agent doesn't follow coding standards
Code suggestions are not contextual
Agent doesn't integrate with project structure

Solutions:

# Update developer persona configuration
cat > {{APM_ROOT}}/agents/personas/developer-custom.json << 'EOF'
{
  "persona": "developer",
  "coding_standards": "project-specific",
  "context_awareness": "high",
  "integration_mode": "seamless"
}
EOF

# Use custom developer configuration
/dev --config developer-custom.json

10. Architect Agent Issues

Common Architect Problems:

Agent focuses on low-level details instead of high-level architecture
Architectural decisions don't consider project constraints
Agent doesn't maintain architectural consistency

Solutions:

# Configure architect for high-level focus
echo "ARCHITECT_FOCUS=high-level" >> {{APM_ROOT}}/config/personas.conf
echo "ARCHITECT_CONSISTENCY=strict" >> {{APM_ROOT}}/config/personas.conf

# Load project constraints
/architect --load-constraints project-constraints.json

11. QA Agent Issues

Common QA Problems:

Agent doesn't understand project testing standards
Test strategies don't match project requirements
QA framework integration fails

Solutions:

# Configure QA for project-specific requirements
/qa --load-test-standards project-test-standards.json

# Update QA framework configuration
cat > {{APM_ROOT}}/config/qa-framework.json << 'EOF'
{
  "test_types": ["unit", "integration", "e2e"],
  "frameworks": ["jest", "pytest", "selenium"],
  "coverage_threshold": 80
}
EOF

---

🔍 Agent Diagnostic Tools

Comprehensive Agent Health Check

Built-in Diagnostics:

# Run complete agent health check
{{APM_ROOT}}/scripts/agent-health-check.sh

# Test individual agent activation
{{APM_ROOT}}/scripts/test-agent-activation.sh developer
{{APM_ROOT}}/scripts/test-agent-activation.sh architect
{{APM_ROOT}}/scripts/test-agent-activation.sh qa

Custom Diagnostic Commands:

# Test agent persona consistency
/dev --test-persona --verbose
/architect --test-persona --verbose
/qa --test-persona --verbose

# Test agent handoff capabilities
/coherence --test-handoffs --verbose

# Test parallel agent coordination
/parallel-test --test-coordination --verbose

Agent Performance Analysis

Performance Monitoring:

# Monitor agent activation time
time /dev --benchmark
time /architect --benchmark

# Monitor handoff performance
time /handoff architect --benchmark

# Monitor parallel agent performance
time /parallel-development --benchmark

Resource Usage Analysis:

# Monitor agent resource consumption
{{APM_ROOT}}/scripts/monitor-agent-resources.sh

# Analyze agent memory usage
{{APM_ROOT}}/scripts/analyze-agent-memory.sh

# Check agent CPU usage patterns
{{APM_ROOT}}/scripts/analyze-agent-cpu.sh

---

🛠️ Agent Recovery Procedures

Emergency Agent Reset

Complete Agent System Reset:

# Stop all agent processes
pkill -f apm
pkill -f claude

# Clear agent state
rm -rf {{APM_ROOT}}/state/agents/
rm -f {{APM_ROOT}}/state/*.lock

# Reset session management
rm -f {{APM_ROOT}}/session_notes/current_session.md

# Restart APM system
/coherence --recovery-mode

Individual Agent Reset

Reset Specific Agent:

# Reset developer agent
rm -f {{APM_ROOT}}/state/agents/developer.state
cp {{APM_ROOT}}/config/default/personas/developer.json {{APM_ROOT}}/agents/personas/

# Test agent reset
/dev --test-mode --verbose

Rollback to Previous Configuration

Configuration Rollback:

# Backup current configuration
cp -r {{APM_ROOT}}/agents/personas {{APM_ROOT}}/agents/personas.backup.$(date +%Y%m%d)

# Restore from backup
cp -r {{APM_ROOT}}/agents/personas.backup.YYYYMMDD/* {{APM_ROOT}}/agents/personas/

# Test restored configuration
{{APM_ROOT}}/scripts/test-all-agents.sh

---

📊 Agent Quality Assurance

Agent Behavior Validation

Behavioral Tests:

# Test agent persona adherence
{{APM_ROOT}}/scripts/test-persona-adherence.sh

# Validate agent response patterns
{{APM_ROOT}}/scripts/validate-agent-responses.sh

# Check agent knowledge consistency
{{APM_ROOT}}/scripts/test-agent-knowledge.sh

Integration Tests:

# Test agent integration with project
{{APM_ROOT}}/scripts/test-project-integration.sh

# Test agent collaboration
{{APM_ROOT}}/scripts/test-agent-collaboration.sh

# Test agent workflow compatibility
{{APM_ROOT}}/scripts/test-workflow-compatibility.sh

---

📚 Related Resources

• Common Issues - General APM troubleshooting
• Performance Issues - Agent performance optimization
• Diagnostic Tools - Advanced debugging utilities
• Persona Guide - Understanding agent personas

---

Last Updated: 2025-08-19 Coherence APM Framework v4.2.0 - Enhanced TTS Audio Experience