alunduil / alunduil/blog.alunduil.com
Two species of issue: tracking vs acceptance-criteria
- Dominant language
- Astro
- Stars
- 1
- Forks
- 1
- Avg merge
- 6h 34m
- Merged PRs (30d)
- 118
Description
## Spark
Looking at the digest for 2026-04-27→2026-05-04, alunduil/woodland-generators shipped two completely different kinds of issue the same day: acceptance-criteria issues (#119 "Add permissions, timeout-minutes, and concurrency to all workflows", #120 "Bump Node engines to >=20", #142 "Run pre-commit in GitHub Actions and re-add lychee link check") and tracking issues (#136 "Adventure plot generator (tracking)", #137–#141 export formats / settings persistence "(tracking)"). The "(tracking)" suffix is doing a lot of work that the issue type itself doesn't carry.
## Why it could be interesting
Most teams use "issue" as a single bucket for two species of work that have different definitions of done, different success criteria, and different dashboard semantics:
- **Acceptance-criteria issue**: title is a statement true when done; body lists measurable conditions. Closes via merge. Closing it is meaningful work.
- **Tracking / parking-lot issue**: a placeholder so scope you care about doesn't fall out of memory. No definition of done. Closing it is a curation decision, not an accomplishment.
The conflation has concrete consequences: 100-open-issues panics maintainers but most are parking-lot; new contributors can't tell what's pickup-able; "closed N issues this week" velocity numbers conflate shipping with grooming; tracking issues never get closed and bloat the backlog forever. Existing tools (epics in Jira, parent/sub-issue in GitHub, milestones) formalise parent-of-AC but don't fix the leaf-level mixing.
The post would name the distinction, give the consequences, and explain how I choose: AC by default; tracking only when (a) it's user-visible scope I want remembered but won't act on soon, or (b) it's an explicit parent of AC sub-issues; tracking always tagged or scoped to a separate milestone so velocity counts stay honest.
## Open questions
- [ ] Honest weakness: is there an existing industry term for the leaf-vs-leaf split? "Epic" doesn't quite fit. If there isn't, the post becomes more useful (it names a thing); if there is, the post needs to engage with prior art.
- [ ] Should tracking issues live in a separate repo / project entirely? (Avoids polluting issue search.)
- [ ] How does this interact with auto-close-via-PR conventions? (Closes/Fixes only fits AC.)
- [ ] Worked example: walk through one tracking → AC decomposition (e.g. woodland-generators#137 "Markdown export (tracking)" → what AC issues it would spawn).
## Source material
- alunduil/woodland-generators tracking issues: #134 #135 #136 #137 #138 #139 #140 #141
- alunduil/woodland-generators AC issues that closed in window: #117 #118 #119 #120 #121 #122 #123 #124 #125 #142 #166 #167 #168 #169 #170 #179 #183
- alunduil/blog.alunduil.com#62 (AC) vs #56 "Title and branding decided" (closer to tracking)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.