/oh-my-issues

name: oh-my-issues
description: Cluster a GitHub issue backlog by root cause into a small set of plan-master issues, redirect children with a standardized comment, and bundle architectural-fix PRs that close clusters atomically. Use when an issue tracker has accumulated dozens of reports that share underlying defects, when asked to triage / consolidate / cluster / dedupe issues, when asked to build a plan series or roadmap from open issues, or when routing a new incoming bug into an existing plan.

oh-my-issues

Turn an issue backlog into a roadmap. Issues are symptom data, not units of work — the unit of work is the architectural defect that produces them. The end state is `open issues == open plans`, 1:1.

Core principle

Stop closing issues one at a time. Group symptoms that share a single architectural fix into a cluster, give the cluster one canonical home (a plan-master issue whose body is the design), close every child with a standardized redirect, and ship one PR per cluster that closes all children atomically. New incoming bugs get appended to the matching master as a "Round N" comment, not opened as new tracked issues.

This compounds three ways: architectural fixes retire whole symptom families, the plan's test matrix institutionalizes prevention in CI, and standardized triage makes residual inflow cheap.

When to use

• The repo has 20+ open issues and many feel like duplicates or platform-specific symptoms of the same defect.
• The user asks to "triage", "consolidate", "cluster", "dedupe", "group", or "make a plan from" the issue list.
• A new bug is filed and the user wants to know whether it belongs to existing work.
• The user wants to ship a focused PR that resolves a cluster of related issues.

When NOT to use

• Fewer than ~15 open issues: just close them.
• Issues are genuinely independent (no shared root causes): one fix per issue is correct.
• The repo has no plan-master discipline (one tracked master issue per root cause) and the user does not want to introduce one — propose first, do not impose.

Three modes

Mode 1: Cluster pass (initial reduction)

Use when the backlog has never been consolidated, or when the user wants a fresh re-cluster. Goal: go from N issues to N_plans masters in one operation.

**Start blind.** Do NOT read prior plan notes (local drafts, or `plans/*.md` in git history), prior `[plan-XX]` master issues, `plan`-labeled issues, or closed-issue redirect trails before clustering. Prior clusterings anchor the new one to their surfaces and defeat the point of re-running the pass. Cluster from the open issues alone; only after the new clusters are named may you diff against existing masters to decide which to close/supersede.

1. **Read everything in full.** Fetch every open issue's body *and* its comment thread — not just titles — **excluding** issues labeled `plan` (the existing masters; see "Start blind" above — they are compared against only after clustering). Surface-level grouping fails without full text, and reproduction steps, linked duplicates, and diagnostic output often live in comments rather than the original body. See "GitHub CLI primitives" below for the correct paginated listing + per-issue comment fetch (a single `gh issue list` call does **not** return comment bodies). 2. **Cluster by root cause, not by surface.** The clustering question is *would one architectural change retire all of these?* — not *do these mention the same word?*. "Windows" is a surface; "spawn contract violated by host shells" is a root cause. Two issues with different surfaces can share a cluster (e.g. an env-var leak in two different code paths sharing one missing env-isolation boundary). 3. **Name each cluster as an architectural problem.** Title format: `[plan-XX] <Architectural Defect> — <one-line scope>`. Example: `[plan-14] Child Process Ownership — every process the worker spawns dies with the worker`. The title must imply a fix, not a topic. 4. **Open one master issue per cluster** with a body that lists: the architectural defect, the children (by issue number), the fix sequence, and a required test matrix (host × IDE × shell, etc.) that prevents regression. 5. **Keep the design in the master issue body.** It is the public tracker and the canonical design. Do not commit plan docs to the repo or open a PR for them: plans, research and notes never go in a PR. If you want a working draft, keep it in a gitignored local folder (for example `.scratch/plans/`). 6. **Close every child** with the standardized redirect comment (see below) and state `not planned`. 7. **Verify end state:** `gh issue list --state open` returns exactly the masters and nothing else.

Target shape for ~100 issues: 4–8 masters. More than 10 means you're clustering by surface; fewer than 3 means clusters are too broad to ship as one PR each.

Mode 2: Triage (new incoming bug, steady state)

Use when a new issue is filed after consolidation is in place. Goal: never let the issue list re-accumulate.

1. **Read the new issue's body in full.** 2. **Pattern-match the symptom against existing plan masters.** For each open master, ask: *would the fix described here also fix this new bug?* If yes → it belongs to that plan. 3. **If a match exists**, post a "Round N" comment on the master that:

• Names the new child by number
• Describes the symptom in one line
• Sketches the concrete fix (1–3 lines, e.g. "guard with `case "$_SH" in /*.exe|"") _SH=bash ;; esac`")
• Adds any new test-matrix cell the bug exposes

4. **Close the child** with the standardized redirect comment, `not planned`. 5. **If no match exists** and the bug is genuinely novel: open a new plan master. Resist this. Most bugs are children of existing plans.

Mode 3: Bundle (ship the cluster)

Use when a plan slice is ready to ship. Goal: one PR closes N children atomically.

1. **List the master's children.** From the master body and consolidation comments, collect every child issue num