Issue tracker

This skill is the tracker integration point for any workflow that needs to talk to the repo's issue tracker (wayfinder, triaging, etc.). It is premade with GitHub operations — swap the body for Jira / Linear / a local-markdown tracker as needed; keep the headings so consuming skills keep working.

The GitHub operations below are adapted from mattpocock/skills — issue-tracker-github.md, with endpoint details verified against the live API.

Conventions

• Create an issue: gh issue create --title "..." --body "...". Use a heredoc for multi-line bodies (backticks in inline --body strings get eaten by shell expansion).
• Read an issue: gh issue view <number> --comments.
• List issues: gh issue list --state open with --label filters as needed.
• Comment: gh issue comment <number> --body "...".
• Apply / remove labels: gh issue edit <number> --add-label "..." / --remove-label "..." (create labels first with gh label create — editing with a nonexistent label fails).
• Close: gh issue close <number> --comment "...".
• Numeric database id: several endpoints below need the issue's database id, not its #number or node_id: gh api repos/<owner>/<repo>/issues/<number> --jq .id.

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.

Wayfinding operations

Used by the wayfinder skill. The map is a single issue with child issues as tickets.

• Map: a single issue labelled wayfinder:map, holding the Destination / Notes / Decisions-so-far / Fog body. gh issue create --label wayfinder:map.

• Child ticket: an issue linked to the map as a native GitHub sub-issue — do this, don't just mention #1 in the body:

  gh api repos/<owner>/<repo>/issues/<map-number>/sub_issues \
    -F sub_issue_id=<child-database-id>

  The map's children are then queryable via gh api repos/<owner>/<repo>/issues/<map-number>/sub_issues --jq '.[].number' and render as sub-issues in the GitHub UI. Labels: wayfinder:<type> (research/prototype/grilling/task/domain-modeling). Once claimed, the ticket is assigned to the driving dev.

• Blocking: GitHub's native issue dependencies — the canonical, UI-visible representation:

  gh api --method POST repos/<owner>/<repo>/issues/<blocked-number>/dependencies/blocked_by \
    -F issue_id=<blocker-database-id>

  Read a ticket's blockers via gh api repos/<owner>/<repo>/issues/<number>/dependencies/blocked_by --jq '.[].number' (and the reverse via .../dependencies/blocking). Prefer these dedicated endpoints over the issue_dependencies_summary field on the issue object, which can lag right after a write. A ticket is unblocked when every blocker is closed.

• Frontier query: list the map's open children via the sub-issues endpoint above, drop any with an open blocker (from dependencies/blocked_by) or an assignee; first in map order wins.
• Claim: gh issue edit <number> --add-assignee @me — the session's first write.
• Resolve: gh issue comment <number> --body "<answer>", then gh issue close <number>, then append a context pointer (gist + link) to the map's Decisions-so-far.

Branch association (map ↔ feat/* branch)

A wayfinder map may have a feat/* branch that lives across the whole effort. The convention is:

1. Default name: derived from the map issue's title slug — feat/<slug> (lowercased, hyphenated). For map title "Auth JWT refactor" → feat/auth-jwt-refactor. forge-flow's step 2 uses this rule to name the branch on first cut.
2. Optional explicit pointer: the map issue body may carry a ## Feat branch heading with the explicit branch name, overriding the default slug derivation. Example:

   ## Feat branch
   feat/auth-jwt-refactor

3. Query — to find an existing branch for a given map issue:
   • First read the map body and look for the ## Feat branch heading; if present, treat that as authoritative.
   • Else compute the slug from the map title and look up git branch -a --list "feat/<slug>*". The first matching branch (local, then remote-tracking) is the one to reuse.
   • Else fall back to a gh pr list --head "feat/<slug>" --state open lookup — an open PR on a matching feat/* head is also a hit.

The slug-derived name is the association. The explicit pointer exists for cases where the branch was renamed or doesn't follow the default naming rule.