Files

T

Brummel ca3d613d9e feat: add issue skill for Gitea issue authoring

Unifies four issue-writing rules — impersonal voice, every claim
validated-with-evidence or flagged as a claim, imperative concise
title (checkboxes allowed for sub-points), and self-containment
(every reference directly resolvable, no unresolvable tags) — and
records the tea-CLI mechanics for create/edit/comment/close.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-05-30 14:57:04 +02:00

6.1 KiB

Raw Blame History

name, description

name	description
issue	Use when creating, editing, commenting on, or closing a Gitea issue — filing a bug, feature, or idea into the tracker, or turning a finding into a tracker item. Covers the issue-writing conventions and the tea-CLI mechanics for the operation.

issue — write and edit Gitea issues

Violating the letter of these rules is violating the spirit.

Overview

An issue is a durable artefact in the forward-queue, read later by humans and by other agents — usually without the conversation that produced it. It must stand on its own. This skill unifies how issue text is written so every issue reads the same way, and records the tea mechanics for creating and editing them.

An issue states facts and clearly-flagged claims about a concern. It is not a chat message.

When to use

Situation	Use this?
"Open an issue for X" / "file a bug about Y"	Yes
"Edit / re-label / comment on issue #N"	Yes
"Close #N" (outside a `closes #N` commit)	Yes
Turning a finding or deferred work into a tracker item	Yes
A note relevant only to the current conversation	No

Other skills file issues through these same conventions — e.g. brainstorm parks a deferred spec as a backlog issue, audit files regressions. This skill is the shared convention they lean on.

The four writing rules

These apply to every issue, on create and on edit.

No direct address. Impersonal, declarative voice. No "you", no imperative aimed at the reader. State the situation, not instructions to a person.
- Avoid: "You need to fix the parser because you broke escaping."
- Use: "The parser drops backslash escapes in quoted strings."
Validated or flagged. Every factual statement is either verified — carrying its evidence (command output, log line, file:line, a reproduction) — or explicitly marked as an unverified claim, so a reader never mistakes a guess for a fact.
- Verified: "parse() returns None for a\"b — see parser.rs:84 and the repro below."
- Flagged: "Claim (unverified): the regression likely landed in 0b96983; not yet bisected."
Imperative, concise title. Verb-first, one line, no trailing period — scannable in the list, mirroring commit-message style. Checkboxes (- [ ]) are allowed in the body for sub-points or a small acceptance checklist.
- Avoid: "parser bug" / "There is a problem with the parser."
- Use: "Preserve backslash escapes in quoted strings"
Self-contained. The issue is understandable on its own, without the originating conversation. Every reference resolves directly for any reader — an issue/PR number (#42), a commit SHA, a full URL, or a path that exists in the repo. No dangling pointers ("as discussed", "see the spec") and no tags, codes, or acronyms that need outside knowledge to resolve; spell them out or link them.
- Avoid: "Fixes the regression from the ledger refactor; see the spec."
- Use: "Fixes the regression behind #38; spec at docs/specs/0004-escaping.md."

Language: title and body are English — an issue is a repo artefact mirrored to Gitea ("would it be committed → English", per ~/dev/CLAUDE.md).

tea mechanics

tea is pre-authenticated via its own config (~/.config/tea/). Never read or echo that file — it holds a token. tea auto-detects the repository from the git remote; override with --repo owner/name when running outside the repo (the slug lives in issue_tracker.repo if a project profile sets it).

Operation	Command
List open	`tea issues ls --state open`
View one	`tea issues <idx>`
Create	`tea issues create -t "<title>" -d "<body>" -L "<labels>"`
Edit body/title	`tea issues edit <idx> -t "<title>" -d "<body>"`
Re-label	`tea issues edit <idx> --add-labels a --remove-labels b`
Comment	`tea comment <idx> "<body>"`
Close / reopen	`tea issues close <idx>` / `tea issues reopen <idx>`

Notes:

The body flag is --description/-d, not --body. For a multi-line body pass a heredoc via command substitution: tea issues create -t "..." -d "$(cat <<'EOF' … EOF\n)".
Labels are matched by name (-L feature,bug); they must already exist in the repo. The project's label vocabulary lives in ~/dev/CLAUDE.md (BLOCKER, feature, bug, idea, in-progress).
Before editing, view the issue first (tea issues <idx>) — do not edit blind. Status/discussion updates go in a tea comment, not by overwriting the body.
Routine closing is done by a closes #N line in the commit body on push (per ~/dev/CLAUDE.md); tea issues close is for closing without an accompanying commit.

Common mistakes

Mistake	Why it's bad	Instead
"You should…" / reader-directed imperative	Breaks rule 1, ages badly	State the situation declaratively
A guess written as fact	Misleads future actors	Flag it: "Claim (unverified): …"
Title as a noun blob ("parser bug")	Not scannable	Imperative verb phrase
`-d` body with a guessed flag (`--body`)	tea rejects it	`--description`/`-d`
Editing without viewing first	Clobbers others' edits	`tea issues <idx>`, then edit
Reading/echoing tea's config	Token leak	tea is already authenticated
Dangling reference ("see the spec", an internal code)	Reader can't resolve it	Link it: `#N`, SHA, URL, or repo path

Red flags — STOP

The word "you" anywhere in title or body
A factual statement with neither evidence nor a "claim" flag
A title that is a noun phrase or ends with a period
A reference with no resolvable locator (#N, a commit SHA, a URL, or an existing repo path), or an acronym/code needing outside knowledge
About to tea issues edit without having viewed the issue
About to print or cat the tea config

Cross-references

~/dev/CLAUDE.md — repo-English rule, label vocabulary, the closes #N commit convention (the tracker is the forward-queue).
../brainstorm/SKILL.md, ../audit/SKILL.md — callers that file issues through these conventions.

6.1 KiB Raw Blame History