diff --git a/skills/issue/SKILL.md b/skills/issue/SKILL.md index 73259b7..55f70cd 100644 --- a/skills/issue/SKILL.md +++ b/skills/issue/SKILL.md @@ -14,17 +14,22 @@ always `--login "$GITEA_LOGIN"`, never a literal name (see `/tea:use`). ## Steps 1. **Read the format**: load `../use/references/issue-format.md`. -2. **Pick the type** — `bug`, `feature`, `refactor`, or `draft` (for ideas - not ready for work). If it is not obvious from the request, ask the user - (one question). +2. **Pick the type** — `bug`, `task`, `refactor`, `test`, `feature` (a + container for several issues with one business value), or `draft` (for + ideas not ready for work). If it is not obvious from the request, ask the + user (one question). 3. **Ensure labels exist**: `tea labels list --login "$GITEA_LOGIN" -o json`. - For each missing `type/*` label, create it via `tea api` with - `"exclusive": true` exactly as shown in the format doc. Do NOT use - `tea labels create` for these — it cannot set exclusivity. + For each missing **exclusive** label (`type/*`, and `severity/*` when + used), create it via `tea api` with `"exclusive": true` exactly as shown + in the format doc. Do NOT use `tea labels create` for these — it cannot + set exclusivity. Non-exclusive `tech/*` and `comp/*` labels may be created + either way; apply them when the technology or component is evident. 4. **Compose title and body** per the format: English imperative title without a type prefix; the type's template with all sections present, in order, headers in English, prose in Russian; `## Spec` filled with a repo path, a URL, or the literal `none` — ask the user if you cannot determine which. + If the issue depends on others, add a `## Depends on` section right after + `## Spec` (one `#N` per line); omit it otherwise. 5. **Post via tmp/ + tea api** (the body is always multi-line, so entity commands are off the table — see "Rich payloads" in `/tea:use`): ```bash @@ -35,14 +40,18 @@ always `--login "$GITEA_LOGIN"`, never a literal name (see `/tea:use`). ``` The create endpoint takes label **IDs** (integers), not names — take them from the `tea labels list` output of step 3 (or from the create response). - If labels fail to attach on create, fall back to - `PUT repos/{owner}/{repo}/issues/{n}/labels` with `{"labels": []}`. -6. **Report**: show the issue URL and the applied `type/*` label. + The `labels` array holds every applied label: the `type/*` ID plus any + `severity/*`, `tech/*`, `comp/*` IDs. If labels fail to attach on create, + fall back to `PUT repos/{owner}/{repo}/issues/{n}/labels` with + `{"labels": []}`. +6. **Report**: show the issue URL and the applied labels. ## Editing an existing issue -When asked to bring an existing issue to the format: fetch it -(`tea issues --login "$GITEA_LOGIN" -o json`), restructure the body into +When asked to bring an existing issue to the format: fetch it with the use +skill's script (`python3 ../use/scripts/fetch_issue.py ` relative to this +skill's base dir — writes `tmp/issue//data` + comments, prints a compact +index; no `--login`, it resolves the pin itself), restructure the body into the type's template without losing information, then `PATCH repos/{owner}/{repo}/issues/{n}` with the new title/body and ensure exactly one `type/*` label is set. diff --git a/skills/use/SKILL.md b/skills/use/SKILL.md index 94069a4..889f369 100644 --- a/skills/use/SKILL.md +++ b/skills/use/SKILL.md @@ -86,10 +86,11 @@ Notes: - [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. +- [ISSUE FORMAT](references/issue-format.md) — canonical issue format: label + namespaces (`type/*`, `severity/*` exclusive; `tech/*`, `comp/*` free), + types `bug|task|refactor|test|feature|draft`, templates, dependencies, + 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` diff --git a/skills/use/references/issue-format.md b/skills/use/references/issue-format.md index d99966b..6d05e84 100644 --- a/skills/use/references/issue-format.md +++ b/skills/use/references/issue-format.md @@ -2,7 +2,8 @@ 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. +order, verifiable acceptance criteria, one issue = one deliverable. Source +spec: the project wiki ([Issues-Workflow](https://git.noodles.cam/claude-skills/tea/wiki/Issues-Workflow)). ## Language rules @@ -13,30 +14,79 @@ order, verifiable acceptance criteria, one issue = one deliverable. the given order. Do not translate, rename, or reorder them. - **Body prose** (text inside sections): Russian. -## Types and labels +## Label namespaces -Every issue carries exactly one `type/*` label: +Four namespaces classify an issue. Two are exclusive (Gitea enforces at most +one label from the scope), two are free-form: -| Label | Meaning | +| 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 | |---|---| -| `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 | +| `severity/low` | `#c2e0c6` | +| `severity/medium` | `#fbca04` | +| `severity/high` | `#eb6420` | +| `severity/showstopper` | `#ee0701` | +| `severity/critical` | `#b60205` | -`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`: +### `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`: ```bash tea api --login "$GITEA_LOGIN" -X POST \ - -d '{"name":"type/bug","color":"#ee0701","exclusive":true,"description":"Something behaves incorrectly"}' \ + -d '{"name":"type/bug","color":"#ee0701","exclusive":true,"description":"Something behaves incorrectly in existing code"}' \ repos/{owner}/{repo}/labels ``` -Suggested colors: `type/bug` `#ee0701`, `type/feature` `#0e8a16`, -`type/refactor` `#1d76db`, `type/draft` `#cccccc`. +`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: + +```markdown +## Depends on +- #12 — нужна схема БД из этого issue +- #15 +``` + +Omit the section when there are no dependencies — never write an empty one. ## Shared rules @@ -52,7 +102,8 @@ Suggested colors: `type/bug` `#ee0701`, `type/feature` `#0e8a16`, - 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. +- 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` @@ -81,7 +132,7 @@ Suggested colors: `type/bug` `#ee0701`, `type/feature` `#0e8a16`, - [ ] добавлена проверка на регрессию (если применимо) ``` -## Template: `type/feature` +## Template: `type/task` ```markdown ## Summary @@ -120,6 +171,53 @@ Suggested colors: `type/bug` `#ee0701`, `type/feature` `#0e8a16`, - [ ] проверяемое условие (тесты зелёные, старый путь удалён, …) ``` +## Template: `type/test` + +```markdown +## 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. + +```markdown +## 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 @@ -137,3 +235,11 @@ template. ## 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.