/skill-issues

name: skill-issues
description: "Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

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 task plan tool)

Subcommands

1. List Issues (Default)

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

Show all open issues in table format:

## 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:

⚠ 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:

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

# 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`

# 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:

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

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

Step 5: Confirm

✅ 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

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

If not found, show error:

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

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

Step 2: Ask for Resolution Notes

**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:**

| 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

✅ 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:**

## Issue Details: ISS-20260203-001

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

**Actions:**
- Resolve: `/o