marketplace/skills/issue/references/format.md

Issue format

Canonical format for every issue in this project, whether it ever reaches a tracker or not. 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).

Nothing here depends on Gitea. How these files are mapped onto a tracker is the sync layer's business — see /tea:sync.

Identity

An issue is one file, tmp/issues/<id>.md, and id is a slug: lowercase ASCII, digits, single dashes, derived from the title. The slug is the identity. It is stable for the life of the issue — a retitled issue keeps its slug, and an issue pushed to a tracker keeps it too. Tracker numbers are a foreign key stored in a field, never the name of anything.

tmp/issues/wire-sqlc-appclick.md

Metadata block

One field per line, lists inline, so plain grep works without a parser:

---
id: wire-sqlc-appclick
state: open
labels: [type/task, tech/sql]
assignees: [naudachu]
milestone: v0.2
depends: [migrate-schema]
origin: gitea
branch: feat/wire-sqlc
gitea: claude-skills/tea#42
remote-updated: 2026-08-09T18:24:01Z
synced: 2026-08-09T18:40:00Z
url: https://git.noodles.cam/claude-skills/tea/issues/42
---
# Wire sqlc into the appclick repo layer

## Summary
…

Field	Owner	Meaning
id	domain	slug; equals the file name
state	domain	open or closed
labels	domain	see namespaces below; exactly one type/*
assignees	domain	logins; may be empty
milestone	domain	title, or none
depends	domain	ids this issue depends on — the authoritative graph
origin	domain	local, or the name of a tracker this also lives in
gitea	sync	the handle in that tracker: owner/repo#N
branch	sync	the tracker's branch link (Gitea ref); push fills an empty one with the current git branch, and never overwrites a filled one
url, synced, remote-updated, comments	sync	bookkeeping

Domain fields render first, in the order above; sync fields follow, sorted.

origin is domain-owned on purpose: whether a piece of work exists anywhere but here is a fact about the work. Where that is, and how to reach it, is the sync layer's business — the domain carries gitea: and the rest through load/save verbatim and never reads them. That passthrough is why one file can represent a local issue and a synced one without a second format.

origin: local is a durable state, not a pending one. An issue that never leaves this machine is complete and valid. Pushing is optional and additive.

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 (at most one label from the namespace), 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	Meaning
type/bug	Something behaves incorrectly in existing code
type/task	Implementation of new functionality
type/refactor	Internal restructuring: file moves, architecture; behavior must not change
type/test	Writing or fixing tests
type/feature	Container: several issues delivering one unit of business value
type/draft	Idea captured for later; not ready for work

severity/* — at most one

severity/low, severity/medium, severity/high, severity/showstopper, severity/critical.

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.

Label colors are not part of the format: a hex code is how a tracker paints a chip, not what an issue is. They live in skills/sync/scripts/map.py and are applied on push.

Dependencies

depends: in the metadata block is the graph, and it holds ids:

depends: [migrate-schema, add-pool-cfg]

An optional ## Depends on section, placed right after ## Spec, carries the human explanation — one reference per line, with a reason where it helps:

## Depends on
- migrate-schema — нужна схема БД из этого issue
- add-pool-cfg

The section is prose and is passed to and from a tracker unchanged; only depends: is walked when the graph is computed. Keeping them consistent is on you — issue_check.py warns when the section names an id that depends: does not list. Omit the section when there are no dependencies; never write an empty one.

Draw the graph with issue_tree.py. The reverse direction is a grep:

grep -ln 'depends:.*migrate-schema' tmp/issues/*.md

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 by id.
• Screenshots are allowed but their content must be duplicated as text — an LLM reading these files cannot see 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 their depends:. Keep implementation detail in the children; the feature body stays at business level.

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

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

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

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

## 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. Locally it is just the milestone: field; a tracker-side milestone must already exist for a push to attach the issue to it.
• Project — a set of issues tracked by status columns (Backlog, ToDo, InProgress, Ready, Done). Not represented in this format and not reachable through the Gitea API — web UI only.