---
title: Reconcile a backlog and plan reviews
description: Find backlog items to verify, review suggested actions, check coverage, compare competing PRs, and get an ordered queue of reviews.
url: "https://issue-graph.dev/docs/backlog"
docs_index: /llms.txt
lastUpdated: "2026-09-27T00:00:00.000Z"
navTitle: "Reconcile and plan"
canonical_url: "https://issue-graph.dev/docs/backlog"
---

# Reconcile a backlog and plan reviews

> For an index of all documentation, see [/llms.txt](/llms.txt).

## Reconcile an open backlog

`reconcile` finds a repository's open issues and PRs, follows their references, and suggests an action for each item. The repository doesn't need labels.

```bash
issue-graph reconcile owner/repo --format markdown
issue-graph reconcile owner/repo --format json --no-save
```

Replace `owner/repo` with a repository you can read. Without `--format`, output is Markdown in a terminal and JSON in a pipe.

The report lists counts, ordered items, supporting evidence, crawl limits, history, and next steps. Each evidence entry has a stable `code`, a `summary`, and `related` node keys that scripts can read.

## Review suggested actions

| Action                | What to check                                                               |
| --------------------- | --------------------------------------------------------------------------- |
| `verify-completed`    | Current behavior and acceptance criteria for an issue linked to merged work |
| `close-superseded`    | Scope coverage and contributor credit                                       |
| `verify-superseded`   | Whether the merged implementation covers the older PR                       |
| `resolve-competing`   | Differences between competing PRs                                           |
| `repair-closing-link` | A closing claim missing its GitHub relationship                             |
| `review-open-pr`      | Code and checks on the latest PR head                                       |
| `keep-linked`         | Related work still active                                                   |
| `keep-untracked`      | Reproduction and evidence needed to prioritize the issue                    |

Reconcile only reads GitHub and builds this review queue. You close issues, merge PRs, and post comments yourself after you verify each item.

## Check coverage

Seed discovery paginates GitHub search until it reaches `--budget` or GitHub's 1000-result search ceiling. The node cap defaults to 80, and you can set it from 1 to 1000. Depth, hub, concurrency, and per-node limits also apply.

Inspect `limits.seedLimitReached`, `limits.cappedOut`, and `limits.fetchFailures` before you trust the queue. Depending on which limit you hit, increase the budget, re-seed the missing neighborhood, or retry the access failure. See [Graph](/docs/graph) for the per-node limits that apply at every node cap.

## Compare history

Reconcile saves each report under `~/.issue-graph/reconcile-owner-repo/`. History is keyed by repository, so it can track changes even when the open seed list changes or becomes empty.

Each comparison lists added, changed, and resolved actions, plus coverage changes. When coverage is incomplete, the comparison leaves out new or resolved claims it can't support. `--no-save` skips saving the new report but still compares against an existing baseline.

## Plan the next action

```bash
issue-graph plan owner/repo --format markdown
issue-graph plan owner/repo --format json
```

`plan` runs reconciliation and groups the results into:

- ready actions
- items needing investigation
- blocked work, including drafts, conflicts, and active related work

When coverage permits, it selects one `next` action and adds a structured `decision` for that item and its related work.

Cleanup and verification come before implementation review. Within each group, readiness, discussion activity, and visible inbound references set the order. The same evidence and evaluation time always produce the same order.

If open seeds are missing or a neighborhood hit the node cap, the queue is provisional and `plan` omits `next`. A failed neighbor reference affects only the items related to it.

## Compare competing PRs

For competing PRs, `decision` compares draft state, reviews, mergeability, diff size, file counts, and update times. `reviewFirst` names a PR to start inspecting. Check the code, CI, and review threads before you choose an implementation.

`blockedBy` uses the GitHub relationships visible in the capture. Run `plan` again after a merge or closure to refresh the queue.

## Find work one fix resolves

The plan's `sweep` groups list open work that one decision can resolve together:

- `competing`: an issue with two or more open closing PRs
- `stale`: an open PR whose modified files are all gone from the default branch
- `overlap`: each open PR paired with the PR it shares the most source files with, when the two close no common issue. Shared files weigh more when fewer other open PRs touch them.

Each PR reports `staleBase`, which is `true` when every file it modifies or deletes is gone from the default branch. Use `--budget 1000` to include older backlog items.

Each group names its `next` step: `verify` to run the issue's repro on the current release, `choose` to pick one implementation, or `compare` to read both PRs. `verify` groups, where every PR is stale, come first because they usually need verification on the current release rather than new code.

Treat a group as a lead to investigate. Reproduce the issue on the current release before you close anything.

`plan` saves no snapshots. Use `--format json` for structured output. HTML export is available in graph mode. See [Command reference](/docs/reference) for output formats.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)