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>
This commit is contained in:
+138
@@ -0,0 +1,138 @@
|
|||||||
|
---
|
||||||
|
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."
|
||||||
|
|
||||||
|
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>` |
|
||||||
|
| 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.
|
||||||
Reference in New Issue
Block a user