Issue Tracker

Track findings, bugs, and improvements as text files. All operations go through the CLI at ~/.claude/skills/issue/cli.py.

Two-Tier Model

Tier	Severity	Format	When
Deep	critical, significant, enhancement	Individual file in status dirs	Needs research, design decisions, multiple rounds
Quick	warning, gap	Checklist in quickfixes.md	Mechanical — clear problem, clear fix

Severity determines format. Don't create a file for a one-line fix. Don't put a research problem on a checklist.

Config

Location: ~/.config/issue-tracker/config.yaml

issues_root: ~/issues
default_project: fabulexa
projects:
  fabulexa:
    root: ~/projects/fabulexa_sim
    packages: [engine, abm, export]
  claude-skills:
    root: ~/claude_skills

All issues live under issues_root/<project>/. Project is resolved from cwd automatically. Use --project <name> to override.

Directory Structure

~/issues/
├── config.yaml
├── fabulexa/
│   ├── open/
│   ├── in_progress/
│   ├── closed/
│   └── quickfixes.md
└── claude-skills/
    ├── open/
    ├── in_progress/
    ├── closed/
    └── quickfixes.md

Command Reference

init

python3 ~/.claude/skills/issue/cli.py init myproject --packages api,frontend

# With custom issues root
python3 ~/.claude/skills/issue/cli.py init myproject --issues-root ~/work/issues

Creates config entry and directory structure. Default issues root: ~/issues.

create

# Minimal
python3 ~/.claude/skills/issue/cli.py create critical "PyArrow NULL handling gap"

# With content
python3 ~/.claude/skills/issue/cli.py create significant "dict.get fallbacks mask contracts" \
  --package abm \
  --component export \
  --summary "dict.get() with defaults hides missing required keys" \
  --problem "Found in flush.py:45 — uses dict.get('key', []) which silently returns empty list" \
  --analysis "Root cause: defensive coding pattern. Affects all callers."

Output: Created #034: <summary>

quickfix

python3 ~/.claude/skills/issue/cli.py quickfix "getattr on Actor alias properties" \
  --package abm \
  --items "types/actor.py:45=remove properties @property alias" \
          "types/actor.py:52=remove actor_type @property alias"

update (reads from stdin)

python3 ~/.claude/skills/issue/cli.py update 034 --section analysis <<'EOF'
Root cause is the flush method treating nullable columns as non-nullable.
EOF

list

python3 ~/.claude/skills/issue/cli.py list
python3 ~/.claude/skills/issue/cli.py list --status all
python3 ~/.claude/skills/issue/cli.py list --package abm --severity critical

Output:

fabulexa — 3 open, 1 in progress, 15 closed

  Open:
    034 [critical, abm] PyArrow array construction crashes on nullable columns
    037 [significant, abm] dict.get() fallbacks mask contract violations

  In Progress:
    033 [significant, abm] state: object type erasure remaining in 6 files

  Quick fixes: 2 open, 4 closed

search

python3 ~/.claude/skills/issue/cli.py search "pyarrow"

Case-insensitive. Searches issue files and quickfixes.md. Capped at 20 results.

show

python3 ~/.claude/skills/issue/cli.py show 034
python3 ~/.claude/skills/issue/cli.py show pyarrow

start / close / reopen

python3 ~/.claude/skills/issue/cli.py start 034
python3 ~/.claude/skills/issue/cli.py close 034 --commit abc1234 \
  --decision "Use from_pandas=True" --fix "Changed flush.py"
python3 ~/.claude/skills/issue/cli.py reopen 034

For longer decision/fix content, use update first, then close without those flags.

close-quickfix

python3 ~/.claude/skills/issue/cli.py close-quickfix "getattr on Actor"

LLM Workflow

Filing issues after a review

python3 ~/.claude/skills/issue/cli.py list
python3 ~/.claude/skills/issue/cli.py create critical "Title" --package pkg --problem "..." --analysis "..."
python3 ~/.claude/skills/issue/cli.py quickfix "Title" --package pkg --items "file:line=description"

Working an issue

python3 ~/.claude/skills/issue/cli.py start 034
# ... do the work ...
python3 ~/.claude/skills/issue/cli.py close 034 --commit <hash>

Adding research

python3 ~/.claude/skills/issue/cli.py update 034 --section options <<'EOF'
Option A: ...
Option B: ...
EOF

Principles

• Issues live outside the project repo. No context pollution during codebase searches.
• Status = directory. Moving a file changes its status.
• Deep issues accumulate context. Each research round adds to Options/Analysis via update.
• Quick fixes are bulk-processable. Read the checklist, fix in one pass, close-quickfix.
• Summary enables scanning. One-line summaries in frontmatter power list/search.

Integration with Other Skills

Review skills should file findings as issues:

1. Classify each finding by severity
2. Create via CLI commands above
3. Reference issue numbers in review summaries (#034)