Skip to content
Skills Library
Management & product · Planning

skill-issues

/skill-issues

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

Author
nyldn ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

Arguments

/skill-issues [list|add|resolve|show] [description or ID]
Original author description

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

How it works

  1. Overview
  2. When to Use
  3. Subcommands
  4. File Management
  5. ID Generation Algorithm
  6. Severity Levels
  7. Integration with Other Skills
  8. Best Practices
  9. Common Patterns
  10. Red Flags - Don't Do This
Original SKILL.md headings · 490 lines, 1,455 words
SKILL.md preview
---
name: skill-issues
disable-model-invocation: true
user-invocable: true
aliases:
  - issues
  - issue-tracking
description: "Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage"
trigger: |
  EXPLICITLY USE when user mentions:
  - "issue" or "issues" or "problem"
  - "track this" or "remember this blocker"
  - "add issue" or "create issue"
  - "resolve issue" or "close issue"
  - "show issues" or "list issues"
  
  DO NOT activate for:
  - Git issues (use git commands)
  - GitHub issues (use gh CLI)
  - General problem-solving without tracking
argument-hint: "[list|add|resolve|show] [description or ID]"
---

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

**Action:**

```bash
# 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:**

```bash
# 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:**

```bash
#!/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.**

Versions

The database has no other skills named skill-issues.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 6e0bd053bca3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100triage
    Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
  • 100workflow-status
    Use when: you need a read-only project and article status cockpit with blockers and the next safe command.
  • 100triage
    Triage and prioritize Linear backlog issues using the linear CLI. Analyzes staleness, blockers, dependency health, and priority mismatches. Use when the user asks about backlog grooming, sprint planning, issue prioritization, managing stale tickets, or cleaning up Linear issues.
  • 100triage
    Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
  • 88triage
    Move issues and external PRs through a state machine of triage roles. Categorise (bug/enhancement), verify claims, grill if needed, write agent-ready briefs. Five state roles: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. Use when the user says "triage…
  • 85shiplog
    Preserve project discussion, decisions, and work context in GitHub. Use when the user requests durable tracking, recalls past discussion, or continues tracked work across sessions.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.