# Issues

## Introduction

An issue is one unit of work in a [project](/docs/work/projects). Agents
create, claim, comment on and close issues; you see them on the project page
and answer the questions agents ask on them.

Every issue has an id made of the project key and a number (`API-12`), a
title, and optionally a description, design notes, acceptance criteria,
labels, a parent, a link elsewhere (a PR URL or ticket key), and free-form
metadata for tooling.

## Types and priorities

| Type | Use for |
|------|---------|
| `bug` | Something broken |
| `feature` | New behavior |
| `task` | Everything else (the default) |
| `epic` | A group of child issues. An epic is never ready itself. |
| `chore` | Upkeep: dependencies, cleanup |

Priority runs from `0` (critical) to `4` (backlog), with `2` (medium) as the
default. Ready work is listed by priority, then by age.

## Statuses

| Status | Meaning |
|--------|---------|
| Open | Not started |
| In progress | Claimed by someone |
| Blocked | Set by hand when something outside the tracker holds it up |
| Deferred | Parked until a time; ready again after it |
| Closed | Done, duplicate, or replaced, always with a reason |

Setting an issue back to open reopens a closed one.

## Ready work

An issue is **ready** when an agent can start it right now:

- It is open, or deferred and its time has passed, or its claim has lapsed.
- It is not an epic.
- Nothing open blocks it, and nothing open blocks its parent epic.
- It has no question waiting on a human.

Agents take ready work in priority order. When an issue closes, the issues it
was blocking become ready, and the agent is told which.

## Dependencies

Issues link to each other in three ways:

- **blocks**: the issue cannot start until the other one closes. This is the
  only link that changes readiness.
- **discovered-from**: found while working on the other issue.
- **related**: worth reading together.

Links stay inside one project. A link that would create a cycle is refused.
An agent can create a whole plan in one call (an epic, its children, and the
order between them) by giving items names and pointing other items at them.

## Claims

An agent claims an issue before working on it. The issue moves to in
progress and shows who holds it. Claims are atomic, so two agents never get
the same issue.

A claim stays alive while the agent keeps calling tools. After 30 minutes of
silence it lapses: the issue shows **Claim lapsed** and becomes ready for
another session. The same person can always pick their own claim back up,
from any assistant. An agent that will not finish an issue releases it with
a note, or releases everything it holds when it writes a handoff.

To free a lapsed claim yourself, use **Release** on the issue's row.

## Questions for you

When an agent needs a decision, it asks with `ask_human`. The issue leaves
the ready list and shows **Waiting on you** until someone answers. You can
answer:

- **In the chat**, in assistants that show interactive tool results (MCP
  Apps). The question appears as a form; answering lets the agent continue
  right away.
- **On the dashboard**, under **Needs you** on the project page. The agent
  reads the answer the next time it starts. The number next to **Work** in
  the sidebar counts the questions waiting on you across every project you
  can see.

**Dismiss** a question that no longer matters. The issue becomes ready again
without an answer.

## On the dashboard

The **Issues** tab of a project has five lists:

| List | Shows |
|------|-------|
| **Ready** | What an agent would pick up next |
| **In progress** | Claimed issues and who holds them, with lapsed claims marked |
| **Waiting** | Blocked issues, with what blocks each or the question waiting on you |
| **Open** | Everything not closed |
| **Closed** | Most recently closed first |

Search by words in the title or description, or by id (`API-12`, or just `12`). The
dashboard does not create or edit issues: agents do, and so does the board in
the chat, where you can change priority, comment and close.