t3 checkpoint ref=refs/t3/checkpoints/ZWM2OGU3MTQtNGQ5OS00MDZjLTg3NDgtNGMyOTAzOTJlODZi/turn/23

docs/agents/issue-tracker.md

@@ -0,0 +1,50 @@
+# Issue tracker: Forgejo
+
+Issues and PRDs for this repository live as Forgejo issues at
+`git.s1q.dev/phg/fuse-mail-dir-by-tag`.
+
+Use this base command for all operations:
+
+`fgj --hostname git.s1q.dev issue <command> -R phg/fuse-mail-dir-by-tag`
+
+## Conventions
+
+- **Create an issue**:
+  `fgj --hostname git.s1q.dev issue create -R phg/fuse-mail-dir-by-tag --title "..." --body "..."`
+- **Read an issue**:
+  `fgj --hostname git.s1q.dev issue view <number> -R phg/fuse-mail-dir-by-tag`
+- **Read an issue as JSON**:
+  `fgj --hostname git.s1q.dev issue view <number> -R phg/fuse-mail-dir-by-tag --json`
+- **List issues**:
+  `fgj --hostname git.s1q.dev issue list -R phg/fuse-mail-dir-by-tag --state open`
+- **List issues as JSON**:
+  `fgj --hostname git.s1q.dev issue list -R phg/fuse-mail-dir-by-tag --state open --json`
+- **Comment on an issue**:
+  `fgj --hostname git.s1q.dev issue comment <number> -R phg/fuse-mail-dir-by-tag --body "..."`
+- **Apply a label**:
+  `fgj --hostname git.s1q.dev issue edit <number> -R phg/fuse-mail-dir-by-tag --add-label "..."`
+- **Remove a label**:
+  `fgj --hostname git.s1q.dev issue edit <number> -R phg/fuse-mail-dir-by-tag --remove-label "..."`
+- **Close an issue with a comment**:
+  `fgj --hostname git.s1q.dev issue close <number> -R phg/fuse-mail-dir-by-tag --comment "..."`
+
+Pull requests are not part of the triage request surface.
+
+## When a skill says “publish to the issue tracker”
+
+Create a Forgejo issue with `fgj issue create` using the hostname and repository arguments above.
+
+## When a skill says “fetch the relevant ticket”
+
+Read it with `fgj issue view <number>` using the hostname and repository arguments above.
+
+## Wayfinding operations
+
+The **map** is a single Forgejo issue with child issues represented by links in its body.
+
+- **Map**: an issue labelled `wayfinder:map`, containing the Notes, Decisions-so-far, and Fog sections.
+- **Child ticket**: an issue with `Part of #<map>` at the top of its body and a `wayfinder:<type>` label, where the type is `research`, `prototype`, `grilling`, or `task`.
+- **Blocking**: record `Blocked by: #<number>, #<number>` at the top of the child issue body. A ticket is unblocked when every referenced blocker is closed.
+- **Frontier**: inspect the map’s open child issues, discard blocked or already claimed tickets, and take the first remaining ticket in map order.
+- **Claim**: record the acting developer or agent in a comment before starting work.
+- **Resolve**: comment with the answer, close the child issue, and append a pointer to the result under the map’s Decisions-so-far section.