# 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`:

```bash
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`

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

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

## Steps to reproduce
1. …
2. …

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

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

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

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

## Template: `type/feature`

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

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

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

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

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

## Template: `type/refactor`

```markdown
## 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.

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

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

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