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.

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.

Types and labels

Every issue carries exactly one type/* label:

Label	Meaning
type/bug	Something behaves incorrectly
type/feature	New capability or change in behavior
type/refactor	Internal restructuring; behavior must not change
type/draft	Idea captured for later; not ready for work

type is an exclusive scope: Gitea enforces at most one type/* label per issue, but only if the labels were created with exclusive: true. The tea labels create command (as of tea 0.14.2) cannot set that field, so missing type/* 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"}' \
  repos/{owner}/{repo}/labels

Suggested colors: type/bug #ee0701, type/feature #0e8a16, type/refactor #1d76db, type/draft #cccccc.

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.

Template: type/bug

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

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

## Steps to reproduce
1. …
2. …

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

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

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

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

Template: type/feature

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

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

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

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

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

Template: type/refactor

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

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

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

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

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

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
Свободные заметки: что известно, открытые вопросы, варианты.