# Issue Management Reference

Extended reference documentation for `ao-task` skill.

---

## CLI Commands (ao)

All issue management is done via the `ao` CLI. Most commands need no global flags.

| Command | Description | Example |
|---------|-------------|---------|
| `ao ls` | List all open issues | `ao ls --sort priority` |
| `ao issue show ID` | Show issue details | `ao issue show FEAT-0001@abc123` |
| `ao add TITLE` | Create new issue | `ao add "Fix login" --type bug --priority high` |
| `ao set ID` | Quick-update fields | `ao set BUG-0042@abc123 --status in_progress` |
| `ao close ID` | Close an issue | `ao close BUG-0042@abc123 --status done --log "Fixed"` |
| `ao log add ID MSG` | Append log entry | `ao log add FEAT-0001@abc123 "progress note"` |
| `ao ac add ID TEXT` | Add acceptance criterion | `ao ac add FEAT-0001@abc123 "tests pass"` |
| `ao ac check ID INDEX` | Toggle AC item | `ao ac check FEAT-0001@abc123 1` |
| `ao link add ID` | Add dependency | `ao link add FEAT-0042@abc123 --depends-on FEAT-0001@aaa111` |
| `ao lesson add ID MSG` | Add lesson learned | `ao lesson add FEAT-0001@abc123 "gotcha description"` |
| `ao lesson ls ID` | List lessons on issue | `ao lesson ls FEAT-0001@abc123` |
| `ao next` | Show ready-to-work issues | `ao next` |
| `ao rebuild` | Rebuild active.jsonl | `ao rebuild` |

### Flag Notes

- `--yes` is only needed for interactive commands: `compact`, `triage`, `worktree`
- When `--yes` is set, `--format json` and `--progress none` are auto-applied
- `ao add` defaults: `--type feat --priority backlog --status todo --confidence normal`

### Filter Examples

```bash
ao ls --priority high
ao ls --epic auth --status todo
ao next
ao ls status:todo prio:high type:bug
```

---

## 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 critical issues as JSON
ao --format json ls --priority critical
ao --format json ls --priority high
```

### 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 set IDEA-0001@abc123 --priority high
```

---

## Bulk Operations

```bash
# Add multiple issues
ao add "Fix session expiry" --priority high --type bug
ao 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` |
