skill-issues

# Issue Tracking

## Overview

Cross-session issue tracking for persistent problem management. Issues are stored in `.octo/ISSUES.md` and survive across Claude Code sessions.

**Core principle:** Track → Resolve → Learn.

---

## When to Use

**Use this skill when user wants to:**
- Track a problem or blocker for later
- Record issues discovered during development
- Review open issues across sessions
- Mark issues as resolved
- View details of specific issues

**Do NOT use for:**
- GitHub issue management (use gh CLI)
- Git-tracked issues (use git commands)
- Temporary todos (use TodoWrite)

---

## Subcommands

### 1. List Issues (Default)

**Trigger:** `/octo:issues` or `/octo:issues list`

Show all open issues in table format:

```markdown
## Open Issues

| ID | Severity | Category | Description | Created | Phase |
|----|----------|----------|-------------|---------|-------|
| ISS-20260203-001 | high | integration | Auth not working | 2026-02-03 | Develop |
| ISS-20260203-002 | medium | performance | Slow query performance | 2026-02-03 | Deliver |
```

**Pattern Detection:** After listing, check if 3+ open issues share the same category. If so, alert:
```text
⚠ Pattern detected: 3 open issues in category "integration" — may indicate a systemic problem.
```

**Implementation:**
1. Check if `.octo/ISSUES.md` exists
2. If not, initialize from template
3. Read and parse Open Issues section
4. Display in table format

---

### 2. Add Issue

**Trigger:** `/octo:issues add <description>`

Add new issue with auto-generated ID.

**Flow:**

#### Step 1: Gather Information

Use AskUserQuestion with two questions:

```javascript
AskUserQuestion({
  questions: [
    {
      question: "What severity is this issue?",
      header: "Severity",
      multiSelect: false,
      options: [
        {label: "critical", description: "Blocks all progress"},
        {label: "high", description: "Significant impact"},
        {label: "medium", description: "Should address"},
        {label: "low", description: "Nice to fix"}
      ]
    },
    {
      question: "What category does this issue fall into?",
      header: "Category",
      multiSelect: false,
      options: [
        {label: "logic-error", description: "Incorrect behavior or wrong output"},
        {label: "integration", description: "Cross-component or API compatibility"},
        {label: "quality-gate", description: "Quality gate failures during workflows"},
        {label: "security", description: "Security vulnerabilities or concerns"},
        {label: "performance", description: "Speed, memory, or scalability issues"},
        {label: "ux", description: "User experience or usability problems"},
        {label: "architecture", description: "Structural or design pattern issues"}
      ]
    }
  ]
})
```

#### Step 2: Determine Current Phase

```bash
# Check if STATE.md exists
if [ -f .octo/STATE.md ]; then
  grep "current_phase:" .octo/STATE.md
else
  echo "Unknown"
fi
```

#### Step 3: Generate Issue ID

**Format:** `ISS-YYYYMMDD-NNN`

```bash
# Get today's date
TODAY=$(date +%Y%m%d)

# Find existing issues for today
grep "ISS-${TODAY}-" .octo/ISSUES.md | tail -1

# Increment sequence number
# If ISS-20260203-001 exists, next is ISS-20260203-002
```

#### Step 4: Append to ISSUES.md

Add new row to Open Issues table:

```markdown
| ISS-20260203-003 | medium | performance | Slow query performance | 2026-02-03 | Develop |
```

**Preserve existing issues** - append only, don't overwrite.

#### Step 5: Confirm

```markdown
✅ Issue created: ISS-20260203-003

**Severity:** medium
**Category:** performance
**Description:** Slow query performance
**Created:** 2026-02-03
**Phase:** Develop

View with: /octo:issues show ISS-20260203-003
```

---

### 3. Resolve Issue

**Trigger:** `/octo:issues resolve <id>`

Mark issue as resolved and move to Resolved section.

**Flow:**

#### Step 1: Validate Issue Exists

```bash
# Check if issue ID exists in Open Issues
grep "ISS-20260203-001" .octo/ISSUES.md
```

If not found, show error:

```markdown
❌ Issue ISS-20260203-001 not found in open issues.

Use `/octo:issues list` to see all open issues.
```

#### Step 2: Ask for Resolution Notes

```markdown
**Resolving issue:** ISS-20260203-001

Please provide resolution notes:
```

#### Step 3: Move to Resolved Section

1. Extract issue row from Open Issues table
2. Remove from Open Issues
3. Add to Resolved Issues with resolution date and notes

**Resolved Issues format:**

```markdown
| ID | Severity | Category | Description | Created | Resolved | Resolution |
|----|----------|----------|-------------|---------|----------|------------|
| ISS-20260203-001 | high | integration | Auth not working | 2026-02-03 | 2026-02-04 | Fixed OAuth token refresh |
```

#### Step 4: Confirm

```markdown
✅ Issue resolved: ISS-20260203-001

**Resolution date:** 2026-02-04
**Resolution notes:** Fixed OAuth token refresh

View with: /octo:issues show ISS-20260203-001
```

---

### 4. Show Issue Details

**Trigger:** `/octo:issues show <id>`

Display full details of specific issue.

**Flow:**

#### Step 1: Find Issue

Search both Open and Resolved sections for issue ID.

#### Step 2: Display Details

**For open issue:**

```markdown
## Issue Details: ISS-20260203-001

**Status:** Open
**Severity:** high
**Category:** integration
**Description:** Auth not working
**Created:** 2026-02-03
**Phase:** Develop

**Actions:**
- Resolve: `/octo:issues resolve ISS-20260203-001`
```

**For resolved issue:**

```markdown
## Issue Details: ISS-20260203-001

**Status:** Resolved
**Severity:** high
**Category:** integration
**Description:** Auth not working
**Created:** 2026-02-03
**Resolved:** 2026-02-04
**Resolution:** Fixed OAuth token refresh
```

#### Step 3: If Not Found

```markdown
❌ Issue ISS-20260203-001 not found.

Use `/octo:issues list` to see all open issues.
```

---

## File Management

### Initialize ISSUES.md

**When:** First time skill is used or `.octo/ISSUES.md` doesn't exist.

*