skill-issues

> 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: `/octo:issues resolve ISS-20260203-001`

For resolved issue:

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

❌ 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.

Action:

# Create .octo directory if needed
mkdir -p .octo

# Copy template
cp ${HOME}/.claude-octopus/plugin/config/templates/ISSUES.md.template .octo/ISSUES.md

# Replace {{PROJECT_NAME}} with actual project name
PROJECT_NAME=$(basename $(pwd))
sed -i '' "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" .octo/ISSUES.md

Preserve Existing Issues

CRITICAL: When adding or resolving issues, NEVER overwrite existing content.

Pattern:

# Read existing content
EXISTING=$(cat .octo/ISSUES.md)

# Modify specific section only
# Append new issue to Open Issues table
# OR move issue from Open to Resolved

# Write back with all content preserved
echo "$MODIFIED" > .octo/ISSUES.md

ID Generation Algorithm

Format: ISS-YYYYMMDD-NNN

Example: ISS-20260203-001

Implementation:

#!/bin/bash

# Get today's date in YYYYMMDD format
TODAY=$(date +%Y%m%d)

# Find all issues created today
TODAY_ISSUES=$(grep -o "ISS-${TODAY}-[0-9]\{3\}" .octo/ISSUES.md || echo "")

if [ -z "$TODAY_ISSUES" ]; then
  # No issues today, start at 001
  NEXT_NUM="001"
else
  # Get highest number for today
  HIGHEST=$(echo "$TODAY_ISSUES" | sed "s/ISS-${TODAY}-//" | sort -n | tail -1)
  
  # Increment
  NEXT_NUM=$(printf "%03d" $((10#$HIGHEST + 1)))
fi

# Generate ID
ISSUE_ID="ISS-${TODAY}-${NEXT_NUM}"
echo "$ISSUE_ID"

Severity Levels

| Level | Meaning | Example |

|-------|---------|---------|

| critical | Blocks all progress | Production down, data loss |

| high | Significant impact | Feature broken, security issue |

| medium | Should address | Performance degradation, UX issue |

| low | Nice to fix | Minor bug, cosmetic issue |

Integration with Other Skills

With skill-debug

User: "track this bug for later"

1. Use skill-issues to create issue
2. Use skill-debug to investigate if time permits
3. Link issue ID in debug notes

With skill-task-management

User: "add fixing ISS-20260203-001 to todos"

1. Use skill-task-management to add todo
2. Reference issue ID in todo description
3. Mark issue as resolved when todo completes

With flow-develop

User: "implement fix for ISS-20260203-001"

1. Use flow-develop to implement fix
2. Use skill-issues to resolve issue after fix
3. Link commit SHA in resolution notes

Best Practices

1. Clear Descriptions

Good:

Auth token refresh fails after 15 minutes

Poor:

Auth broken

2. Appropriate Severity

Critical: Only for blockers that stop all work

High: Significant but workarounds exist

Medium: Should fix but not urgent

Low: Nice to have

3. Resolution Notes

Good:

Fixed OAuth token refresh by updating expiration logic in auth.ts
Commit: abc123

Poor:

Fixed

Common Patterns

Pattern 1: Track During Development

User: "track this issue: API rate limiting not working"

Action:
1. Create issue with appropriate severity
2. Record current phase from STATE.md
3. Continue development

Pattern 2: Resolve After Fix

User: "resolve ISS-20260203-001, fixed in commit abc123"

Action:
1. Ask for resolution notes
2. Move to Resolved section
3. Record resolution date and notes

Pattern 3: Review Open Issues

User: "what issues do we have?"

Action:
1. List all open issues
2. Show severity and phase
3. Offer to show details or resolve

Red Flags - Don't Do This

| Action | Why It's Wrong |

|--------|----------------|

| Overwrite ISSUES.md | Lose all existing issues |

| Skip severity validation | Invalid data in file |

| Duplicate issue IDs | ID collision |

| Vague descriptions | Can't remember what issue was |

| Resolve without notes | No record of what was done |

Quick Reference

| User Intent | Skill Action | Output |

|-------------|--------------|--------|

| "list issues" | Read and display Open Issues | Table of issues |

| "add issue X" | Generate ID, append to file | Issue created |

| "resolve ISS-X" | Move to Resolved section | Issue resolved |

| "show ISS-X" | Find and display details | Issue details |

The Bottom Line

Issue tracking → Persistent memory across sessions
Otherwise → Forget problems, repeat mistakes

Track everything. Resolve systematically. Learn from history.