|
| 1 | +# Issue tracker: GitHub |
| 2 | + |
| 3 | +Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations. |
| 4 | + |
| 5 | +## Artifact language: Russian |
| 6 | + |
| 7 | +All human-readable artifacts the agent creates MUST be written in Russian: issue titles, issue bodies, issue comments, close comments, wayfinder map and child ticket bodies and answers, PR titles, PR bodies, PR comments, and commit messages. Code identifiers, branch names, label names, and `gh` commands stay in English; only the prose is in Russian. Never default to English prose because a template or example in this file is in English — translate the content to Russian. |
| 8 | + |
| 9 | +## Conventions |
| 10 | + |
| 11 | +- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies. |
| 12 | +- **Read an issue**: `gh issue view <number> --json number,title,body,labels,comments`. |
| 13 | +- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters. |
| 14 | +- **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body. |
| 15 | +- **Comment on an issue**: `gh issue comment <number> --body "..."` |
| 16 | +- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."` |
| 17 | +- **Close**: `gh issue close <number> --comment "..."` |
| 18 | + |
| 19 | +Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone. |
| 20 | + |
| 21 | +## Pull requests as a triage surface |
| 22 | + |
| 23 | +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ |
| 24 | + |
| 25 | +When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents: |
| 26 | + |
| 27 | +- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff. |
| 28 | +- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`. |
| 29 | +- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`. |
| 30 | + |
| 31 | +- **PR and commit language**: PR titles, PR bodies, and PR comments MUST be in Russian (see **Artifact language: Russian** above). Commit messages MUST also be in Russian. |
| 32 | +- **Create a PR**: `gh pr create --title "..." --body "..."` with title and body in Russian. Use a heredoc for multi-line bodies. |
| 33 | + |
| 34 | +GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`. |
| 35 | + |
| 36 | +## When a skill says "publish to the issue tracker" |
| 37 | + |
| 38 | +Create a GitHub issue. |
| 39 | + |
| 40 | +## When a skill says "fetch the relevant ticket" |
| 41 | + |
| 42 | +Read it as in **Read an issue** above. |
| 43 | + |
| 44 | +## Wayfinding operations |
| 45 | + |
| 46 | +Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. |
| 47 | + |
| 48 | +- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`. |
| 49 | +- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. |
| 50 | +- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed. |
| 51 | +- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. |
| 52 | +- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write. |
| 53 | +- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far. |
0 commit comments