alunduil / alunduil/blog.alunduil.com

Two species of issue: tracking vs acceptance-criteria

Open
#71 0 comments 0 reactions 0 assignees View on GitHub
idea
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.