Issue buckets: parent trackers, child issues, and PR candidates

[RaresKeY]

Issue buckets: parent trackers, child issues, and PR candidates

I think we need one more lightweight coordination rule: make issue hierarchy the owner of the problem, and make PRs candidate implementations of that problem.

Right now a lot of attention lands on "which PR should merge?" When volume is high, that makes it hard to see whether the underlying issue is real, duplicated, partially solved, superseded, or part of a bigger area.

I think we should turn that around:

1. classify the issue into the right bucket;
2. find or create the smallest actionable issue slice;
3. link any PRs as candidate implementations;
4. decide whether the PR actually solves the issue as described.

The issue can be worth keeping even if the current PR is not good enough. A PR can be useful but still only solve part of the issue. Multiple PRs can exist for one issue, but the issue should stay the owner of the problem and acceptance criteria.

flowchart TD
    D["Coordination Discussion<br/>priorities + process"]

    B["Parent Tracker<br/>Stabilization + Review Scalability"]

    A["Tracker Bucket<br/>Auth + Owner Boundaries<br/>#4200"]
    S["Tracker Bucket<br/>Storage + Persistence<br/>#4377"]

    A1["Issue Slice<br/>Owner contract<br/>#4201"]
    A2["Issue Slice<br/>Chat/tool writes<br/>#4202"]
    S1["Issue Slice<br/>Source-of-truth map"]
    S2["Issue Slice<br/>Scheduled email store"]

    PA1["PR<br/>resolver + tests"]

    PA3["PR<br/>write migration"]
    PS1["PR<br/>storage audit"]
    PS2["PR<br/>email cleanup"]

    D --> B
    B --> A
    B --> S
    A --> A1
    A --> A2
    S --> S1
    S --> S2

    A1 --> PA1
    A2 --> PA3
    S1 --> PS1
    S2 --> PS2

Loading

This graph is intentionally simplified to show the base hierarchy: parent tracker -> sub-tracker buckets -> issue slices -> PRs. Real areas can have more or fewer tracker layers depending on need. The important rule is that each issue has one main owner bucket, and the smallest actionable issue slice owns the acceptance criteria. A PR can be linked, partial, superseded, or accepted without changing the value of the issue itself.

Where this should not apply

This should not become a required gate for every PR.

The organizational layer makes the most sense for broad, ambiguous, overlapping, deferred, non-milestone, or roadmap-ish work: places where ownership is unclear, several PRs may be candidate implementations, or maintainers need a durable problem bucket before deciding what should merge.

It should not block narrow fixes, active Stabilization milestone items, or clearly scoped issues/PRs where the owner area and acceptance criteria are already obvious. If the issue is narrow and the PR is narrow, the reviewer should be able to review directly. Categorization only helps when it reveals overlap, missing issue shape, risky scope, or a better parent bucket.

Mental model

• Discussions are for broad direction, open questions, and coordination.
• Parent tracker issues own a problem area.
• Sub-tracker issues split that problem area into smaller buckets.
• Child issues are the smallest actionable slices.
• PRs are candidate implementations of child issues.
• A PR should only use closing language when it actually satisfies the child issue.
• If a PR is partial, stale, too broad, or solves the wrong thing, the issue remains valid.
• Cross-cutting work should have one true parent bucket, with other areas linked in Related, dependencies, labels, or project fields.

This keeps ownership clear. One issue belongs in one main bucket. If it touches auth and storage, pick the bigger owner area and link the other area as related instead of trying to make both own it.

Examples

#4200 is a good tracker shape. It owns the Default/Local owner-profile problem. #4201, #4202, #4203, and #4204 are smaller slices. #4195 is related current-behavior work, but it is not the same thing as completing #4200.

#4377 is another good shape. It keeps storage architecture discussion out of one noisy PR thread and turns it into per-domain child issues.

#2523 is a useful existing roadmap tracker example: one parent issue, ordered slices, active slice called out, next available work made explicit.

Proposed workflow

For top-down work:

1. Maintainer or contributor opens a broad tracker for an accepted problem area.
2. The tracker lists scope, non-goals, sub-tracker issues, related trackers, and decision points.
3. Sub-tracker issues split the broad bucket into smaller owned areas.
4. Child issues define concrete behavior, acceptance criteria, and validation.
5. PRs target child issues, not the broad tracker unless the whole tracker is actually done.

For bottom-up work:

1. A bug report, proposal, or PR appears.
2. First classify the problem area.
3. Search the matching tracker bucket for duplicates, overlap, or superseding work.
4. If a good child issue exists, link there.
5. If not, open a compact child issue under the right tracker.
6. Then review any PR as "does this solve this child issue?" rather than "is this PR generally useful?"

Concrete implementation path

The first practical maintainer task is not to design every bucket up front. It is to start classifying existing issues and let the buckets emerge from the real problems already being reported.

A workable pass could look like this:

1. Query for open issues that do not have a parent link yet.
2. Pick one issue and decide whether the issue itself is valid enough to inspect.
3. If the issue is malformed, unclear, missing evidence, or not actionable, route it through a small "needs issue cleanup" bucket, label, or holding tracker and ask the author to fix the issue before PR review continues.
4. If the issue is valid, classify its owner area.
5. If the right tracker bucket already exists, attach the issue under the smallest fitting tracker.
6. If the right tracker bucket does not exist, create the missing tracker structure upward: actionable issue -> smallest sub-tracker bucket -> broader parent tracker.
7. Let linked PRs follow the issue. Since PRs should already link an issue, classifying the issue also organizes the PRs attached to it.

That means PR inspection starts from the issue being real and well-shaped enough to warrant review. If the issue is a duplicate, overlap, or malformed report, maintainers can handle that at the issue layer first instead of spending review time on every linked PR.

Over time this creates an emergent map of the project from the issues themselves. The categories should be broad, sensible, and curated carefully, but they do not need to be perfect on day one. Build the bucket structure as we go, from the actual issue queue, and let repeated problem shapes show where new tracker buckets are needed.

Later, once maintainers have established enough obvious structure, automation can help pre-classify new issues into likely buckets. A tuned pipeline or CI helper could suggest a parent tracker, related buckets, likely duplicates, or a "needs issue cleanup" route. That should be advisory at first: maintainers curate the structure, and automation reduces sorting work after the shape is already logical.

The same boundary should apply to automation too: it can suggest organization for broad, ambiguous, deferred, or overlapping work, but it should not become an automatic blocker for narrow fixes that are already reviewable.

What this helps with

• reduces duplicate PRs;
• makes contributors easier to route;
• keeps big discussions out of PR threads;
• separates issue value from PR quality;
• lets maintainers see a whole problem area before judging one PR;
• gives contributors a place to look before opening overlapping work;
• makes broad roadmap direction possible without forcing one huge implementation PR.

First practical slices

1. Agree on the vocabulary: tracker issue, sub-tracker issue, child issue, related issue, candidate PR.
2. Pilot this on existing trackers like Define an explicit Default/Local owner profile for auth-disabled no-login mode #4200, Storage architecture: source-of-truth rules and per-domain tracker #4377, and tests: Test Hardening and Scalability tracker #2523.
3. Add or reuse a project view grouped by parent issue if maintainers want that view.
4. Ask contributors to claim or open the issue slice before starting anything larger than a tiny fix.
5. Later, connect this to Add PR related-work coordinator bot #3051 so related-work hints can point contributors toward the right bucket automatically.

Related context

• How should we coordinate as contributors/maintainers? #2528 - contributor/maintainer coordination source thread.
• Stabilization v1: candidate intake #3163 - Stabilization v1 intake and bucket-style candidate routing.
• Define an explicit Default/Local owner profile for auth-disabled no-login mode #4200 - parent tracker example for Auth / Owner Boundaries.
• Storage architecture: source-of-truth rules and per-domain tracker #4377 - parent tracker example for Storage / Persistence.
• tests: Test Hardening and Scalability tracker #2523 - mature tracker example for test hardening.
• Add PR related-work coordinator bot #3051 - related-work coordinator bot idea.
• Stabilization: slow down risky merges with clear PR review rules #3694 - review/merge rules this workflow supports.
• [Proposal]: CODEOWNERS 🗳️ #593 / Proposal: CI baseline (correctness + security) gate for the repo #2288 - ownership routing and CI baseline context.

Open questions

• Should parent trackers use a tracker label, issue type, or just naming/body convention?
• Should broad trackers be listed from a pinned coordination Discussion?
• Should PR templates ask for "parent tracker" and "child issue solved" separately?
• Should closing keywords be reserved for child issues, while broad trackers use normal related links?

[TimHoogervorst]

I do like this plan, what maybe we could add to this, is also a short track route? Since if we do this for everything, we might be close to the dead by policy rule.

I do think, a lot of PRs can be merged (not as quickly as before, but quicker than this plan mentions), think of small bug fixes, non-related auth or other strict scopes or domains, or very simple UI fixes. I think for these, it would be overkill to perform these in this policy. We should still have a small review, is this really a small bugfix, and does this not touch an important domain, and is not an issue for other ongoing PRs, and if yes, it can go with the fast-track.

[RaresKeY]

Yeah, I agree with this framing. I do not want this to become a rigid process that every PR has to pass through.

The bucket structure makes the most sense for work that needs organization: broad areas, overlapping proposals, deferred/non-milestone goals, roadmap-ish work, unclear issue ownership, or places where multiple PRs may be candidate implementations of the same problem.

For narrow fixes, Stabilization milestone items, and clearly scoped PRs tied to clearly scoped issues, the reviewer should be able to review directly. If the issue is already narrow and the PR is narrow, there may be nothing useful to categorize. The hierarchy should help when ownership is unclear, not create a required ceremony before review can happen.

Longer term, once the bigger buckets exist, I think we can also experiment with advisory automation: suggest likely parent buckets, duplicates, related issues, or cleanup routes. But I would keep that as correction-friendly organization, not a hard rule. Maintainers should be able to override it, and the structure should emerge from real issue patterns rather than being designed perfectly up front.

So I think the actionable question is less "can some things be fast-tracked?" and more "which kinds of work benefit from the organizational layer, and which kinds should stay direct?" My answer would be: use the layer for ambiguous, broad, deferred, or overlapping work; keep narrow fixes and active stabilization work direct unless classification actually helps.

[TimHoogervorst]

Great! This would indeed be a quite solid and stable plan. Related to your open questions, are just how we want to organize it. I think an system with structured and tracker labeled parent issues, with a more free and open sub issues, would prefer this. With possible discussions pinned would be my way to go, but i can see this go either way.

Also for the bucketing, would it be worth looking into what kind of issues/PRs open and closed are already out there? We could run a quick script, to analyze all tickets, which domains they touch/ed, and what kind of bucket this would fall into. This would not give us the definitive ones, but maybe a good starting point for some possible buckets. Other way would just be creating them as we go.