GOAP Stuck State Diagnostic System

[igordayen]

GOAP Stuck State Diagnostic System

Feature Request Summary

Overview

A comprehensive diagnostic system that automatically analyzes GOAP (Goal-Oriented Action
Planning) planner failures and provides developers with precise root cause analysis and
explicit corrective actions.

Please refer to issue: #179

Problem Statement

When GOAP planners got stuck, developers currently face:

• Cryptic error messages: "No plan found" with some minimal context
• Time-intensive debugging on analyzing world state / action
  preconditions
• Trial-and-error fixes: Developers guess at solutions without understanding root causes
• Complex interdependencies: Difficult to trace why action sequences fail

Solution Benefits

For Developers

• Instant Root Cause Identification: Know exactly why the planner is stuck
• Explicit Fix Instructions: Get precise code changes needed to resolve issues
• Reduced Debugging Time: Cut troubleshooting from hours to minutes
• Learning Tool: Understand GOAP patterns and best practices through guided feedback

For Teams

• Faster Development Cycles: Reduce iteration time on agent behavior
• Knowledge Sharing: Junior developers learn GOAP concepts through diagnostic guidance
• Quality Improvement: Prevent common GOAP anti-patterns
• Documentation: Self-documenting system that explains GOAP rules

Diagnostic Categories

1. Missing Preconditions

Problem: Action cannot execute due to unsatisfied conditions
Guidance: Specific conditions to fix and how to satisfy them

2. Signature Collisions

Problem: Multiple actions with identical parameters confuse the planner
Guidance: Add discriminating preconditions to distinguish actions

3. Unreachable Goals

Problem: Goal requires conditions no available action can produce
Guidance: Split complex goals or add intermediate actions

4. Circular Dependencies

Problem: Action A needs B, but B needs A
Guidance: Identify dependency loops and suggest breaking points

5. Object Type Mismatches

Problem: Required object types not available in blackboard
Guidance: Show which actions should produce missing types

Example Diagnostic Output

🚫 GOAP PLANNER STUCK: MISSING_PRECONDITIONS

📋 ROOT CAUSE:
Action 'decideOnFlight' cannot execute because condition 'travelFlightCondition'
is FALSE but action requires TRUE.

🔧 EXPLICIT FIX:

1. Check @condition method: travelFlightCondition(Option option)
2. Verify it returns TRUE when option == Option.FLIGHT
3. Add explicit condition setting in classify action

📝 CODE CHANGE REQUIRED:
@action(post = {"travelFlightCondition", "travelItineraryCondition"})
Option classify(UserInput input, OperationContext context) {
Option result = // ... LLM call

  // ADD THIS:
  if (result == Option.FLIGHT) {
      context.setCondition("travelFlightCondition", true);
      context.setCondition("travelItineraryCondition", false);
  }
  
  return result;

}

💡 WHY THIS WORKS:
The planner needs explicit condition values to determine which actions
can execute next. @condition methods alone may not be evaluated
automatically after each action.

Implementation Approach

1. Analysis Engine: Examine world state, actions, and goals to identify failure patterns
2. Pattern Matching: Categorize failures into known problem types
3. Code Generation: Provide exact code snippets for fixes

Success Metrics

• Debugging Time Reduction: 80% decrease in time to identify GOAP issues
• Developer Onboarding: New developers productive with GOAP in days vs weeks
• Code Quality: Reduced GOAP-related bugs in production
• Documentation: Self-documenting system reduces support tickets

This diagnostic system transforms GOAP debugging from an art into a science, making complex
planning systems accessible to all developers.