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:

## 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"}
      ]
    }
  ]
})