Fixture. This page is the stdout of
wayfinder skill tracker, run against a config with tracker value github cli and two registered ticket skills (grill-design, pre-mortem). Change either and this render changes with it.$ wayfinder skill tracker52 lines
1## Issue tracker: github cli
2
3Issues live in this repo's GitHub Issues. Use the [`gh`](https://cli.github.com/) CLI for every operation. Run it inside a clone and it infers the repo from `git remote -v`.
4
5The sub-issue and dependency flags below need `gh` 2.94.0 or later. Check with `gh --version`. For an older `gh`, see [Older gh](#older-gh).
6
7### Conventions
8
9- **Create**: `gh issue create --title "..." --body-file <path>`. Write a multi-line body to a file first.
10- **Read**: `gh issue view <n> --comments`. Add `--json <fields>` for machine-readable output.
11- **List**: `gh issue list --state open --json number,title,labels,assignees`. Filter with `--label`, `--state`, `--assignee`.
12- **Comment**: `gh issue comment <n> --body-file <path>`
13- **Label**: `gh issue edit <n> --add-label "..."` / `--remove-label "..."`
14- **Close**: `gh issue close <n> --comment "..."`
15
16### Labels
17
18`gh` refuses a label that this repo does not have. When a skill tells you to apply a label that is missing, ask the human to choose: create it with `gh label create <name>`, or publish without it. Apply the choice they make.
19
20### When a skill says "publish to the issue tracker"
21
22Create a GitHub issue.
23
24### When a skill says "fetch the relevant ticket"
25
26Run `gh issue view <n> --comments`.
27
28GitHub gives issues and pull requests one number space, so a bare `#42` can be either. Resolve it with `gh issue view 42`, and fall back to `gh pr view 42`.
29
30### Wayfinding operations
31
32The **map** is one issue. Each **ticket** is a sub-issue of the map.
33
34- **Map**: `gh issue create --label wayfinder:map --title "..." --body-file <path>`
35- **Child ticket**: `gh issue create --parent <map> --label wayfinder:<type> --title "..." --body-file <path>`, where `<type>` is `research`, `prototype`, `grilling`, or `task`. To adopt an issue that already exists, run `gh issue edit <map> --add-sub-issue <n>`.
36- **Blocking**: `gh issue edit <ticket> --add-blocked-by <blocker>`, and `--remove-blocked-by` to undo. To create a ticket that carries its edge, run `gh issue create --blocked-by <blocker> ...`.
37- **Frontier**: two steps, because no search qualifier scopes a query to one map's children.
38 1. List the children: `gh issue view <map> --json subIssues`.
39 2. For each child with `state: OPEN`, run `gh issue view <n> --json blockedBy,assignees`. The ticket is on the frontier when `assignees` is empty and every `blockedBy` node has `state: CLOSED`. First in map order wins.
40- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
41- **Resolve**: `gh issue comment <n> --body-file <path>`, then `gh issue close <n>`, then append the context pointer to the map's Decisions-so-far.
42
43### Older gh
44
45`gh` below 2.94.0 has no sub-issue or dependency flags. Reach the same GitHub features through the REST API:
46
47- **Child ticket**: `gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=<child-db-id>`
48- **Blocking**: `gh api --method POST repos/{owner}/{repo}/issues/<ticket>/dependencies/blocked_by -F issue_id=<blocker-db-id>`
49- Both endpoints take the **database id**, not the `#number`. Get it with `gh api repos/{owner}/{repo}/issues/<n> --jq .id`.
50- **Frontier**: read `issue_dependencies_summary.blocked_by` from `gh api repos/{owner}/{repo}/issues/<n>`. A value above zero means the ticket has an open blocker.
51
52Where the repo has neither the flags nor the endpoints, write `Part of #<map>` and `Blocked by: #<n>` at the top of the ticket body.