Issues and kinds #

View this page as Markdown

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 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 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.

Glossary defines waiting for and a claim.
The tools lists raise, find, close, and the rest.
Refusals lists what each tool can refuse, with its remedy.