# Error Analysis

## Overview

The error analysis command provides AI-powered diagnosis of errors, failures, and unexpected behavior encountered during prototype development and deployment. It implements the **QA-first routing** principle: all errors are routed to the `qa-engineer` agent, which owns the full diagnostic lifecycle including evidence gathering, log analysis, and root cause identification.

For persistent or unresolvable issues, the system integrates with the [escalation chain](Escalation.md).

## Command

```
az prototype analyze error --input INPUT
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `--input` | string (required) | Error input to analyze. Accepts an inline error string, a path to a log file, or a path to a screenshot image. |
| `--json` / `-j` | flag | Output machine-readable JSON instead of formatted display. |

## Input Types

The `--input` parameter accepts three types of input, detected automatically:

### Inline Error String

Pass an error message directly as a quoted string. Useful for quick diagnosis of a specific error.

```bash
az prototype analyze error --input "Error: ResourceGroupNotFound - Resource group 'rg-myapp' could not be found"
```

### Log File Path

Pass a path to a log file. The QA agent reads the file contents and analyzes the full log for errors, warnings, and root causes.

```bash
az prototype analyze error --input ./terraform.log
```

### Screenshot Image

Pass a path to a screenshot image (PNG, JPG, etc.). The QA agent uses vision capabilities to analyze the screenshot, identify error messages, and diagnose the issue.

```bash
az prototype analyze error --input ./error-screenshot.png
```

## QA-First Routing

Error analysis follows the agent governance principle that all errors, failures, and unexpected behavior must route to `qa-engineer` first. The QA agent:

1. **Gathers evidence** -- examines the error message, log content, or screenshot
2. **Analyzes context** -- considers the current project configuration, design, and build state
3. **Identifies root cause** -- determines what went wrong and why
4. **Recommends resolution** -- provides actionable steps to fix the issue

The QA agent has web search enabled (see [Knowledge System](Knowledge-System.md)), so it can look up Microsoft Learn documentation when diagnosing unfamiliar errors.

If the QA agent cannot resolve the issue and an escalation tracker is available, it records the blocker automatically for [escalation](Escalation.md).

## Vision Support

When the input is an image file, the extension uses the AI provider's vision capabilities to analyze screenshots. This is particularly useful for:

- Azure Portal error dialogs
- Deployment failure screens
- CLI output screenshots shared by team members
- Browser-based application errors

The `AIMessage.content` field supports both string and list forms; the list form holds OpenAI-compatible vision content arrays with base64-encoded image data.

## Examples

Analyze an inline error:

```bash
az prototype analyze error --input "TerraformError: Error creating AzureRM Resource Group: unexpected status 403"
```

Analyze a Terraform log file:

```bash
az prototype analyze error --input ./infra/terraform.log
```

Analyze a deployment failure screenshot:

```bash
az prototype analyze error --input ./screenshots/deploy-failure.png
```

Get JSON output for programmatic consumption:

```bash
az prototype analyze error --input "connection refused" --json
```

## Related

- [Escalation](Escalation.md) -- what happens when QA cannot resolve the issue
- [Troubleshooting](Troubleshooting.md) -- common issues and diagnostic commands
- [Knowledge System](Knowledge-System.md) -- web search used during diagnosis