---
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, 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 reachability test.** The issue stands on its
   own, without the conversation that produced it. Apply one test to
   every reference: *starting from this entry alone — a reader may have
   arrived by a direct comment-anchor link, no chat and no sibling
   comments loaded — can they follow it to its target?* If not, it is a
   dangling pointer: reproduce the content inline, or swap in a
   resolvable locator.

   **Reachable — use these:** content stated or quoted inline; an
   issue/PR number (`#42`, or cross-repo `Skills #11`); a commit SHA
   (`a1b2c3d`, resolves on push); a full URL; a repo-relative path,
   optionally with a line range (`parser.rs:84-90`); another comment by
   its full URL (the link ending `#issuecomment-NNNN` — the bare fragment
   only resolves in-page on that comment's own issue); a same-entry
   section marker (`§5`); a convention-resolvable in-repo slug (a
   `docs/specs/` slug, a cycle number).

   **Unreachable — rewrite or inline; these never resolve from the
   tracker:**
   - **The producing chat by reference, in any phrasing** — "the
     in-context discussion", "settled before the run", "the session /
     cycle transcript", an in-context juror/panel verdict (`D3`). No
     anchor can ever reach it; the irrecoverable case. (Quoting the
     decision's words inline is fine — see the carve-out below.)
   - **A weak prose pointer** — "above", "below", "earlier", "the prior
     comment", "logged above", "as discussed" — with no resolvable
     locator: the target comment's full URL, a `#N`, or a *same-entry*
     `§` marker. A `§` pointing into another comment or file is itself
     unreachable — link that comment's URL.
   - **An artifact named by role, not locator** — "the OOS harness
     issue", "see the ledger", a `Depends on` target — carrying no `#N` /
     SHA / URL / repo path.
   - **A path outside this repo** — `/mnt/...`, `~/.claude/...`, a Claude
     auto-memory slug, another project's `BLOCKED.md`. Only a path in
     *this* repo is reachable.
   - **A bare code or ordinal whose defining set the entry does not
     reproduce** — a plan-item / ledger / lens code (`I7`, `C16`), an
     index ("decision #5"). Gloss it in place, or restate the set.
   - **A locator-shaped token that resolves to nothing** — a template
     placeholder (`#(A)`), or a `#`-number in the wrong format (`#0071` —
     issue refs are unpadded integers like `#71`; a leading zero matches
     nothing).

   A chat decision becomes referenceable only by being **written to the
   tracker first** — log it, then cite that comment; a chat is reachable
   by being written down, never by being pointed at (the `boss`
   reference-issue mechanic, `../boss/SKILL.md` § The reference issue).

   **These stay self-contained** (don't strip them chasing the rule): an
   inline dated verbatim quote of a chat decision ("`mach es so!`" —
   2026-06-29) — the reader sees the exact words, and only a surplus
   "settled in-context" sentence *beside* it is the violation; an
   enumerated fork `(A)`/`(B)` whose options are restated here; a
   glossary code glossed inline; a provenance sentence whose fact is also
   stated inline, so long as it embeds no unresolvable pointer (keep
   "decided", drop or anchor "logged above"). Flag the *pointer* a
   tracker-only reader can't resolve, never the content it reproduces.

   - Avoid: "Approach B (the mechanism refinement decided + logged
     above)." — "logged above" points to a sibling comment with no
     resolvable URL, so a reader who landed on this comment can't reach
     the refinement; the violation is the unresolvable pointer, and it
     stands even when the mechanism is restated inline. The bare label
     "Approach B" compounds it — it indexes an A/B fork this entry never
     reproduces, so the letter means nothing to a reader who didn't see
     the fork laid out.
   - Use — drop the chat-native label, name the option on its own terms,
     then inline or link the refinement: "The honest per-held-cycle bleed
     (accrue each held cycle, dump at close) — refined in
     `http://…/issues/148#issuecomment-2142`."

**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 |
| Pointer to the chat that produced the entry ("in-context", "the cycle transcript", a juror code) | The chat is invisible to a tracker reader — never reachable | Quote the words inline, or log the decision to the tracker and cite that comment's full URL |
| "above" / "below" / "the prior comment" with no anchor | A reader on a direct comment link can't tell which entry | Add the comment's full URL, a `#N`, or a *same-entry* `§` marker |
| Artifact or path named without a locator — "the harness issue", "see the ledger", `/mnt/...`, `~/.claude/...` | Nothing to navigate to from the tracker | Supply a `#N`, SHA, URL, or in-repo path — or reproduce the fact inline |
| Bare un-glossed code or ordinal (`I7`, `C16`, "decision #5") | Its defining set isn't in the entry | Gloss it inline, or restate the set |

## 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, an
  existing repo path, a `docs/specs/` slug or cycle number, a same-entry
  `§`, or the fact reproduced inline), or a bare never-glossed code whose
  defining set isn't in the entry — in particular:
  - a pointer to the chat that produced the entry ("in-context", "the
    cycle transcript", a juror code); the chat is never tracker-reachable
  - "above" / "below" / "the prior comment" / "as discussed" with no
    resolvable locator — the comment's full URL, a `#N`, or a same-entry `§`
  - an out-of-repo path (`/mnt`, `~/.claude`, a `memory <slug>`,
    another project's `.md`) cited as the basis
  - a `#`-token that resolves to nothing — a `#(A)` placeholder or a
    wrong-format `#0071`
- 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 with an autonomous-provenance body block
  (§ Skill-system feedback), and its § The reference issue is the
  constructive escape hatch for rule 4: log a chat decision to the
  tracker first, then cite that comment instead of pointing at the chat.