claude-skills/marketplace
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
62c8ff976d2affaf76a8d5d93898c5d7ae2c69e8
marketplace/skills/issue/SKILL.md
T
naudachu 62c8ff976d feat: tick in-body checkboxes from a domain script 
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>
2026-08-10 15:41:15 +05:00

9.6 KiB
Raw Blame History

name, description
name description
issue Work with this project's issues as units of work — create, read, grep, validate, and walk their dependency graph. Entirely offline; issues are local markdown files and need no tracker. Load when the user asks to file/create an issue, read or find issues, check an issue against the format, or see what depends on what. For pushing to or pulling from Gitea, load /tea:sync instead.

/tea:issue — issues as units of work

An issue is a markdown file in tmp/issues/. This skill covers everything you do with an issue: writing one, reading one, checking it against the canonical format, and walking the dependency graph.

Nothing here touches the network. No tea, no Gitea, no login. An issue that lives only on this machine is a first-class issue, not a draft waiting to be uploaded. Synchronizing with a tracker is a separate, optional layer — /tea:sync.

Read references/format.md before creating or editing an issue. It is the single source of truth for identity, metadata, types, labels, templates, and language rules.

Identity: the slug

The file name is the id and the id is a slug — tmp/issues/wire-sqlc-appclick.md. It never changes, not when the title changes and not when the issue is pushed somewhere. Tracker numbers live in a metadata field (gitea: owner/repo#42), never in a file name and never in depends:.

Consequence worth internalizing: #42 means nothing in this layer. Refer to issues by id.

Scripts

All offline, all in <skill-base-dir>/scripts/.

Script What it does
issue_new.py --type T --title "…" create tmp/issues/<slug>.md from the type's template
issue_check.py [id…] validate against the canonical format; exit 1 on errors
issue_ac.py <id> [--check N|TEXT] list the body's checkboxes; tick or untick one
issue_tree.py [id…] draw the dependency graph from depends:
issue_index.py rebuild tmp/issues/INDEX.md
issue.py the domain module the others import — not a command 
tmp/issues/INDEX.md                 table of every issue — read this first
tmp/issues/wire-sqlc-appclick.md    metadata block + `# Title` + body
tmp/issues/wire-sqlc.comments.md    comment thread (written by /tea:sync only)
tmp/issues/tree-<id>.md             saved graph (issue_tree.py --write)

Reading: grep, don't parse

Metadata is one field per line with inline lists precisely so plain grep works. INDEX.md first, then the files:

grep -l  'labels:.*type/bug' tmp/issues/*.md      # all bugs
grep -l  'origin: local' tmp/issues/*.md          # never pushed anywhere
grep -ln 'depends:.*migrate-schema' tmp/issues/*.md   # who depends on it
grep -A3 '## Acceptance criteria' tmp/issues/wire-*.md
grep -c  '^- \[ \]' tmp/issues/wire-sqlc-appclick.md  # open checkboxes

Read whole files only for the issues the task actually needs.

Creating an issue

  1. Read the format: references/format.md.
  2. Pick the type — bug, task, refactor, test, feature (a container for several issues with one business value), or draft (an idea not ready for work). If it is not obvious from the request, ask the user (one question).
  3. Scaffold it: 
    python3 <skill-base-dir>/scripts/issue_new.py \
  --type task --title "Wire sqlc into the appclick repo layer" \
  --label tech/sql --label comp/appclick --depends migrate-schema
    English imperative title with no type prefix; --depends takes ids.
  4. Fill the sections with Edit — every section of the template present and in order, headers English, prose Russian. ## Spec gets a repo path, a URL, or the literal none; ask the user if you cannot determine which.
  5. Check it: 
    python3 <skill-base-dir>/scripts/issue_check.py wire-sqlc-appclick

One file = one issue. Several related issues = several files, linked through depends:.

The issue is now real and complete. Publishing it to Gitea is a separate decision — /tea:sync — and does not change the file's status here.

Editing an issue

Edit the file. Change state: to close it, edit labels:, add ids to depends:. Re-run issue_check.py afterwards, and issue_index.py to refresh the table. Checkboxes are the exception — use issue_ac.py, below.

If the issue is synced (origin: gitea), your edit is local until you run push.py --update from /tea:sync. Nothing tracks that drift automatically.

Ticking checkboxes

A checkbox is the one part of a body that is state and not prose, so it has a command of its own. Never rewrite a body just to tick a box: the rewrite re-flows lines and re-words sentences, and the issue's diff swells around a change that means one character.

python3 <skill-base-dir>/scripts/issue_ac.py wire-sqlc-appclick
python3 <skill-base-dir>/scripts/issue_ac.py wire-sqlc-appclick --check 3
python3 <skill-base-dir>/scripts/issue_ac.py wire-sqlc-appclick --check "регресс"
python3 <skill-base-dir>/scripts/issue_ac.py wire-sqlc-appclick --uncheck 3

With no flag it prints the numbered list with each item's state, grouped by the heading the item sits under. --check / --uncheck take that number or a substring of the item's text (case-insensitive).

  • Every checkbox in the body counts, not just ## Acceptance criteria. A type/feature keeps its children as checkboxes under ## Issues, and they are numbered in the same list. The script is named after the section most boxes live in, nothing more.
  • A substring must match exactly one item. Two matches is an error that lists them; pick by number instead. It never guesses.
  • Exactly one character of the file changes. Metadata, wording, wrapping and trailing whitespace all come back byte for byte, so git diff and the tracker's diff show the tick and nothing else.
  • Examples inside a ``` fence are markup, not state — they are skipped.
  • INDEX.md gains a progress column (3/7, blank when the issue has no boxes), recomputed from the body on every build and stored in no field. issue_ac.py rebuilds the index after a successful tick.

Getting the tick to the tracker is a separate step — push.py --update in /tea:sync.

Writing a proper description

Issues get filed on the run — "comments aren't pulled", "the guard broke". That is a request, not a statement of work: no reproduction steps, no path/file:line, acceptance criteria nobody can check. Rewriting one into the canonical format is a procedure, not improvisation.

  1. Read the issue whole, and everything it points at — the ids in depends:, the ## Spec target, the files it names.

  2. Determine the type and its template. The type/* label selects one of the templates in references/format.md, and that template's section list is the shape you are aiming at. If the label is missing or wrong, decide it now and fix labels:; promoting a type/draft to a concrete type is this same step.

  3. Locate the anchor points in the code. Grep the repo for every file, symbol, command, and error string the issue mentions, until you can name lines:

    grep -rn 'GITEA_LOGIN' hooks/ skills/

    Work that does not exist yet still has anchor points — the files the change will land in, and the ones that will call it.

  4. Gather the missing context. What has to be there when you are done:

    • code references in the path/file.ext:line form, for every place the change lands;
    • reproduction steps — exact commands and their real output (type/bug splits them across ## Steps to reproduce / ## Expected / ## Actual);
    • acceptance criteria that are objectively checkable: a command that exits 0, a file that exists, a section that is present — not aspirations;
    • a real value for ## Spec — a repo path, a URL, or the literal none.

    A missing fact is either found in the repository or becomes a question to the user. Inventing one is forbidden. Ask in one batch, and keep none in ## Spec as the legitimate answer it is — never a plausible-looking link.

  5. Rewrite the sections with Edit: every section of the template, in the template's order, English headers and Russian prose. Replace the body; do not append a second telling of the same issue below the old one.

  6. Check it:

    python3 <skill-base-dir>/scripts/issue_check.py wire-sqlc-appclick

    Errors mean malformed, warnings mean the type's template is not fully filled in. Re-run issue_index.py if the labels changed.

The procedure is identical for origin: local and origin: gitea — it works on tmp/issues/<id>.md, and this layer does not know the difference. Getting the rewritten body into the tracker is a separate decision — push.py --update in /tea:sync — and is no part of this.

Dependency graph

depends: is the authoritative edge list; the body's ## Depends on section is prose for humans. issue_check.py warns when they disagree.

python3 <skill-base-dir>/scripts/issue_tree.py                 # all roots
python3 <skill-base-dir>/scripts/issue_tree.py wire-sqlc-appclick --write

A type/feature plus its children read as one document: draw the tree once for the shape, then grep the files.

Layering rule

This skill must keep working with skills/sync/ deleted. Every import under scripts/ is stdlib, and subprocess is not among them:

grep -rhn '^import\|^from' skills/issue/scripts/ | sort -u

If you find yourself wanting a tracker concept here — an issue number, a login, an HTTP call — it belongs in /tea:sync.

Reference in New Issue View Git Blame Copy Permalink