Skip to content

issue-tracker.md

Latest commit

 

History

History
101 lines (67 loc) · 6.89 KB

issue-tracker.md

File metadata and controls

101 lines (67 loc) · 6.89 KB
Raw

Issue tracker: GitHub

Repo-owned. Hand-maintained — no generator writes this file. See ADR-0033.

Issues and specs for this repo live as GitHub issues at unic/unic-agents-plugins (a migration to Azure DevOps is planned, not scheduled). Use the gh CLI for all operations.

Conventions

  • Create an issue: gh issue create --title "..." --body "...". Use a heredoc for multi-line bodies.
  • Read an issue: gh issue view <number> --comments for a human read — it prints tab-delimited text, not JSON, so it cannot be piped to jq. For anything programmatic ask for the fields: gh issue view <number> --json title,body,labels,comments,state --jq '{title, state, labels: [.labels[].name], body, comments: [.comments[].body]}'.
  • 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.
  • Comment on an issue: gh issue comment <number> --body "..."
  • Apply / remove labels: gh issue edit <number> --add-label "..." / --remove-label "..."
  • Close: gh issue close <number> --comment "..."

Infer the repo from git remote -v — gh does this automatically when run inside a clone.

Labels: state, type, priority and area are documented in labels.md. A skill's canonical triage role maps onto the state tier via triage-labels.md — this repo runs an 8-state vocabulary and uses rejected, never wontfix.

Pull requests as a triage surface

PRs as a request surface: yes.

PRs run through the same labels and states as issues, using the gh pr equivalents:

  • Read a PR: gh pr view <number> --comments and gh pr diff <number> for the diff.
  • List external PRs for triage: gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments then keep only authorAssociation of CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR, or NONE (drop OWNER/MEMBER/COLLABORATOR).
  • Comment / label / close: gh pr comment, gh pr edit --add-label/--remove-label, gh pr close.

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.

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 /wayfinder. The map is a single issue with child issues as tickets. Both endpoints below are enabled on this repo — sub-issues and native issue dependencies — so neither body-convention fallback applies here.

The five wayfinder:* labels exist on the tracker — map plus the four ticket types — created by hand on 2026-08-05. Nothing maintains them and /wayfinder does not create a missing one, so treat their presence as a prerequisite to verify, not a fact to trust: this file is versioned and the tracker is not, so a deleted label or a fresh fork will disagree with it. Check with gh label list --search wayfinder, and create whatever is missing:

gh label create wayfinder:map       --description "Wayfinder map: the index issue for one effort" --color 5319E7
gh label create wayfinder:research  --description "Wayfinder ticket: investigate against primary sources" --color BFD4F2
gh label create wayfinder:prototype --description "Wayfinder ticket: build a throwaway to answer it" --color BFD4F2
gh label create wayfinder:grilling  --description "Wayfinder ticket: decide it by grilling" --color BFD4F2
gh label create wayfinder:task      --description "Wayfinder ticket: do the thing" --color BFD4F2

Every sub-issue and dependency endpoint below takes the issue's numeric database id, never its #number and never its node_id. Read it once per issue and reuse it: gh api repos/<owner>/<repo>/issues/<n> --jq .id.

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

  • Child ticket: create the issue, then link it to the map as a GitHub sub-issue:

    gh issue create --title "<question>" --body "…" --label "wayfinder:<type>"
gh api --method POST repos/<owner>/<repo>/issues/<map>/sub_issues -F sub_issue_id=<child-db-id>

    <type> is one of research, prototype, grilling, task. Once claimed, the ticket is assigned to the driving dev.

    The sub_issues POST returns the parent issue, not the child, so its .number is not confirmation that the link landed. Verify by listing: gh api repos/<owner>/<repo>/issues/<map>/sub_issues --jq '.[].number'.

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

    gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>

    GitHub reports issue_dependencies_summary.blocked_by — open blockers only, which is the live gate. A ticket is unblocked when every blocker is closed.

  • Frontier query: gh issue list has no sub-issue filter, so read the children from the map and check each one:

    gh api repos/<owner>/<repo>/issues/<map>/sub_issues \
  --jq '.[] | select(.state == "open" and (.assignee | not)) | .number' |
while read -r n; do
  gh api "repos/<owner>/<repo>/issues/$n" \
    --jq 'select(.issue_dependencies_summary.blocked_by == 0) | "\(.number) \(.title)"'
done

    The result is the frontier: open, unassigned, unblocked. First in map order wins.

  • Claim: gh issue edit <n> --add-assignee @me — the session's first write.

  • 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.

  • Research branch: a research subagent keeps its findings on feature/<scope>/<issue#>-<slug>. This name replaces the skill's throwaway research/<name> branch, because this repo's Gitflow has no research/ prefix. <scope> is the research ticket's area label with its tier stripped, as root AGENTS.md § Git branching derives it, so app:unic-archon-dlc gives unic-archon-dlc. A ticket with no area label takes repo.

    git worktree add --no-track <dir> -b feature/<scope>/<issue#>-<slug> origin/develop
git push -u origin feature/<scope>/<issue#>-<slug>
gh pr create --draft --base develop

    --no-track keeps a bare git push from going to develop. The note reaches develop only through that pull request. Keep the branch until the pull request merges, and put its link in the ticket's context pointer.

wayfinder:* labels sit outside the four-tier taxonomy — /wayfinder owns their lifecycle. See the ADR-0032 amendment.