---
name: issue-tracking
description: Project issue tracking system. Use when creating, reading, updating, listing, or closing issues. Triggers on "create an issue", "add a bug", "track a task", "list issues", "show bugs", "what's open", "close issue", or any issue/bug/task management request.
---

# Track issues with the issy CLI

## Authoring Issues

Issues describe *what* needs to be done and *why*. Keep them high-level unless the user provides specific details.

### What to Include

- **Problem/Overview**: What's wrong or what's needed (1-2 paragraphs)
- **Proposed Solution**: High-level approach
- **Acceptance Criteria**: Optional - what "done" looks like from user perspective
- **Verification**: Optional but encouraged - how to prove the issue is resolved (see below)
- **Future Considerations**: Optional - related ideas for later
- **References**: Optional - links to related docs, issues, or resources

### Verification Guidance

When possible, include verification steps or hints that tell the implementing agent *how to prove* the issue is resolved. This helps ensure work is actually verified before being marked complete.

**Why include verification?** Agents should never claim work is done without evidence. If the issue itself describes how to verify, the implementing agent can follow those steps and provide concrete proof (command output, test results, screenshots, etc.).

**What to include (pick what fits):**
- Commands to run and expected output (`curl`, CLI commands, `bun test`)
- UI flows to test (can use `agent-browser` skill for automation)
- Database queries to confirm state changes
- Specific behavior to observe or confirm
- Edge cases to check

**Examples:**

```markdown
## Verification
Run `bun test src/auth.test.ts` — all tests should pass, including the new "handles expired tokens" case.
```

```markdown
## Verification
Perform the following using the agent-browser skill:

1. Navigate to /settings and toggle dark mode
2. Refresh the page — preference should persist
3. Check localStorage contains `theme: "dark"`
```

```markdown
## Verification
After deployment, `curl https://api.example.com/health` should return `{"status": "ok"}` with a 200 response.
```

### Implementation Details

**Only include implementation details if the user explicitly provides them.** Don't invent:

- Task lists or phases
- Specific code changes or file paths
- Step-by-step instructions
- Technical breakdowns

**Why?** The engineer working on the issue will plan their own implementation. Issues capture the user's intent, not execution plans generated by the agent.

**The rule:** Capture what the user says. If they provide implementation details, include them. If they don't, keep it high-level.

## CLI Commands

Use the `issy` CLI (or `npx -y issy ...` if it's not on PATH).

```bash
# List issues
issy list                    # Open issues only
issy list --all              # Include closed
issy list --priority high    # Filter: high, medium, low
issy list --type bug         # Filter: bug, improvement
issy list --search "keyword" # Fuzzy search

# Search issues (fuzzy search with typo tolerance)
issy search "dashboard"      # Search open issues
issy search "k8s" --all      # Include closed issues

# Read issue
issy read <id>               # e.g., issy read 0001

# Create issue
issy create --title "Fix login bug" --type bug --priority high
issy create --title "Add dark mode" --type improvement --priority medium --labels "ui, frontend"

# Update issue
issy update <id> --priority low
issy update <id> --status closed
issy update <id> --labels "api, backend"

# Close issue
issy close <id>
```

## Closing Issues with Learnings

When closing an issue, append a `## Resolution Notes` section if anything useful was discovered during implementation:

- Alternative approaches considered or rejected
- Unexpected gotchas or edge cases found
- Decisions made that differ from the original plan
- Useful context for future reference

Keep it brief—just capture what someone revisiting this issue would want to know.

## Issue Properties

| Property | Required | Values |
|----------|----------|--------|
| title | Yes | string |
| description | Yes | string (one-line summary) |
| priority | Yes | `high`, `medium`, `low` |
| type | Yes | `bug`, `improvement` |
| labels | No | comma-separated strings |
| status | Yes | `open`, `closed` |

## After Mutations

If your workflow tracks issues in git, consider committing updates so the tracker stays in sync.