---
name: detect-zero-iteration-failures
description: Identify and handle pre-execution agent failures occurring before any iterations or tool usage
---

# Detect Zero-Iteration Failures

This skill helps identify and properly categorize agent failures that occur before any task execution begins. These failures require system-level investigation rather than agent-level debugging.

## When to Apply

Use this skill when analyzing agent task executions where:

1. **Iteration count is 0** - The agent completed zero iterations
2. **No tool usage** - No tools were invoked during the execution
3. **No artifacts created** - No files, documents, or outputs were produced
4. **Minimal or no conversation log** - Only the user instruction exists, with no agent responses

## Identification Checklist

Check the following indicators to confirm a zero-iteration failure:

```
[ ] Iterations reported: 0
[ ] Tool invocations: None
[ ] Files created: None  
[ ] Conversation turns: 1 (user instruction only)
[ ] Agent self-report: Indicates failure before execution began
```

## Failure Categories

Zero-iteration failures typically indicate one of these pre-execution issues:

| Category | Description | Investigation Focus |
|----------|-------------|---------------------|
| Initialization crash | Agent failed during setup | System logs, environment config |
| Environment issue | Missing dependencies or resources | Infrastructure, permissions |
| Prompt parsing error | Input could not be processed | Prompt format, encoding |
| Resource exhaustion | Quota or limits exceeded | System capacity, rate limits |

## Diagnostic Steps

### Step 1: Verify Zero-Iteration Indicators

```python
def is_zero_iteration_failure(execution_log):
    """Check if execution shows zero-iteration failure pattern."""
    indicators = {
        'iterations': execution_log.get('iterations', 0) == 0,
        'tools_used': len(execution_log.get('tool_calls', [])) == 0,
        'artifacts': len(execution_log.get('files_created', [])) == 0,
        'conversation_length': len(execution_log.get('messages', [])) <= 1
    }
    return all(indicators.values())
```

### Step 2: Check System-Level Indicators

Look for these error patterns in system logs:

- **Environment errors**: Missing packages, permission denied, path not found
- **Initialization errors**: Connection failures, timeout during setup
- **Resource errors**: Memory exceeded, quota limits, rate limiting
- **Parsing errors**: Invalid JSON, encoding issues, malformed input

### Step 3: Route Investigation Appropriately

```
IF zero-iteration failure detected:
    └── Do NOT debug agent logic or prompt instructions
    └── DO investigate:
        ├── System initialization logs
        ├── Environment configuration
        ├── Resource allocation and limits
        └── Input parsing and validation
```

## Response Actions

### For Analysts

1. **Flag as system-level issue** - Do not attribute to agent behavior
2. **Check infrastructure health** - Verify system components are operational
3. **Review recent changes** - Look for deployments, config updates, or quota changes
4. **Escalate appropriately** - Route to infrastructure/platform team, not agent developers

### For Automated Systems

```python
def categorize_failure(execution_log):
    """Categorize failure type for routing."""
    if is_zero_iteration_failure(execution_log):
        return {
            'category': 'PRE_EXECUTION_FAILURE',
            'severity': 'HIGH',
            'investigation_team': 'INFRASTRUCTURE',
            'agent_debug_required': False,
            'recommended_actions': [
                'Check system initialization logs',
                'Verify environment configuration',
                'Review resource quotas and limits',
                'Validate input parsing pipeline'
            ]
        }
    else:
        return {
            'category': 'EXECUTION_FAILURE',
            'severity': 'MEDIUM',
            'investigation_team': 'AGENT_DEVELOPMENT',
            'agent_debug_required': True
        }
```

## Example Analysis

**Zero-Iteration Failure Example:**
```
Task ID: 69a8ef86-phase1
Iterations: 0
Tools Used: None
Files Created: None
Messages: [User instruction only]
Agent Report: "Failed before executing any iterations"

Analysis: PRE_EXECUTION_FAILURE
- No agent logic was executed
- Failure occurred during initialization
- Action: Investigate system environment, not agent prompts
```

**Normal Execution Failure (for contrast):**
```
Task ID: abc123
Iterations: 3
Tools Used: [read_file, write_file, shell_agent]
Files Created: [output.txt]
Messages: [User instruction, Agent response x3]
Agent Report: "Could not complete task due to X"

Analysis: EXECUTION_FAILURE
- Agent logic was executed
- Failure occurred during task performance
- Action: Debug agent reasoning and tool usage
```

## Key Takeaways

1. **Zero iterations = Pre-execution failure** - The agent never got to work
2. **System-level, not agent-level** - Debug infrastructure, not prompts
3. **High severity** - Indicates potential systemic issues affecting multiple tasks
4. **Distinct failure mode** - Treat separately from normal execution failures

---
Source attribution: xyliu-cs
Original project: https://github.com/xyliu-cs/OpenSpace-GDPval/blob/af1b40a42167d09c30b3a63000aa14ace4c1e229/gdpval_bench/skills/detect-zero-iteration-failures/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 ✨Data Intelligence Lab@HKU✨

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: xyliu-cs
Original project: https://github.com/xyliu-cs/OpenSpace-GDPval/blob/af1b40a42167d09c30b3a63000aa14ace4c1e229/gdpval_bench/skills/detect-zero-iteration-failures/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Marketing, Customer Support
Roles: Data Analyst, Marketing Analyst, Technical Support
Specialties: Specialty not specified
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 963d701eb2e6da8322f539f9bb39a69f0e92d37179259b92e808e1a77616c23e