Issue Management

Works with or without

aoc

CRITICAL: Issue Management ONLY

This skill manages issues. It NEVER implements code.

• ✅ Create, refine, list, search, triage issues
• ✅ Move issues between priority files
• ❌ NEVER implement features or fix bugs
• ❌ NEVER modify code files

After any issue operation, ALWAYS offer a handoff — never auto-proceed.

Reference: See REFERENCE.md for templates, CLI commands, JSON export.

Issue ID Format

Format:

{TYPE}-{NUMBER}@{HASH}

BUG-0023@efa54f

FEAT-0001@c2d4e6

Types:

BUG

FEAT

CHORE

ENH

SEC

PERF

DOCS

TEST

REFAC

PLAN

Minimal Issue Template

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

id: {TYPE}-{NUMBER}@{HASH}
title: "{title}"
type: {type}
status: todo | in_progress | done
priority: critical | high | medium | low
description: {brief description}
details: references/{TYPE}-{NUMBER}@{HASH}.md

### Acceptance Criteria
- [ ] Criterion 1

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

Issue Size Guardrails

• Keep backlog items minimal: title, metadata, 1–2 sentence description, acceptance criteria if known.
• If an issue needs more than ~20 lines, move details to a reference file in

  .agent/issues/references/

  and link it in the issue.
• Reference files should contain research, long descriptions, examples, diagrams, or interview notes.
• Never embed large code blocks or research dumps directly in backlog items.

Reference File Format

• Path:

  .agent/issues/references/{ISSUE-ID}.md

• Include a short header and a link back to the issue.
• Example:

# {ISSUE-ID} — {title}

Moved from backlog.md on YYYY-MM-DD.

## Context
...

File Organization

.agent/issues/critical.md

.agent/issues/high.md

.agent/issues/medium.md

.agent/issues/low.md

.agent/issues/backlog.md

.agent/issues/history.md

Operations

Create Issue

1. Analyze request for type, title, priority, scope, criteria
2. Use

   agent-ops-interview

   for missing info
3. Generate ID from

   .agent/issues/.counter

4. Create issue, append to priority file
5. STOP AND HANDOFF

Mandatory Handoff

✅ Issue created: {ISSUE-ID}: {title}

What's next?
1. Start implementing (requires confirmation)
2. Create more issues
3. Do nothing

Refine Issue

Triggers for refinement:

• Generic titles ("Fix bugs")
• Missing acceptance criteria
• Confidence marked

  low

Procedure: Interview for scope, criteria, dependencies, risks.

Change Priority

1. Remove from current file
2. Update

   priority

   field
3. Add log entry
4. Append to new file

Triage Backlog

For each backlog item: assign priority or skip/delete.

Issue Discovery

Other skills invoke discovery when they find potential work:

baseline

planning

critical-review

Procedure:

1. Collect findings
2. Categorize by type/priority
3. Present summary to user
4. Create issues on confirmation
5. Offer next actions

Quality Checklist

• Valid ID format
• Action-oriented title
• Testable acceptance criteria
• Appropriate confidence level