Files

T

Brummel 268ee705f4 feat(specify): record in-context fork resolutions as auditable issue comments

The `spec-skeptic` `scope-fork` juror reads only the seeding issue plus
the spec. On the legitimate `specify` direct-entry path — a fork settled
in a long in-context design discussion — that resolution lives only in
ephemeral chat the juror cannot replay. When the issue body lags the
discussion (still lists the fork open), the juror correctly blocks, and
a design BLOCK escalates without self-correction. The result: auto-sign
was structurally almost unreachable for the in-context entry path.

Close the blind spot by giving the juror an auditable source instead of
weakening the gate. When `specify` enters in-context and a tracker issue
still lists a now-resolved fork as open, the orchestrator posts a
reconciliation comment recording each fork's resolution WITH provenance
(a record of the user's decision, never a fresh orchestrator one) before
writing the spec. The comment is persistent and audit-able — unlike a
carrier digest — so it, not the orchestrator's confidence, is what the
juror checks.

Separation of powers keeps it honest: the orchestrator writes the
comment, the adversarial juror enforces the provenance requirement. A
bare `decision: X` with no provenance does not resolve the fork — the
re-dispatched juror blocks on it. The escalation rule and the
three-field carrier are untouched; only the juror's information changes.

Mechanics:
- specify Step 1.5: reconciliation-comment sub-step, provenance format,
  issue-less fallback (auto-sign -> human sign-off, no weak spec-note).
- spec-skeptic: replace the "quoted in the dispatch" drift; juror reads
  the issue WITH comments via `issue_tracker.show_cmd`; provenance check.
- new profile slot `issue_tracker.show_cmd` (must render comments);
  documented in schema + template.
- issue skill: `tea issues <idx>` is body-only; `--comments` required
  (verified against tea 0.14.1 and Aura #55 — 180 vs 144 lines).
- consistency: design.md out-of-scope, README, pipeline.md, boss skill.

2026-06-12 15:54:47 +02:00

6.6 KiB

Raw Blame History

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. This skill is the shared convention they lean on.

The four writing rules

These apply to every issue, on create and on edit.

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."
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")
```
```
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"
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.

6.6 KiB Raw Blame History