Skills/issue/SKILL.md

---
name: issue
description: 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.

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`; 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>` (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` — callers that file
  issues through these conventions.