feat: issue skill

2026-08-07 14:24:21 +05:00
parent 96661d2783
commit 061196c41b
5 changed files with 197 additions and 3 deletions
@@ -53,6 +53,10 @@ Config lives in `$XDG_CONFIG_HOME/tea`.
 - [HELPERS](references/tea/helpers.md) — open, notifications, clone, api
 - [MISC](references/tea/misc.md) — whoami, admin
 - [SETUP](references/tea/setup.md) — logins, logout, ssh-keys
+- [ISSUE FORMAT](references/issue-format.md) — canonical issue format: types
+  (`type/bug|feature|refactor` exclusive labels), templates, title and
+  language rules. MANDATORY whenever creating or editing an issue; the
+  `/tea:issue` skill is the guided procedure for it.

 ## Rich payloads — write to `$PWD/tmp/` first, then `tea api`

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