Make the issue tracker the source of truth #93

Merged

yonlu merged 2 commits from docs/issue-driven-workflow into main 2026-08-18 20:35:45 +00:00

Conversation 0 Commits 2 Files Changed 10

+555 -202

2 Commits

Author	SHA1	Message	Date
yonlu	eb139cf872	docs: make the issue tracker the source of truth ... Work has been starting from a chat message and a plan file, so two people could pick up the same thing and neither could see the other. The tracker is where that is visible. Search before starting, claim before the first edit -- not before the commit, since the point is that the other person can see the work is taken while it is being done. If no issue covers it, open one first: that is what makes the tracker a description of the project rather than a description of the past. The conventions were already right and are written down rather than reinvented -- the Kind/Area/Priority/Platform/Reviewed/Status taxonomy, its exclusive scopes, #73 as the roadmap, real Gitea dependencies for hard blockers, and PR #83's body shape. What #83 also demonstrated is that a Closes list closes nothing reliably: it listed ten and five of them sat open in main for a fortnight. So closing is a step you take and verify, not a keyword you trust. .planning/ stops being a queue and keeps design documents and measured history -- NOTES.md, the audits, the completed plans and the arguments in them. plans/pending/ is gone, because a plan nobody is executing is an issue; everything unimplemented in it is now #85-#91, and each completed plan says which issue carries its remainder. autotag.md is kept as a historical record, marked stale where the scoring overhaul overtook it. The commit grammar is unchanged and is load-bearing for a different reason, so the issue number lives in the branch name and the PR body rather than the commit subject. Refs #92	2026-08-18 16:23:52 -04:00
yonlu	ae82fd2233	chore(scripts): reach the issue tracker from the command line ... Issues become this project's source of truth for what is wanted and what is already being worked on, which puts "search the tracker" at the top of every task rather than occasionally. Fifty-odd open issues make that a real lookup, and a lookup nobody can remember the shape of is a lookup that gets skipped -- the same way the CI log endpoint cost two sessions to a tool that 404s. Text reaches the API as JSON and never as shell, which is why the formatting half is its own Python file: an issue body is arbitrary prose carrying backticks, quotes and $, and every attempt to build that JSON inside the shell ends in nested quoting nobody can verify. Same reasoning that keeps release notes out of gitea-release.sh's argument list. Claiming is an assignment, a label and a comment together, because any one alone is a claim somebody has to go looking for. It resolves the comment before it mutates anything -- reading it afterwards is how a claim ends up half-made, with the issue saying it is taken without saying by what work -- and refuses outright if somebody else holds it. Three API shapes are pinned here because each fails quietly: - Labels are resolved to ids rather than posted as names. Gitea accepts a list of unknown names with 200 and applies none of them, so a typo reports success and does nothing. - The dependency endpoint takes a whole IssueMeta, not an index. A body of {"index": 88} answers 404, which reads exactly like a Gitea build without the feature. - close drops Status/In Progress, or a claim outlives the work. Refs #92	2026-08-18 16:23:39 -04:00