Skip to content

TODO.md Keeps Directional Decisions in the File While the New Handoff Rule Counts Only Labelled Issues, So the Stated Count Omits Eight #1439

Closed

Description

@ptr727

PR #1435 makes the decision-labelled issue set the sole enumeration source for the queue a session
presents when it writes a handoff, and states the count. TODO.md documents the opposite practice for
the same category of item, and that PR did not sweep it.

Three surfaces in TODO.md conflict with it:

  • Its intake rule sends a reproducible defect to an issue and keeps the rest in the file.
  • Its selection step 5 says to keep "a rollout or directional decision" in TODO.md rather than filing
    it.
  • Its cluster State vocabulary defines decision as a state that "needs the maintainer", and eight
    clusters currently sit in it
    .

The concrete failure

A session follows TODO.md step 5, records a directional decision needing the maintainer as a
State decision cluster, then writes a handoff. It enumerates this repository's open issues carrying
the decision label, states a count, and reports a queue that omits all eight clusters.

That is worse than the failure GOVERNANCE.md "Communicating with the User" exists to prevent, not
better: its own line reads "A count nobody states is a queue nobody can see", and here the count is
stated and wrong, which reads as authoritative.

What needs deciding

One sentence, somewhere authoritative, saying whether a TODO.md cluster in State decision is inside
or outside the parked queue. Three shapes, and the choice is the maintainer's:

  1. Outside, and say so. TODO.md clusters are a working file rather than the queue, and the handoff
    count covers issues only. Cheapest, and it leaves eight maintainer decisions permanently outside the
    mechanism built to surface them.
  2. Inside, by filing them. A directional decision needing the maintainer becomes a decision-labelled
    issue, and step 5 changes to say so. Makes the count true and moves eight items out of the file.
  3. Inside, by counting both. The handoff enumerates the label and the State decision clusters, and
    states one combined count. Keeps the working file as-is and makes the enumeration read two sources.

Note that TODO.md's cluster State is a self-defined vocabulary that never claimed to use the GitHub
label, so this is not a naming collision to correct. It is two mechanisms for the same obligation, and
only one of them is now wired to the handoff.

Activity

  1. ptr727 commented on Oct 23, 2026

    @ptr727
    OwnerAuthor

    Closed under the maintainer's decision (ptr727, 2026-10-23) on #3391: the backlog keeps real bugs with a stated failure, features the maintainer wants, and open decisions. A finding the review loop filed on code or text a change did not touch, a refactor or consolidation chore, a tracker, a wording item, or a guard shape no session has produced is closed rather than worked. Reopen with the input and the wrong result if this issue states one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions