Skip to content

Issue tracker: GitHub

Issues and specs for this repo live as GitHub issues. Use the gh CLI for all operations. Infer the repository from git remote -v.

Conventions

  • Create: gh issue create --title "..." --body "...". Use a heredoc for a multiline body.
  • Read: gh issue view <number> --comments, including labels and filtering comments with jq when needed.
  • List: gh issue list --state open --json number,title,body,labels,comments with the required label and state filters.
  • Comment: gh issue comment <number> --body "...".
  • Label: gh issue edit <number> --add-label "..." or --remove-label "...".
  • Close: gh issue close <number> --comment "...".

Skill Rules

  • When a skill says "publish to the issue tracker", create a GitHub issue.
  • When a skill says "fetch the relevant ticket", run gh issue view <number> --comments.
  • Every implementation issue should be closed by a PR that references it with Closes #N.
  • Remaining work discovered during a session should be filed as new issues, not markdown TODO lists.

Pull requests as a triage surface

PRs as a request surface: no. External pull requests do not enter the issue triage queue.

GitHub shares one number space across issues and pull requests. For an ambiguous #<number>, run gh pr view <number> and fall back to gh issue view <number>.

Wayfinding operations

  • Map: one issue labelled wayfinder:map, with Notes, Decisions-so-far, and Fog sections.
  • Child ticket: a GitHub sub-issue linked to the map and labelled wayfinder:<type>, where type is research, prototype, grilling, or task. If sub-issues are unavailable, use a task list in the map and put Part of #<map> at the start of the child body.
  • Blocking: use native issue dependencies. Pass the blocker's numeric database ID, not its issue number or node ID, to the dependencies API. If the API is unavailable, put Blocked by: #<n>, #<n> at the start of the child body. A ticket is unblocked when all blockers are closed.
  • Frontier: list the map's open children, then remove assigned tickets and tickets with an open blocker. The first ticket in map order wins.
  • Claim: gh issue edit <number> --add-assignee @me is the session's first write.
  • Resolve: comment with the answer, close the child ticket, then append a context pointer and link to the map's Decisions-so-far.