# Issue tracker: Gitea

Issues and specs for this repo live as Gitea issues. Use the
[`tea`](https://gitea.com/gitea/tea) CLI for all operations.

## Repository context

Run commands inside the clone so `tea` can infer the repository and login from
its Git remote. If the clone has multiple Gitea remotes or logins, pass
`--remote <name>` or `--login <name>`. Use `--repo <owner>/<repo>` only outside
the clone.

Before the first operation, verify the instance with
`tea logins list --output json`. If it is missing, ask the user to run
`tea login add`; never ask for or handle their access token.

## Conventions

- **Create an issue**: `tea issues create --title "..." --description "..."`.
  For a multi-line body, use shell command substitution around a quoted heredoc:

  ```bash
  tea issues create --title "..." --description "$(cat <<'EOF'
  Multi-line issue body.
  EOF
  )"
  ```

- **Read an issue with comments**:
  `tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
- **List issues**:
  `tea issues list --state open --fields index,state,author,url,title,body,assignees,labels,comments --output json`,
  adding `--labels "label-one,label-two"`, `--assignee <user>`, or another
  supported filter as needed. Paginate with `--page` and `--limit`; do not
  assume the default first 30 results are complete.
- **Comment on an issue**: `tea comments add <number> --description "..."`.
- **Apply or remove labels**: `tea issues edit <number> --add-labels "..."` or
  `--remove-labels "..."`. Separate multiple labels with commas.
- **Assign or unassign**: `tea issues edit <number> --add-assignees "..."` or
  `--remove-assignees "..."`.
- **Close**: post the closing explanation with
  `tea comments add <number> --description "..."`, then run
  `tea issues close <number>`.
- **Reopen**: `tea issues reopen <number>`.
- **Raw API fallback**: use `tea api '<endpoint>'` only for a Gitea feature
  without a first-class `tea` command. Prefer `{owner}` and `{repo}`
  placeholders so repository context remains explicit.

Use `--output json` for machine-readable reads. Do not scrape table output.

## Pull requests as a triage surface

**PRs as a request surface: no.** _(Set this to `yes` if this repo treats
external pull requests as feature requests; `/triage` reads this flag.)_

When set to `yes`, PRs use the same labels and states as issues:

- **Read a PR with comments and diff**:
  `tea pulls <number> --comments --fields index,state,author,url,title,body,diff,assignees,labels,comments --output json`.
- **List open PRs**:
  `tea pulls list --state open --fields index,state,author,author-id,url,title,body,assignees,labels,comments --output json`.
  Determine whether an author is external from the repository's Gitea membership
  data; the PR listing does not classify author membership.
- **Comment**: `tea comments add <number> --description "..."`.
- **Apply or remove labels**: `tea pulls edit <number> --add-labels "..."` or
  `--remove-labels "..."`.
- **Close**: `tea pulls close <number>`.

Gitea pull requests use the repository's issue index space, so `#42` may refer
to either surface. If the context is unclear, inspect it with
`tea pulls 42 --output json`; if that command reports no PR, read it with
`tea issues 42 --output json`.

## When a skill says "publish to the issue tracker"

Create a Gitea issue with `tea issues create`.

## When a skill says "fetch the relevant ticket"

Run
`tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.

## Wayfinding operations

`/wayfinder` uses one **map** issue with linked **child** issues. These
conventions store relationships in issue bodies, so they work across Gitea
versions.

- **Map**: create one issue labelled `wayfinder:map` containing the Notes,
  Decisions-so-far, and Fog sections. Use
  `tea issues create --labels "wayfinder:map"` with its title and description.
- **Child ticket**: start the body with `Part of #<map>` and apply a
  `wayfinder:<type>` label: `research`, `prototype`, `grilling`, or `task`. Add
  each child as a task-list item in the map body to preserve frontier order.
- **Blocking**: put `Blocked by: #<n>, #<n>` near the top of the child body. A
  ticket becomes unblocked after every referenced blocker closes.
- **Frontier query**: list all open children, order them by the map's task list,
  and discard tickets with an open blocker or an assignee. Select the first
  remaining ticket. Fetch each referenced blocker; do not infer its state from
  map text.
- **Claim**: resolve the active username with `tea whoami`, then run
  `tea issues edit <n> --add-assignees "<username>"` as the session's first
  write. Do not assume `@me` works.
- **Resolve**: run `tea comments add <n> --description "<answer>"`, close the
  child with `tea issues close <n>`, then append a context pointer and link to
  the map's Decisions-so-far section.