# Issue tracker: GitLab

Issues and specs for this repo live as GitLab issues in `<owner>/<repo>`. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations, and pass `-R <owner>/<repo>` to every `glab issue`, `glab mr` and `glab label` command: a bare `glab` resolves the project from the remotes, which can be another project than this one. Write that project in `glab api` paths too, URL-encoded (`projects/<owner>%2F<repo>/...`), not `projects/:id/`; `glab api` and `glab repo view` do not take `-R` (`glab repo view <owner>/<repo>` is positional). Never rely on the implicit default: before the first `glab issue create -R <owner>/<repo>` of a session, check that `glab repo view <owner>/<repo>` resolves to the project named above, and confirm with the user if it does not.

## Conventions

- **Create an issue**: `glab issue create -R <owner>/<repo> --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
- **Read an issue**: `glab issue view -R <owner>/<repo> <number> --comments`. Use `-F json` for machine-readable output.
- **List issues**: `glab issue list -R <owner>/<repo> -O json` with appropriate `--label` filters.
- **Comment on an issue**: `glab issue note -R <owner>/<repo> <number> --message "..."`. GitLab calls comments "notes".
- **Apply / remove labels**: `glab issue update -R <owner>/<repo> <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
- **Close**: `glab issue close -R <owner>/<repo> <number>`. `glab issue close -R <owner>/<repo>` does not accept a closing comment, so post the explanation first with `glab issue note -R <owner>/<repo> <number> --message "..."`, then close.
- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create -R <owner>/<repo>`, `glab mr view -R <owner>/<repo>`, `glab mr note -R <owner>/<repo>`, etc., the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.

Infer the repo from `git remote -v` only when setting this file up, and have the user confirm it; after that use the repo named above.

## Merge requests as a triage surface

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

When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:

- **Read an MR**: `glab mr view -R <owner>/<repo> <number> --comments` and `glab mr diff -R <owner>/<repo> <number>` for the diff.
- **List external MRs for triage**: `glab mr list -R <owner>/<repo> -O json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
- **Comment / label / close**: `glab mr note -R <owner>/<repo>`, `glab mr update -R <owner>/<repo> --label`/`--unlabel`, `glab mr close -R <owner>/<repo>`.

Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.

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

Create a GitLab issue.

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

Run `glab issue view -R <owner>/<repo> <number> --comments`.

## Wayfinding operations

Used by `/skill:wayfinder`. The **map** is a single issue with **child** issues as tickets.

- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create -R <owner>/<repo> --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description, linked to the map (`glab issue create -R <owner>/<repo> --linked-issues <map> --link-type relates_to`), and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
- **Blocking**: GitLab's **native blocking link**, the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note -R <owner>/<repo> <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
- **Frontier query**: list the map's children with `glab api projects/<owner>%2F<repo>/issues/<map>/links`, keeping open issues that carry a `wayfinder:<type>` label; drop any with an open blocker: a native `blocked_by` link to an open issue (`glab api projects/<owner>%2F<repo>/issues/<child-iid>/links`), or an open issue in the `Blocked by` line, or an assignee; first in map order wins.
- **Claim**: `glab issue update -R <owner>/<repo> <n> --assignee @me`, the session's first write.
- **Resolve**: `glab issue note -R <owner>/<repo> <n> --message "<answer>"`, then `glab issue close -R <owner>/<repo> <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.