zero-iteration-failure-analysis

name	zero-iteration-failure-analysis
description	Identify and handle agent failures with 0 iterations as pre-execution system issues

Zero-Iteration Failure Analysis

This skill provides a workflow for detecting and responding to agent failures that occur before any iterations are executed. These failures indicate system-level problems rather than task execution issues.

When to Apply

Use this skill when analyzing agent execution results and you observe:

• 0 iterations reported in the execution summary
• No tool invocations in the conversation log
• No artifacts created (no files, outputs, or intermediate results)
• Error message present but no agent reasoning visible

Identification Checklist

A zero-iteration failure is confirmed when ALL of the following are true:

[ ] Iteration count = 0
[ ] Tool usage count = 0  
[ ] No conversation log beyond initial instruction
[ ] Error/self-report indicates failure before execution began

Failure Mode Classification

Indicator	Failure Type	Investigation Level
0 iterations, 0 tools	Pre-execution	System-level
1+ iterations, error mid-task	Execution	Agent-level
1+ iterations, wrong output	Reasoning	Agent-level

Investigation Steps

Step 1: Confirm Zero-Iteration Status

def is_zero_iteration_failure(execution_result):
    """Check if failure occurred before any agent iterations."""
    return (
        execution_result.get('iterations', 0) == 0 and
        execution_result.get('tool_calls', []) == [] and
        execution_result.get('artifacts', []) == []
    )

Step 2: Extract Error Context

Examine any error message or self-report for clues:

• Initialization errors: Environment setup, dependency missing, config invalid
• Prompt parsing errors: Malformed instruction, missing required fields
• Resource errors: Memory limits, timeout before start, permission denied

Step 3: Route to Appropriate Investigation

IF zero-iteration failure detected:
    → Escalate to SYSTEM investigation
    → Do NOT attempt agent-level debugging
    → Check: environment, dependencies, prompt format, resource limits
ELSE:
    → Proceed with standard agent failure analysis

Step 4: Document the Failure Mode

Record the failure with appropriate categorization:

failure_analysis:
  type: zero-iteration
  severity: high
  investigation_level: system
  agent_debugging_appropriate: false
  recommended_actions:
    - Check execution environment health
    - Verify prompt/input formatting
    - Review system logs for initialization errors
    - Validate resource availability

Common Causes and Resolutions

Cause	Symptoms	Resolution
Environment crash	Immediate error, no context	Restart environment, check dependencies
Prompt parse failure	Error mentions instruction format	Validate input schema, fix formatting
Resource exhaustion	Timeout or memory error before start	Increase limits, optimize initialization
Permission denied	Access error on startup	Check file/system permissions

Escalation Criteria

Immediately flag for system-level review when:

• Zero-iteration failures occur repeatedly (>2 in same session)
• Error messages indicate infrastructure issues
• Multiple agents fail with same zero-iteration pattern

Example Analysis

EXECUTION SUMMARY:
- Iterations: 0
- Tools Used: None
- Artifacts: None
- Status: Failed
- Error: "Agent initialization failed: missing required config"

ANALYSIS:
✓ Zero-iteration failure detected
✓ Pre-execution failure mode confirmed
→ Action: Escalate to system investigation
→ Do NOT debug agent reasoning (no reasoning occurred)
→ Check: config loading, environment variables, initialization sequence

Anti-Patterns to Avoid

❌ Don't attempt to debug agent reasoning when 0 iterations occurred ❌ Don't assume the task instructions were unclear (agent never saw them) ❌ Don't retry with modified prompts before checking system health ❌ Don't categorize as "agent performance issue"

Integration with Failure Tracking

When logging failures, Tag zero-iteration failures distinctly:

{
  "failure_id": "xyz123",
  "failure_mode": "pre_execution",
  "iteration_count": 0,
  "requires_system_review": true,
  "agent_actionable": false
}