naudachu
62c8ff976d
A checkbox is the one part of a body that is state and not prose.
Everything else is written once; boxes get ticked as the work goes, and
until now the only ways to tick one were a human with an editor or a
model rewriting the whole body. The second is worse: the rewrite re-flows
lines and re-words sentences, so the issue's diff swells around a change
that means one character. Progress was invisible too — issue_index.py
builds INDEX.md from metadata and never looked inside a body, so "3 of 7
done" required opening the file.
All three pieces are domain: a checkbox is body syntax, which is part of
the answer to "what is an issue". The parser goes in issue.py so the sync
layer can reuse it instead of redefining the format on its own side.
issue.py gains checkboxes(text) -> [Checkbox(index, line, end_line,
checked, text, section)], plus set_checkbox(text, item, checked) and
checkbox_progress(text). All pure, no I/O, importable from another layer.
The scan covers the whole text, in any section: the type/feature template
keeps child issues as checkboxes under `## Issues`, so binding the parser
to `## Acceptance criteria` would silently lose half of them; the heading
is recorded, never required. Only a marker line opens an item, so a
wrapped continuation line belongs to the item above it rather than
counting as one of its own. A `- [ ]` inside a code fence is an example
of the markup and is skipped. Line numbers are relative to the text
given, which is what lets a caller work on a body or on a whole file.
issue_ac.py lists the items numbered, grouped by heading, and ticks one
by number or by substring. An ambiguous substring is an error that prints
the matches — a coin flip would tick the wrong box and look like it
worked. It patches the file rather than round-tripping through
Issue.to_text(), so exactly one character changes: metadata order,
wording, wrapping, trailing whitespace and CRLF endings all come back
byte for byte, proven by a diff in the tests.
INDEX.md gains a progress column: `3/7` for an issue with checkboxes,
blank for one without. Counted off the body at build time and stored in
no field — a second copy of the state would be wrong by the next edit.
issue_check.py is unchanged and stays that way on purpose: an unticked
box is work not done yet, not a malformed issue, and validate() carries a
comment saying so.
Delivering a tick to the tracker is out of scope — that is push.py
--update in /tea:sync.
format.md gets one clarifying bullet. It said acceptance criteria are
checkboxes but never said what a checkbox is, so the parser had to settle
questions the format left open: any section, wrapped items, fenced
examples. Those rules are now written down where the parser and the sync
layer can both point at them.
tests/ is new, and is the convention: plain stdlib unittest, no pytest
and no third-party deps, since the code under test may not have
dependencies either. Scripts are imported via sys.path.insert and every
fixture is built in a TemporaryDirectory, never in tmp/.
python3 -m unittest discover -s tests -v 32 tests, OK
skills/issue/scripts/ still imports stdlib only, with no subprocess.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
11 KiB
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.pyand 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
## Summaryis always the first section;## Acceptance criteriais always present (exception:type/draft). These two are the anchors every reader (human or LLM) relies on.## Specis mandatory in every type. Its value is a repo path (docs/specs/auth.md), a URL, or the literalnonewhen no spec exists. Never omit the section and never invent a link —noneis an explicit, valid answer.- Acceptance criteria are
- [ ]checkboxes; each item is an objectively checkable condition, not an aspiration. - A checkbox is item markup, not a property of one section:
- [ ]unticked,- [x]ticked, and it means the same under## Issuesas under## Acceptance criteria. An item that wraps continues on an indented line and is still one item. A- [ ]inside a ``` code fence is an example of the markup, not state. Tick them withissue_ac.py, which reads the whole body on exactly these rules and rewrites one character; progress (3/7) is counted off the body and is never a metadata field. - Code references use the
path/file.ext:lineform; 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/featurecontainer 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.