From ca3d613d9ead9b3e3faf8b14d753e23a037a4bf5 Mon Sep 17 00:00:00 2001 From: Brummel Date: Sat, 30 May 2026 14:57:04 +0200 Subject: [PATCH] feat: add issue skill for Gitea issue authoring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- issue/SKILL.md | 138 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 issue/SKILL.md diff --git a/issue/SKILL.md b/issue/SKILL.md new file mode 100644 index 0000000..0858c99 --- /dev/null +++ b/issue/SKILL.md @@ -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 ` | +| Create | `tea issues create -t "" -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.