combine-issues

Files (1)

• SKILL.md

SKILL.md (first lines)

**MANDATORY: Follow the complete shared lifecycle contract in `${CLAUDE_PLUGIN_ROOT}/skills/shared/run-lifecycle.md` with declared skill `combine-issues`.**

# Combine Issues

**MANDATORY: READ ENTIRE FILE before composing user-facing prose: `${CLAUDE_PLUGIN_ROOT}/skills/shared/readability-style.md`.**

Reduce open issue count by merging related issues into combined ones. The primary goal is saving tokens — fewer, broader issues mean fewer `/design` + `/implement` execution cycles and less duplicated context loading.

## Flags

| Flag | Default | Purpose |
|------|---------|---------|
| `--oos` | off | OOS mode: operate only on open issues with a `[OOS]` title prefix. Checks each item for actuality and merit, discards stale items, stages low-merit rejections for approval, then proposes an aggressive combination scheme. See **OOS Mode** section below for the full step flow. |

When `--oos` is present, skip the standard Steps 1–3 below and follow the **OOS Mode** section instead.

## When to Combine

Good candidates share at least one of:

- **Same code area** — multiple issues touching the same file(s) or module.
- **Similar change pattern** — issues applying analogous edits to different files (e.g., "add error handling to script A" + "add error handling to script B").
- **Overlapping scope** — one issue is a subset of another, or both contribute to the same goal.
- **Sequential dependency** — issues that must land in order and are small enough to ship as one unit.

Do NOT combine issues that are genuinely independent and benefit from separate review (e.g., a bug fix and an unrelated feature).

## Session Temp Directory

Before writing any body files, create a unique temp directory for this run:

```bash
COMBINE_TMPDIR=$(mktemp -d)
```

Use `$COMBINE_TMPDIR/` for all body temp files. Never write to a hardcoded `/tmp/<name>` path; those paths collide when a prior run left a file at the same location.

<!-- step:1 — Fetch Eligible Issues -->

```bash
CLAUDE_PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT" "${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" combine-issues fetch
```

The helper fetches at most the 100 most recent open issues before title-prefix filtering. This is the complete candidate window for both standard and OOS modes. Title-prefix filtering and its Rust parity coverage live in `crates/larch-cli/src/combine_issues_commands.rs`.

Parse `ISSUES_FILE` and `COUNT` from stdout. If `COUNT=0`, print `No open issues eligible for combination.` and stop.

Read the JSON file at `$ISSUES_FILE` to get the full issue list (number, title, body, labels).

<!-- step:2 — Analyze and Propose Groups -->

Read each issue's title and body. Identify groups of 2+ issues that meet the combination criteria above. For each proposed group:

1. List the source issue numbers and titles.
2. State the combination rationale (which criterion from "When to Combine" applies).
3. Draft a combined title and a combined body that preserves all actionable content from the source issues.

Present all proposed groups to the user in a numbered list. If no groups are identified, print `No combination candidates found among <COUNT> open issues.` and stop.

Ask the user which groups to apply (e.g., "all", "1,3", or "none").

<!-- step:3 — Apply Approved Combinations -->

For each approved group, write the combined body to `$COMBINE_TMPDIR/group-<N>.md`, then invoke:

```bash
CLAUDE_PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT" "${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" combine-issues apply \
  --title "<combined title>" \
  --body-file "$COMBINE_TMPDIR/group-<N>.md" \
  --source-issues "<comma-separated issue numbers>" \
  --operator-invoked
```

Parse `COMBINED_ISSUE` and `CLOSED_ISSUES` from stdout. Print a summary line per group: `Combined #X, #Y, #Z → #<new> (<N> issues closed)`.

After all groups are applied, print a final tally: `Done — <N> issues combined into <M>, net reduction: <N-M>`.

## OOS Mode (`--oos`)

Operates only on open issues whose title starts with the `[OOS]` prefix followed by a space (prefix match, not substring). Fetches them, checks actuality and merit item-by-item, discards stale items, stages low-merit rejections for approval, and proposes an aggressive combination.

Resolve the target repository once before OOS commands that require `--repo`:

```bash
# lint-consecutive-bash: ok repo resolution and tempdir setup are separate documented setup steps
REPO=$("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" gh resolve-repo 2>/dev/null || true)
if [ -z "$REPO" ]; then
  REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null || true)
fi
if [ -z "$REPO" ]; then
  echo "Could not determine repository."
  exit 1
fi
```

Create a unique temp directory for body files and state files for this run:

```bash
COMBINE_TMPDIR=$(mktemp -d)
```

Set these variable paths under `$COMBINE_TMPDIR` before running any OOS step:

- `SOURCE_TO_COMBINED_JSON=$COMBINE_TMPDIR/source-to-combined.json`
- `COMBINED_ISSUES_JSON=$COMBINE_TMPDIR/combined-issues.json`
- `BLOCKED_SOURCES_JSON=$COMBINE_TMPDIR/blocked-sources.json`
- `WRITE_RESULTS_JSON=$COMBINE_TMPDIR/write-results.json`
- `EXCEPTION_DECISIONS_JSON=$COMBINE_TMPDIR/exception-decisions.json`
- `DEPS_JSON=$COMBINE_TMPDIR/deps.json`
- `OPEN_ISSUES_JSON=$COMBINE_TMPDIR/open-issues.json`
- `INHERITED_PLAN_JSON=$COMBINE_TMPDIR/inherited-plan.json`
- `REFRESHED_OPEN_ISSUES_JSON=$COMBINE_TMPDIR/open-issues-refreshed.json`
- `FINAL_INHERITED_PLAN_JSON=$COMBINE_TMPDIR/inherited-plan-final.json`
- `AUDIT_OPEN_ISSUES_JSON=$COMBINE_TMPDIR/audit-open-issues.json`
- `EXISTING_EDGES_JSON=$COMBINE_TMPDIR/existing-edges.json`
- `DECIDED_EDGES_JSON=$COMBINE_TMPDIR/decided-edges.json`
- `PROSE_CANDIDATES_JSON=$COMBINE_TMPDIR/prose-candidates.json`
- `TIER2_CANDIDATES_JSON=$COMBINE_TMPDIR/tier2-candidates.json`
- `CLOSE_ELIGIBLE_JSON=$COMBINE_TMPDIR/close-eligible.json`

From character-ai/larch, MIT.

More from character-ai/larch