Skills/issue/SKILL.md

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, and boss files skill-system deficiencies against the plugin's own tracker (with an autonomous-provenance body block — see ../boss/SKILL.md § Skill-system feedback). This skill is the shared convention they lean on.

The four writing rules

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

1. 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."

2. 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."

   • Where it sharpens the point, drop in a concrete code example — the snippet that triggers the failure, or the call as it should behave. A fenced block beats a prose paraphrase:

     ```rust
     parse("a\"b") // => None, want Some("a\"b")
     ```
     

3. 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"

4. 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, introduced in a1b2c3d."

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 project's issue tracker — its CLAUDE.md project facts name the repo slug and the list/show commands).

Operation	Command
List open	tea issues ls --state open
View one	tea issues <idx> (body only) — add --comments to include the discussion thread: tea issues --comments <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. Note tea issues <idx> prints the body only; pass --comments to read the existing thread first (the bare form would otherwise prompt for it interactively, which hangs a non-interactive agent).
• 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, ../boss/SKILL.md — callers that file issues through these conventions (boss files skill-system feedback on the plugin's own tracker with an autonomous-provenance body block, § Skill-system feedback).