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. Impersonal and tool-neutral. Declarative voice — no "you", no imperative aimed at the reader, and equally no first-person narration of the loop's own acts ("I'll now run audit", "I'll hand this off next"): an issue is nobody's monologue, neither addressed to a reader nor spoken by the loop. State the situation, not what an actor does about it. The issue is also a durable, tool-agnostic artefact, so it never carries the orchestration loop's own next move — any direction of what the loop runs next: most blatantly naming a skill or pipeline step ("enter specify", "dispatch implement"), but equally a role-periphrasis for the same hand-off that names nothing ("hand it to the spec writer next", "kick off the next pipeline stage"). That is session control-flow, meaningless to a tracker reader — a human months later, a different tool — who is not the loop; rephrasing it in declarative voice does not save it, because the content is harness-native.

   • The discriminator is status vs. dispatch, not whether a skill is named. A sentence stating what is true of the work — the next work itself ("next: a breakout-style trend entry") or a durable readiness status ("design settled — ready for spec production"; "implementation done — ready for audit", fine even when the phase-noun is also a skill name; "blocked on #N") — is legitimate. A sentence directing who runs what next is out whether or not it names a skill. Apply it sentence by sentence: does it describe the work's condition (keep) or an actor's next move (cut)? "What's next" otherwise lives in the issue's open/labelled state, not a prose dispatch of the next skill in the body.
   • Avoid: "You need to fix the parser because you broke escaping." / "Next step: enter specify from this comment." / "Ready to hand off to the spec writer next."
   • Use: "The parser drops backslash escapes in quoted strings." / "The design is settled here — no open load-bearing fork remains; ready for spec production."

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
Orchestration next-step in title or body — directing who runs what next, whether a skill is named ("enter specify", "dispatch implement") or periphrased ("hand it to the spec writer next")	Harness session control-flow, invisible to a tracker reader who isn't the loop; declarative phrasing doesn't save it	Drop it — a tool-neutral readiness status ("ready for spec production"); the issue's open/labelled state carries "what's next"
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
• An orchestration next-step in title or body — directing who runs what next, whether a skill is named ("enter specify", "dispatch implement") or periphrased ("hand it to the spec writer next") — in place of a tool-neutral status (a tool-neutral statement of the next work, or a readiness status, is not what this flags)
• 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.