<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/agents/issue-tracker.md - fork/gdu @ master</title>
<meta name="description" content="docs/agents/issue-tracker.md in fork/gdu at master.">
<meta property="og:title" content="docs/agents/issue-tracker.md - fork/gdu @ master">
<meta property="og:description" content="docs/agents/issue-tracker.md in fork/gdu at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="c636c61a7fb7f1f9a9ac9306790b41a011cbabb9">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/gdu</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/gdu</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Daniel Milde</span><span class="commit-message" data-commit="5ea284bc365a359eb212fbb75f39c257f31edf4e">docs: for contributors and agents (#626)</span><span class="snapshot-sha sha" data-commit="5ea284bc365a359eb212fbb75f39c257f31edf4e">5ea284b</span><time datetime="2026-08-17T19:58:50+02:00" title="2026-08-17 19:58:50 +0200">2026-08-17</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a href="/fork/gdu/ref/ignore/">ignore</a><a class="current" href="/fork/gdu/ref/master/">master</a><a href="/fork/gdu/ref/subvolume/">subvolume</a><a class="all" href="/fork/gdu/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/gdu/">gdu</a> / <a href="/fork/gdu/ref/master/tree/docs/">docs</a> / <a href="/fork/gdu/ref/master/tree/docs/agents/">agents</a> / <span class="cur">issue-tracker.md</span></nav>
<span class="view-stats"><span>3.7 KiB</span><span>45 lines</span></span><span class="actions"><a class="raw" href="/fork/gdu/raw/1614e9adad04894701b2d30b4e5ef38e35671098/docs/agents/issue-tracker.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Issue tracker: GitHub</h1>
<p>Issues and specs for this repo live as GitHub issues in <code>dundee/gdu</code>. Use the <code>gh</code> CLI for all operations.</p>
<h2>Conventions</h2>
<ul>
<li><strong>Create an issue</strong>: <code>gh issue create --title "..." --body "..."</code>. Use a heredoc for multi-line bodies.</li>
<li><strong>Read an issue</strong>: <code>gh issue view &lt;number&gt; --comments</code>, filtering comments by <code>jq</code> and also fetching labels.</li>
<li><strong>List issues</strong>: <code>gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'</code> with appropriate <code>--label</code> and <code>--state</code> filters.</li>
<li><strong>Comment on an issue</strong>: <code>gh issue comment &lt;number&gt; --body "..."</code></li>
<li><strong>Apply / remove labels</strong>: <code>gh issue edit &lt;number&gt; --add-label "..."</code> / <code>--remove-label "..."</code></li>
<li><strong>Close</strong>: <code>gh issue close &lt;number&gt; --comment "..."</code></li>
</ul>
<p>Infer the repo from <code>git remote -v</code> — <code>gh</code> does this automatically when run inside a clone.</p>
<h2>Pull requests as a triage surface</h2>
<p><strong>PRs as a request surface: no.</strong> <em>(Set to <code>yes</code> if this repo treats external PRs as feature requests; <code>/triage</code> reads this flag.)</em></p>
<p>When set to <code>yes</code>, PRs run through the same labels and states as issues, using the <code>gh pr</code> equivalents:</p>
<ul>
<li><strong>Read a PR</strong>: <code>gh pr view &lt;number&gt; --comments</code> and <code>gh pr diff &lt;number&gt;</code> for the diff.</li>
<li><strong>List external PRs for triage</strong>: <code>gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments</code> then keep only <code>authorAssociation</code> of <code>CONTRIBUTOR</code>, <code>FIRST_TIME_CONTRIBUTOR</code>, or <code>NONE</code> (drop <code>OWNER</code>/<code>MEMBER</code>/<code>COLLABORATOR</code>).</li>
<li><strong>Comment / label / close</strong>: <code>gh pr comment</code>, <code>gh pr edit --add-label</code>/<code>--remove-label</code>, <code>gh pr close</code>.</li>
</ul>
<p>GitHub shares one number space across issues and PRs, so a bare <code>#42</code> may be either — resolve with <code>gh pr view 42</code> and fall back to <code>gh issue view 42</code>.</p>
<h2>When a skill says "publish to the issue tracker"</h2>
<p>Create a GitHub issue.</p>
<h2>When a skill says "fetch the relevant ticket"</h2>
<p>Run <code>gh issue view &lt;number&gt; --comments</code>.</p>
<h2>Wayfinding operations</h2>
<p>Used by <code>/wayfinder</code>. The <strong>map</strong> is a single issue with <strong>child</strong> issues as tickets.</p>
<ul>
<li><strong>Map</strong>: a single issue labelled <code>wayfinder:map</code>, holding the Notes / Decisions-so-far / Fog body. <code>gh issue create --label wayfinder:map</code>.</li>
<li><strong>Child ticket</strong>: an issue linked to the map as a GitHub sub-issue (<code>gh api</code> on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put <code>Part of #&lt;map&gt;</code> at the top of the child body. Labels: <code>wayfinder:&lt;type&gt;</code> (<code>research</code>/<code>prototype</code>/<code>grilling</code>/<code>task</code>). Once claimed, the ticket is assigned to the driving dev.</li>
<li><strong>Blocking</strong>: GitHub's <strong>native issue dependencies</strong> — the canonical, UI-visible representation. Add an edge with <code>gh api --method POST repos/&lt;owner&gt;/&lt;repo&gt;/issues/&lt;child&gt;/dependencies/blocked_by -F issue_id=&lt;blocker-db-id&gt;</code>, where <code>&lt;blocker-db-id&gt;</code> is the blocker's numeric <strong>database id</strong> (<code>gh api repos/&lt;owner&gt;/&lt;repo&gt;/issues/&lt;n&gt; --jq .id</code>, <em>not</em> the <code>#number</code> or <code>node_id</code>). GitHub reports <code>issue_dependencies_summary.blocked_by</code> (open blockers only — the live gate). Where dependencies aren't available, fall back to a <code>Blocked by: #&lt;n&gt;, #&lt;n&gt;</code> line at the top of the child body. A ticket is unblocked when every blocker is closed.</li>
<li><strong>Frontier query</strong>: list the map's open children (<code>gh issue list --state open</code>, scoped to the map's sub-issues / task list), drop any with an open blocker (<code>issue_dependencies_summary.blocked_by &gt; 0</code>, or an open issue in the <code>Blocked by</code> line) or an assignee; first in map order wins.</li>
<li><strong>Claim</strong>: <code>gh issue edit &lt;n&gt; --add-assignee @me</code> — the session's first write.</li>
<li><strong>Resolve</strong>: <code>gh issue comment &lt;n&gt; --body "&lt;answer&gt;"</code>, then <code>gh issue close &lt;n&gt;</code>, then append a context pointer (gist + link) to the map's Decisions-so-far.</li>
</ul>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Issue tracker: GitHub</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Issues and specs for this repo live as GitHub issues in `dundee/gdu`. Use the `gh` CLI for all operations.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"><a-p>##</a-p> <a-tt>Conventions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>- </a-p>**Create an issue**: `gh issue create --title &quot;...&quot; --body &quot;...&quot;`. Use a heredoc for multi-line bodies.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"><a-p>- </a-p>**Read an issue**: `gh issue view &lt;number&gt; --comments`, filtering comments by `jq` and also fetching labels.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"><a-p>- </a-p>**List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq &#39;[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]&#39;` with appropriate `--label` and `--state` filters.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"><a-p>- </a-p>**Comment on an issue**: `gh issue comment &lt;number&gt; --body &quot;...&quot;`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>- </a-p>**Apply / remove labels**: `gh issue edit &lt;number&gt; --add-label &quot;...&quot;` / `--remove-label &quot;...&quot;`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>- </a-p>**Close**: `gh issue close &lt;number&gt; --comment &quot;...&quot;`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>## </a-p><a-tt>Pull requests as a triage surface</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>- **Read a PR**: `gh pr view &lt;number&gt; --comments` and `gh pr diff &lt;number&gt;` for the diff.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>- **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`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>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`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>## </a-p><a-tt>When a skill says &quot;publish to the issue tracker&quot;</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>Create a GitHub issue.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>## </a-p><a-tt>When a skill says &quot;fetch the relevant ticket&quot;</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>Run `gh issue view &lt;number&gt; --comments`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>## </a-p><a-tt>Wayfinding operations</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren&#39;t enabled, add the child to a task list in the map body and put `Part of #&lt;map&gt;` at the top of the child body. Labels: `wayfinder:&lt;type&gt;` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>- **Blocking**: GitHub&#39;s **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/&lt;owner&gt;/&lt;repo&gt;/issues/&lt;child&gt;/dependencies/blocked_by -F issue_id=&lt;blocker-db-id&gt;`, where `&lt;blocker-db-id&gt;` is the blocker&#39;s numeric **database id** (`gh api repos/&lt;owner&gt;/&lt;repo&gt;/issues/&lt;n&gt; --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren&#39;t available, fall back to a `Blocked by: #&lt;n&gt;, #&lt;n&gt;` line at the top of the child body. A ticket is unblocked when every blocker is closed.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>- **Frontier query**: list the map&#39;s open children (`gh issue list --state open`, scoped to the map&#39;s sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by &gt; 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>- **Claim**: `gh issue edit &lt;n&gt; --add-assignee @me` — the session&#39;s first write.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>- </a-p>**Resolve**: `gh issue comment &lt;n&gt; --body &quot;&lt;answer&gt;&quot;`, then `gh issue close &lt;n&gt;`, then append a context pointer (gist + link) to the map&#39;s Decisions-so-far.</span></span></pre></div></div>
</main>
</body>
</html>
