Agent skill

Issue Backlog Clustering

by thedotmack in thedotmack/claude-mem

Groups a large GitHub issue backlog by root cause into plan-master issues, redirects the child issues, and bundles one PR per cluster that closes them together.

Apache-2.0Auto-check passedDevelopment

Install Issue Backlog Clustering

skills CLI
$ npx skills add thedotmack/claude-mem --skill oh-my-issues -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install thedotmack/claude-mem oh-my-issues --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/thedotmack/claude-mem.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugin/skills/oh-my-issues .claude/skills/oh-my-issues && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
oh-my-issues
GitHub stars
99k
Token cost
~2.9k tokens
SKILL.md length
1,328 words
Files
1
Skills in repo
26
Repo updated
First seen
Licence
Apache-2.0

At a glance

Groups a large GitHub issue backlog by root cause into plan-master issues, redirects the child issues, and bundles one PR per cluster that closes them together.

  • Works in 7 steps: Read everything in full. Fetch every… → Cluster by root cause, not by surface.… → Name each cluster as an architectural… → …
  • Consolidating a tracker that holds dozens of duplicate or related bug reports
  • SKILL.md covers Core principle, When to use, When NOT to use and Three modes, plus 7 more sections
  • Calls gh and jq

What it does

Issues are treated as symptoms, and the architectural defect behind them as the real unit of work. In the first pass the agent reads every open issue in full, comment threads included, groups symptoms that share a single fix, and gives each cluster one canonical home: a plan-master issue plus a design document in a plans folder. The goal is open issues and open plans matching one to one.

Child issues are closed with a standardized redirect comment, and one PR per cluster closes all of its children at once. New bugs are appended to the matching master as a numbered round comment instead of becoming new tracked issues, and the skill can route an incoming bug into existing work. It suits backlogs of twenty or more open issues; with fewer than about fifteen it says to just close them, and it will not impose a plans folder on a repo that does not want one.

When your agent uses it

  • Consolidating a tracker that holds dozens of duplicate or related bug reports
  • Building a roadmap from open issues grouped by shared root cause
  • Checking whether a newly filed bug belongs to work that is already planned
  • Shipping one focused PR that resolves a whole cluster of related issues

Example prompts

  • “Cluster our open GitHub issues by root cause and propose the plan-master issues.”
  • “Dedupe the backlog, then draft the redirect comment for each child issue.”
  • “Does this new crash report belong to an existing plan? Check it against the masters.”

Requirements

  • GitHub CLI (gh) with access to the repository's issues

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. Read everything in full. Fetch every open issue's body and its comment thread — not just titles. Surface-level grouping fails without full…
  2. Cluster by root cause, not by surface. The clustering question is would one architectural change retire all of these? — not do these…
  3. Name each cluster as an architectural problem. Title format: [plan-XX] — . Example: [plan-02] Spawn-Contract Templating — canonical…
  4. Open one master issue per cluster with a body that lists: the architectural defect, the children (by issue number), the fix sequence, and…
  5. Mirror each master as plans/0X-.md in the repo. The issue is the public tracker; the doc is the design. They reference each other.
  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.

What it can do on your machine

Read from SKILL.md and the folder at commit fa8ab09. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • gh
    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use gh, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Issue Backlog Clustering loads about 2.9k tokens when it runs. Until then it costs about 121 tokens; SKILL.md has 1,328 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~121
When it runs · the whole SKILL.md, loaded when a task matches
~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from thedotmack/claude-mem at commit fa8ab09, republished under its Apache-2.0 licence (© thedotmack). 1,328 words, ~2,904 tokens.

Download SKILL.mdSave it as .claude/skills/oh-my-issues/SKILL.md (or your agent's skills folder).
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 + a plans/0X-*.md design doc), 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 lacks plans/ discipline 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. Goal: go from N issues to N_plans masters in one operation.

  1. Read everything in full. Fetch every open issue's body and its comment thread — not just titles. 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-02] Spawn-Contract Templating — canonical ${CLAUDE_PLUGIN_ROOT} resolution across all hosts. 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. Mirror each master as plans/0X-<slug>.md in the repo. The issue is the public tracker; the doc is the design. They reference each other.
  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 + plans/0X-*.md. 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 number routed to this plan.
  2. Verify each child's symptom is covered by the architectural fix in the PR. If a child is not covered, the PR is not ready or that child belongs in a different plan.
  3. Generate the PR description: title is the plan slice (e.g. "fix(spawn): canonical ${CLAUDE_PLUGIN_ROOT} resolution"); body lists every child with Closes #N so GitHub auto-closes them on merge.
  4. Add the test matrix from the plan to CI in the same PR. Without the matrix, the cluster will re-emerge.
  5. After merge, the master issue can be closed only if every child was covered. If the plan has remaining scope, leave the master open and link the PR as a partial-shipping checkpoint.
Show full SKILL.md (464 more words)Show less

Naming a plan master

A plan-master title must imply its fix.

Bad (surface)Good (architectural)
Windows bugsSpawn-Contract Templating across hosts
Worker crashesWorker / Daemon Lifecycle Hardening — supervision, health, retry
Auth issuesWorker Env Isolation — strip host CLI env from the SDK subprocess
Install failuresInstaller Failure Transparency — cross-IDE error taxonomy + 12×4 test matrix

If you cannot write a one-line architectural scope, the cluster is wrong.

The standardized redirect comment

Use this exact phrasing on every child closure. Consistency lets contributors recognize the pattern at a glance and keeps the audit trail searchable.

text
Consolidating into #<MASTER> (plan-XX). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress.

Close as not planned (not completed) — the child was a symptom, not a unit of work.

GitHub CLI primitives

Resolve repo:

bash
repo_json=$(gh repo view --json owner,name)
owner=$(jq -r '.owner.login // .owner.name' <<<"$repo_json")
repo=$(jq -r '.name' <<<"$repo_json")

List all open issues (the read-everything pass). Two gotchas:

  • gh issue list --json comments returns only a count placeholder, not the comment bodies. You must fetch comments per issue with gh issue view <N> --json comments.
  • Any explicit --limit silently truncates if the backlog is larger. Always check the total open count first.
bash
# 1. Confirm total — never trust an arbitrary --limit.
# Note: GitHub's REST API treats PRs as issues, so .open_issues_count
# from /repos/{owner}/{repo} is actually issues + PRs. Use the search
# API to get the issue-only count.
total=$(gh api "search/issues?q=repo:$owner/$repo+is:issue+is:open" --jq '.total_count')
echo "Open issues: $total"

# 2. List bodies (set --limit at or above the true total)
gh issue list --state open --limit "$total" \
  --json number,title,body,labels,author,createdAt

# 3. For each issue, fetch its full comment thread
for n in $(gh issue list --state open --limit "$total" --json number --jq '.[].number'); do
  echo "=== Issue #$n ==="
  gh issue view "$n" --json comments \
    --jq '.comments[] | "\(.author.login) (\(.createdAt)): \(.body)"'
done

If total > 1000, paginate via the REST API: gh api "repos/$owner/$repo/issues?state=open&per_page=100&page=N" looped until the result array is empty (note this includes PRs, so filter select(.pull_request|not)).

Open a plan master:

bash
gh issue create \
  --title "[plan-02] Spawn-Contract Templating — canonical \${CLAUDE_PLUGIN_ROOT} resolution across all hosts" \
  --body-file plans/02-spawn-contract-templating.md \
  --label plan,plan-02

Post the consolidation comment + close the child:

bash
gh issue comment <CHILD> --body "Consolidating into #<MASTER> (plan-XX). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress."
gh issue close <CHILD> --reason "not planned"

Append a "Round N" triage comment to a master:

bash
gh issue comment <MASTER> --body "$(cat <<'EOF'
**Round N consolidation**

- #<CHILD> (<one-line symptom>) folded into this plan as <classification>.

Proposed fix: <1–3 line sketch>.

Adds matrix cell: <host/IDE/shell combination>.
EOF
)"

Verify final state:

bash
gh issue list --state open --json number,title \
  | jq -r '.[] | "\(.number)\t\(.title)"'

Output should be exactly the plan masters.

Plan master body template

Save as plans/0X-<slug>.md and use as --body-file for the master issue.

markdown
# [plan-XX] <Architectural Defect> — <one-line scope>

## Defect

<One paragraph: what is structurally broken, why it produces the observed family of symptoms.>

## Children

- #N — <symptom one-liner>
- #N — <symptom one-liner>
- ...

## Fix sequence

1. <First architectural change — bounded, reviewable>
2. <Second>
3. ...

## Test matrix

| Axis A | Axis B | Required behavior |
|---|---|---|
| ... | ... | ... |

The matrix lives in CI. A future regression must fail CI before a user can file.

## Out of scope

<What this plan deliberately does not cover, with pointers to other plan masters.>

Health checks

Run periodically against the plan masters to catch the failure modes.

  • Graveyard master: master issue has accumulated 5+ "Round N" comments without a shipping PR. The plan needs a forcing PR or it must be split.
  • Over-broad master: the children's fixes cannot fit one PR. Split into two plans with narrower scope.
  • Surface-clustered master: the children share a topic but not a fix. Re-cluster by root cause; some children belong to different plans.
  • Drift between issue and doc: the plan master body and plans/0X-*.md disagree. Pick one as canonical (the doc) and regenerate the issue body from it.

Stop conditions

For a cluster pass: stop when gh issue list --state open returns exactly the masters.

For a triage: stop when the new child is closed and the master has a Round-N entry.

For a bundle: stop when the PR is merged and every listed child is auto-closed by Closes #N.

Failure modes worth refusing

  • Premature clustering before reading every issue body in full. Don't.
  • Closing children before the master is open. Children must always have a redirect target.
  • Using the redirect comment for issues that aren't symptoms (e.g. genuine feature requests with no shared root cause). Those stay open or get their own track.
  • Closing a master before every listed child is shipped. The master is the contract; closing it early breaks the audit trail.

© thedotmack, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in plugin/skills/oh-my-issues of thedotmack/claude-mem.

Open the folder on GitHubat commit fa8ab09

Compare with similar skills

Issue Backlog Clustering next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Issue Backlog Clustering compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Issue Backlog Clustering this skillthedotmack/claude-mem99k—~2.9kAutomated safety check: PassApache-2.0
Pre-Release PR Triagejamiepine/voicebox57k—~3.1kAutomated safety check: PassMIT
WinAppSDK Triage Meeting Prepmicrosoft/WindowsAppSDK4.7k—~2.8kAutomated safety check: PassApache-2.0
Ouroboros Maintainer TriageQ00/ouroboros6.2k—~1.7kAutomated safety check: PassMIT
RTK Issue Triagertk-ai/rtk83k—~3kAutomated safety check: NotesApache-2.0
Verdaccio Issue Triageverdaccio/verdaccio18k—~2.4kAutomated safety check: PassMIT

Similar skills

  • Pre-Release PR Triage

    jamiepine/voicebox

    Sorts a backlog of open pull requests into must-merge, candidate, superseded and deferred, writes a triage doc and works the merge loop before a release.

    57k GitHub stars~3.1k tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • WinAppSDK Triage Meeting Prep

    microsoft/WindowsAppSDK

    Official

    Prepares the triage meeting summary for WinAppSDK Needs-Triage issues, with research-backed area suggestions, draft replies and a diff since the last triage.

    4.7k GitHub stars~2.8k tokensUpdated today
    DevelopmentAuto-check passed
  • Triages and works through GitHub issues and pull requests in the Q00/ouroboros repo as a maintainer, within a stated review boundary and clear limits on what it may change.

    6.2k GitHub stars~1.7k tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • Audits open GitHub issues, categorizes them, flags duplicates and linked PRs in three phases, with optional deep analysis and comments posted only after validation.

    83k GitHub stars~3k tokensUpdated today
    DevelopmentAuto-check: notes
  • Verdaccio Issue Triage

    verdaccio/verdaccio

    Triages an incoming verdaccio/verdaccio issue against the code, the affected release line and related issues, and picks labels from the repository's existing taxonomy.

    18k GitHub stars~2.4k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Official

    Takes a bug report for the triagebot-action GitHub Action through reproduction, root-cause diagnosis, an intended-behavior check and a fix attempt.

    63k GitHub stars~639 tokensUpdated today
    DevelopmentAuto-check passed

More from thedotmack/claude-mem

All 26 skills in this repo
  • Walks you through creating, installing and verifying a custom claude-mem mode, including note types, tags and optional Telegram alerts for chosen memories.

    99k GitHub stars~2.4k tokensUpdated yesterday
    Auto-check passed
  • Pull Request Babysitter

    thedotmack/claude-mem

    Keeps watching a pull request, fixing real review and CI problems and resolving stale threads, until it is clean and ready to merge.

    99k GitHub stars~1.1k tokensUpdated yesterday
    Auto-check passed
  • Claude-Mem Install for Grok Bot

    thedotmack/claude-mem

    Use this when setting up claude-mem on Grok Bot: local worker plus CMEM Pro observer (default), optional host-login observer, or remote cmem.ai. No Cursor…

    99k GitHub stars~440 tokensUpdated yesterday
    Auto-check passed
  • Claude-Mem Cloud Sync

    thedotmack/claude-mem

    Checks claude-mem cloud sync status and guides you through connecting a cmem.ai Pro account without the sync token ever passing through the chat.

    99k GitHub stars~1k tokensUpdated yesterday
    Auto-check: notes
  • Audits a design against Dieter Rams' ten principles of good design, scores each with evidence, and hands off a make-plan prompt for a new, refined or redesigned outcome.

    99k GitHub stars~4.6k tokensUpdated yesterday
    Auto-check passed
  • Session Handoff Document

    thedotmack/claude-mem

    Writes a HANDOFF.md capturing goal, state, files, failed attempts and next steps so a fresh agent session can continue exactly where this one stopped.

    99k GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Issue Backlog Clustering

What does Issue Backlog Clustering do?

Groups a large GitHub issue backlog by root cause into plan-master issues, redirects the child issues, and bundles one PR per cluster that closes them together. Issues are treated as symptoms, and the architectural defect behind them as the real unit of work. In the first pass the agent reads every open issue in full, comment threads included, groups symptoms that share a single fix, and gives each cluster one canonical home: a plan-master issue plus a design document in a plans folder.

When should I use Issue Backlog Clustering?

Issue Backlog Clustering fits situations like: consolidating a tracker that holds dozens of duplicate or related bug reports; building a roadmap from open issues grouped by shared root cause; checking whether a newly filed bug belongs to work that is already planned; shipping one focused PR that resolves a whole cluster of related issues.

How do I install Issue Backlog Clustering in Claude Code?

Run `npx skills add thedotmack/claude-mem --skill oh-my-issues -a claude-code`. Or copy the skill folder (plugin/skills/oh-my-issues in thedotmack/claude-mem) into .claude/skills/oh-my-issues in your project. Claude Code loads it when a task matches its description.

How do I install Issue Backlog Clustering in Codex?

Run `npx skills add thedotmack/claude-mem --skill oh-my-issues -a codex`. Or copy the skill folder (plugin/skills/oh-my-issues in thedotmack/claude-mem) into .agents/skills/oh-my-issues in your project. Codex loads it when a task matches its description.

Can I use Issue Backlog Clustering in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add thedotmack/claude-mem --skill oh-my-issues -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/oh-my-issues, .gemini/skills/oh-my-issues, .github/skills/oh-my-issues and .opencode/skills/oh-my-issues in your project.

What does Issue Backlog Clustering need to run?

Going by SKILL.md and its folder, Issue Backlog Clustering needs the command-line tools its instructions call (gh and jq). Our summary lists: GitHub CLI (gh) with access to the repository's issues.

Does Issue Backlog Clustering access the network?

SKILL.md contains no URLs. Its commands use gh, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Issue Backlog Clustering safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Issue Backlog Clustering use?

Issue Backlog Clustering is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Issue Backlog Clustering use?

About 2.9k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Issue Backlog Clustering?

Skills that share tags, products or a category with Issue Backlog Clustering: Pre-Release PR Triage (jamiepine/voicebox, 57k stars), WinAppSDK Triage Meeting Prep (microsoft/WindowsAppSDK, 4.7k stars), Ouroboros Maintainer Triage (Q00/ouroboros, 6.2k stars) and RTK Issue Triage (rtk-ai/rtk, 83k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Issue Backlog Clustering?

thedotmack (a GitHub user) maintains it in thedotmack/claude-mem, which has 99,047 GitHub stars. The repository holds 26 skills in this directory. The repository was last updated on October 9, 2026.

Source: thedotmack/claude-mem on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.