issues

Issue Tracking Skill

A minimal, append-only event log for tracking issues. Designed for close human-AI collaboration.

Installation required: Install the skill-issues package for CLI tools:

uv tool install skill-issues

Data Location

Events are stored in .issues/events-{prefix}.jsonl (project root) - one JSON event per line, append-only. Each user writes to their own file (e.g., events-dp.jsonl), enabling conflict-free multi-user git workflows. Reading aggregates from all user files. The directory and file are auto-created on first use.

User Prefix

Issue IDs include a user prefix (e.g., dp-001) to enable conflict-free collaboration. The prefix is resolved in order:

1. SKILL_ISSUES_PREFIX environment variable
2. git config skill-issues.prefix
3. Derived from git config user.name (first + last initials)
4. Fallback: xx

Configure once per machine:

git config --global skill-issues.prefix "dp"

On first use with a derived prefix, you'll see a hint about configuration.

Quick Reference

# Reading
issues                    # Open issues (default)
issues --open             # Open issues (explicit)
issues --closed           # Closed issues
issues --ready            # Open and not blocked
issues --all              # All issues including closed
issues ID                 # Show single issue
issues --show ID          # Show single issue (explicit)
issues --diagram          # Mermaid dependency diagram
issues --diagram ascii    # ASCII dependency diagram

# Writing
issues create "Title" [options]
issues close ID "Reason"
issues note ID "Content"
issues add-dep ID "DEP_IDS"
issues remove-dep ID "DEP_IDS"

# TUI
issues board              # Kanban board view

Why append-only?

• Writes are trivial (just append)
• Git diffs are always additions at the end
• Full history without digging through git commits
• No read-modify-write complexity

Event Schema

Four event types:

// created - sets initial fields
{"ts": "2025-12-13T14:00:00Z", "type": "created", "id": "dp-014", "title": "Short title", "issue_type": "task", "priority": 2, "description": "Details", "depends_on": ["dp-013"], "labels": ["needs-review"]}

// updated - changes mutable fields (priority, depends_on, labels)
{"ts": "2025-12-13T14:15:00Z", "type": "updated", "id": "dp-014", "priority": 1, "reason": "Blocking other work, needs to be done first"}

// note - adds context during work (can have multiple per issue)
{"ts": "2025-12-13T14:30:00Z", "type": "note", "id": "dp-014", "content": "Discovered that the API requires auth tokens, not session cookies. See src/api/widget.ts:45"}

// closed - terminal state
{"ts": "2025-12-13T15:00:00Z", "type": "closed", "id": "dp-014", "reason": "Done - explanation"}