---
title: Issues and kinds
description: Learn what a tzTrack issue holds, the five states it moves through, the eight kinds, and the outcomes a close records.
slug: /concepts/issues-and-kinds
order: 3
visibility: public
redirects_from: []
---

# Issues and kinds

An issue is one point your AI keeps in its space because it must outlast the conversation. This page explains what an issue holds, its states, its kinds, and the outcomes that end it.

## When an issue is raised

Your AI raises an issue for anything that must outlast its conversation:

- work it does not finish now;
- work another session or agent picks up;
- anything you must see or do;
- anything that must survive if this session ends or is archived.

Each issue holds one point: what was seen and a suggested resolution. An issue has no sub-items and no checklist. Closing it is the check-off.

## What an issue holds

Beside its point, an issue holds its kind, its state, its priority, what it waits for, and its claim. What it waits for can be your person, one member, the reporter, an outside event, or more evidence; its claim says which session, agent, or branch works on it. An issue also holds its labels, its area, and its due date. `find` lists issues by state, kind, priority, waiting for, claim, label, and area, and searches them by words. Comments add to an issue as work goes on, and each report of the same point joins it.

## States

| State | Means |
| --- | --- |
| `new` | The issue is raised. |
| `open` | The issue is being kept. An issue waiting for your person, one member, the reporter, or an outside event stays open, its waiting for saying who or what. |
| `waiting` | The issue waits for more evidence, and for nothing else. `wait` sets it, with what would settle it, and `reopen` opens it again. |
| `fixed` | A fix is made. |
| `closed` | The issue is closed with an outcome and a resolution. `reopen` reverses a close. |

An issue closes when a session closes it with an outcome, with one exception. A daily check closes an issue left `waiting` with no new report for 90 days, as `unexplained`. An issue waiting for you, the reporter, or an outside event stays open until someone acts; nothing closes it on its own. [Waiting and claims](/concepts/waiting-and-claims) gives each value an issue can wait for.

## Kinds

| Kind | Means |
| --- | --- |
| `bug` | Something is wrong, in code, data, text, or anything else. |
| `gap` | Something is missing. |
| `docs` | The instructions or help for a product are wrong. |
| `friction` | It works, but it is hard to use. |
| `question` | Something needs an answer. |
| `task` | Work to do. |
| `praise` | Something works well. |
| `idea` | A possible new thing to make. It takes no priority, is never marked fixed, and later requests link to it. |

A book or another project with no code is not all `docs`. What is wrong in a chapter is a `bug`, and what is missing from it is a `gap`. `docs` is for the instructions or help of a product. tzTrack also accepts other words for some kinds, `problem`, `error`, and `mistake` for a `bug` among them; [Accepted words for kinds](/reference/accepted-words-for-kinds) lists them.

## Outcomes

A close records one outcome and a resolution: what was done, or why no change is needed.

| Outcome | Reads as |
| --- | --- |
| `verified` | The fix was made and checked. |
| `done` | The work was done. |
| `as_designed` | It works as designed, so no change is needed. |
| `declined` | The change was asked for and is not made. |
| `duplicate` | Another issue holds the same point. |
| `superseded` | Later work replaced this issue. |
| `noted` | The point is recorded, and no change follows. |
| `unexplained` | The cause was not found. |

## Related

- [Glossary](/concepts/glossary) defines waiting for and a claim.
- [The tools](/reference/the-tools) lists `raise`, `find`, `close`, and the rest.
- [Refusals](/reference/refusals) lists what each tool can refuse, with its remedy.