# Issue Management Reference

Extended reference documentation for `ao-task` skill.

---

## File-Based Operations (Default)

All issue operations can be performed via direct file editing:

| Operation | How to Do It |
|-----------|--------------|
| List issues | Read `.agent/ops/issues/{priority}.md` files directly |
| Show issue | Search for issue ID in priority files |
| Create issue | `ao --yes issue add "{title}"` (ao manages counter automatically) |
| Update issue | Edit fields directly in the file |
| Close issue | Set `status: done`, add log entry, move to `history.md` |
| Summary view | Count issues across priority files |

---

## CLI Commands (ao)

| Command | Description | Example |
|---------|-------------|---------|
| `ao ls` | List all open issues | `ao ls --sort priority` |
| `ao --yes issue show <ID>` | Show issue details | `ao --yes issue show FEAT-0001` |
| `ao --yes issue add TITLE` | Create new issue | `ao --yes issue add "Fix login" priority:high type:BUG` |
| `ao --yes issue patch <ID>` | Update issue | `ao --yes issue patch BUG-0042 status:in_progress` |
| `ao --yes issue patch <ID> status:done` | Close issue | `ao --yes issue patch BUG-0042 status:done` |

### Filter Examples

```bash
ao ls priority:high
ao ls epic:auth --status todo
ao ls --ready --sort priority
```

---

## Issue Template (Full)

```yaml
## {TYPE}-{NUMBER}@{HASH} — {title}

id: {TYPE}-{NUMBER}@{HASH}
title: "{short title}"
type: bug | feat | chore | enh | sec | perf | docs | test | refac | plan
status: todo | in_progress | blocked | done | cancelled | dropped
priority: critical | high | medium | low | backlog
epic: ""
created: YYYY-MM-DD
updated: YYYY-MM-DD
owner: agent | human | {name}
confidence: low | normal | high

### Scope
files_to_change:
  - path/to/file.ts
files_must_not_change:
  - path/to/protected.ts

### Requirements
- Requirement 1
- Requirement 2

### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

### Dependencies
depends_on:
  - {ISSUE-ID}
blocks:
  - {ISSUE-ID}

### References
spec_file: .agent/ops/issues/references/{ISSUE-ID}.md

### Notes
{Additional context}

### Log
- YYYY-MM-DD: Created
```

---

## BUG Issue Template

```yaml
## BUG-{NUMBER}@{HASH} — {title}

id: BUG-{NUMBER}@{HASH}
title: "{bug description}"
type: BUG
status: todo | in_progress | done
priority: critical | high | medium | low
epic: ""
created: YYYY-MM-DD
updated: YYYY-MM-DD
owner: agent
confidence: low | normal | high

### Problem
{What was broken? Symptoms? Root cause?}

### Scope
files_to_change:
  - path/to/affected.ts

### Acceptance Criteria
- [ ] Bug no longer reproduces
- [ ] Tests added to prevent regression

### Solution
{Populated when done - what fixed it and why}

### Log
- YYYY-MM-DD: Created
- YYYY-MM-DD: Fixed - {summary}
```

---

## Type Prefixes

| Prefix | Description |
|--------|-------------|
| `BUG` | Bug fix |
| `FEAT` | New feature |
| `CHORE` | Maintenance |
| `ENH` | Enhancement |
| `SEC` | Security |
| `PERF` | Performance |
| `DOCS` | Documentation |
| `TEST` | Test coverage |
| `REFAC` | Refactor |
| `PLAN` | Epic/plan |

---

## JSON Export

### Export Command

```bash
# List issues and capture output
ao ls priority:critical > issues.txt
ao ls priority:high >> issues.txt
```

### JSON Structure

```json
{
  "exported": "2026-01-15T10:30:00Z",
  "filters": {"priority": ["critical", "high"]},
  "count": 7,
  "issues": [
    {
      "id": "BUG-0023@efa54f",
      "type": "BUG",
      "priority": "high",
      "title": "Fix login timeout",
      "status": "todo",
      "created": "2026-01-10"
    }
  ]
}
```

---

## Discovery Output Format

When skills call discovery:

```yaml
findings:
  - type: bug
    priority: high
    title: "Fix failing test: UserService.login"
    context: "Test started failing after baseline"
    files: [src/services/UserService.ts]
```

---

## Quick Triage Shorthand

```bash
# List backlog for triage
ao ls priority:backlog
# Promote to priority
ao --yes issue patch IDEA-0001 priority:high
```

---

## Bulk Operations

```bash
# Add multiple issues
ao --yes issue add "Fix session expiry" priority:high type:BUG
ao --yes issue add "Add remember me" priority:medium type:FEAT
```

---

## Schema Validation Errors

| Error | Fix |
|-------|-----|
| Missing `id` | Generate new ID |
| Invalid ID format | Correct to `TYPE-NNNN@HHHHHH` |
| Invalid type | Use standard prefix |
| Missing status | Add `status: todo` |
