---
name: ao-epic-analyzer
description: "AI-based epic assignment suggestions. Uses pydantic-ai with pluggable providers to analyze issues and suggest epic groupings for similar tasks."
category: analysis
invokes: []
invoked_by: [ao-planning, ao-task]
state_files:
  read: [issues/active.jsonl]
  write: [issues/events.jsonl]
---

# Epic Analyzer Skill

Suggest epic assignments for issues using an AI model via `pydantic-ai`.

## Prerequisites

Install the AI extra:

```bash
uv pip install 'ao[ai]'
```

Set the API key for your chosen provider as an environment variable:

- OpenAI: `OPENAI_API_KEY`
- Anthropic: `ANTHROPIC_API_KEY`
- Google: `GOOGLE_API_KEY`
- Groq: `GROQ_API_KEY`

## Usage

### CLI

```bash
# Suggest epics for unassigned issues
uv run ao epic analyze openai:gpt-4o

# Include issues that already have an epic
uv run ao epic analyze openai:gpt-4o --include-assigned

# Suggest and apply in one step
uv run ao --yes epic analyze openai:gpt-4o --apply
```

### Python API

```python
from ao.api import AOIClient

client = AOIClient(root="path/to/.agent/ops")
suggestions = client.epic_analyze("openai:gpt-4o")
# [{"issue_id": "FEAT-0001@abc123", "epic": "Auth System", "reason": "..."}]

# Apply suggestions directly
client.epic_analyze("openai:gpt-4o", apply=True)
```

## Model String Format

The model parameter uses pydantic-ai's provider format: `provider:model_name`.

Examples:
- `openai:gpt-4o`
- `anthropic:claude-sonnet-4-20250514`
- `groq:llama-3.1-70b-versatile`
- `google:gemini-2.0-flash`

## When to Use

- After creating several issues that lack epic assignments
- When reorganizing work into parallel streams
- During planning to identify natural groupings
- After importing issues from an external source

## What It Does

1. Loads all active non-terminal issues (optionally including those already assigned)
2. Serializes issue metadata (ID, title, type, priority, labels, notes) into a prompt
3. Sends to the configured AI model via pydantic-ai
4. Returns structured suggestions: `issue_id`, `suggested_epic`, `reason`
5. With `--apply`, writes SET events to assign the suggested epics
