marketplace/skills/use/references/issue-format.md

Issue format

Canonical format for every issue created or edited via tea. Designed to be unambiguous for both humans and LLMs: fixed English section headers in a fixed order, verifiable acceptance criteria, one issue = one deliverable. Source spec: the project wiki (Issues-Workflow).

Language rules

• Issue title: English, imperative mood, no type prefix — the type lives in the label, not the title. Good: Fix tea-guard crash on empty settings file. Bad: fix: crash, [bug] crash, Крашится гвард.
• Section headers: the exact English literals below, as ## headings, in the given order. Do not translate, rename, or reorder them.
• Body prose (text inside sections): Russian.

Label namespaces

Four namespaces classify an issue. Two are exclusive (Gitea enforces at most one label from the scope), two are free-form:

Namespace	Exclusive	Purpose
type/*	yes	What kind of work; primarily its business value. Mandatory, exactly one.
severity/*	yes	Business impact. At most one; apply when the impact is known.
tech/*	no	Technology the issue is bound to. Any number.
comp/*	no	System component of this repo. Any number; no preset — project-specific.

type/* — mandatory, exactly one

Label	Color	Meaning
type/bug	#ee0701	Something behaves incorrectly in existing code
type/task	#0e8a16	Implementation of new functionality
type/refactor	#1d76db	Internal restructuring: file moves, architecture; behavior must not change
type/test	#fbca04	Writing or fixing tests
type/feature	#5319e7	Container: several issues delivering one unit of business value
type/draft	#cccccc	Idea captured for later; not ready for work

severity/* — at most one

Label	Color
severity/low	#c2e0c6
severity/medium	#fbca04
severity/high	#eb6420
severity/showstopper	#ee0701
severity/critical	#b60205

tech/* — any number

Technology-bound labels, e.g. tech/sql (pgx, sqlc, sql-migrate — persistent storage), tech/obs (grafana, loki, prometheus, alloy — observability), tech/postgres.

comp/* — any number

Components of this repo's system, e.g. comp/appclick. No preset list — derive from the project.

Creating exclusive labels

Gitea enforces exclusivity only if the label was created with exclusive: true. The tea labels create command (as of tea 0.14.2) cannot set that field, so missing type/* and severity/* labels MUST be created via tea api:

tea api --login "$GITEA_LOGIN" -X POST \
  -d '{"name":"type/bug","color":"#ee0701","exclusive":true,"description":"Something behaves incorrectly in existing code"}' \
  repos/{owner}/{repo}/labels

tech/* and comp/* are non-exclusive; either tea labels create or tea api works for them.

Dependencies

An issue may explicitly depend on others. Declare that in an optional ## Depends on section placed right after ## Spec, one #N reference per line:

## Depends on
- #12 — нужна схема БД из этого issue
- #15

Omit the section when there are no dependencies — never write an empty one.

Shared rules

• ## Summary is always the first section; ## Acceptance criteria is always present (exception: type/draft). These two are the anchors every reader (human or LLM) relies on.
• ## Spec is mandatory in every type. Its value is a repo path (docs/specs/auth.md), a URL, or the literal none when no spec exists. Never omit the section and never invent a link — none is an explicit, valid answer.
• Acceptance criteria are - [ ] checkboxes; each item is an objectively checkable condition, not an aspiration.
• Code references use the path/file.ext:line form; related issues as #N.
• Screenshots are allowed but their content must be duplicated as text — an LLM posting through tea api cannot read images.
• If acceptance criteria grow past ~5 unrelated items, split the issue (or promote it to a type/feature container with child issues).

Template: type/bug

## Summary
Что сломано и где проявляется, одно-два предложения.

## Spec
`docs/specs/auth.md`, URL — или `none`.

## Steps to reproduce
1. …
2. …

## Expected
Что должно было произойти.

## Actual
Что происходит на самом деле: вывод команды, лог.

## Environment
Только релевантное: версии, ОС, конфигурация.

## Acceptance criteria
- [ ] баг не воспроизводится по шагам выше
- [ ] добавлена проверка на регрессию (если применимо)

Template: type/task

## Summary
Что нужно сделать, одно-два предложения.

## Spec
Ссылка или `none`.

## Motivation
Какую проблему пользователя/системы это решает.

## Acceptance criteria
- [ ] проверяемое условие
- [ ] …

## Constraints
Что НЕ входит в объём; технические рамки. (опционально)

Template: type/refactor

## Summary
Что перестраиваем и в каких файлах (`path/file:line`).

## Spec
Ссылка или `none`.

## Motivation
Чем плохо текущее состояние: дублирование, связность, читаемость.

## Invariants
Что НЕ должно измениться: поведение, публичные API, форматы данных.

## Acceptance criteria
- [ ] проверяемое условие (тесты зелёные, старый путь удалён, …)

Template: type/test

## Summary
Что покрываем тестами и где (`path/file:line`).

## Spec
Ссылка или `none`.

## Motivation
Зачем: регрессия после бага, пробел в покрытии, флаки-тест.

## Test cases
- сценарий → ожидаемый результат
- …

## Acceptance criteria
- [ ] перечисленные кейсы покрыты и зелёные
- [ ] тесты проходят в CI

Template: type/feature

A container: one unit of business value delivered by several child issues. Child issues carry their own type/* (task, bug, test, …) and link back via ## Depends on or the ## Issues list here. Keep implementation detail in the children; the feature body stays at business level.

## Summary
Бизнес-ценность одним-двумя предложениями.

## Spec
Ссылка или `none`.

## Motivation
Какую проблему пользователя/системы это решает.

## Issues
- [ ] #N — краткое описание части
- [ ] …

## Acceptance criteria
- [ ] все дочерние issues закрыты
- [ ] проверяемое условие уровня фичи (например, e2e-сценарий работает)

Template: type/draft

A parking spot for ideas that are not fleshed out yet. Minimal structure, no acceptance criteria required. Before implementation starts, a draft MUST be promoted: relabeled to a concrete type and rewritten into that type's template.

## Summary
Идея одним-двумя предложениями.

## Spec
Ссылка или `none` (для драфтов обычно `none`).

## Notes
Свободные заметки: что известно, открытые вопросы, варианты.

Containers beyond type/feature

• Milestone — a set of issues with an optional time bound. Manage via tea milestones / tea milestones issues.
• Project — a set of issues describing one project, tracked by status columns. Standard statuses: Backlog, ToDo, InProgress, Ready, Done. The Gitea projects API is not exposed via tea subcommands — use the web UI.