Skip to content
skill-issues · octo · Flowy
Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage
One skill from octo .
$ npx -y skills add nyldn/claude-octopus --skill skill-issues --agent claude-codeInstalls just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itself Claude auto-loads it when your prompt matches the work. You can call it Invoke it directly when you want it. Slash command /skill-issues👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage </> SKILL.md
skill-issues.SKILL.md
---
name : skill-issues
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 : |
AUTOMATICALLY ACTIVATE 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
Flowy AI Flows that just work. Hand-picked Claude Code plugins that fire the right skill as you prompt.
- 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.**
© 2026 Flowy · Free and open source
Built for Claude Code · Not affiliated with Anthropic
