# Issue solving

Point AM at your GitHub issues and it fixes them: it discovers open issues, picks
the highest‑value one, implements a fix on its own branch, runs the
[Verification Gate](/docs/verification-gate), and opens a PR that closes the issue.

## Enable it

In **Repo settings → Issue solving** (Pro plan or higher):

- **Issue solving** — toggle on.
- **Solutions per issue** — how many independent attempts to spawn per issue
  (Pro = 1; Max = up to 3; Enterprise up to 5). Each solution uses a different
  approach (minimal → refactored → test‑driven) on its own branch.

A [verify command](/docs/verification-gate) is strongly recommended — it's what
makes a generated fix trustworthy.

## How it works

1. **Sync** — AM pulls open issues from GitHub into a candidate queue, scored by
   signal (bug label, help‑wanted, comment activity). Pull requests are skipped;
   issues closed on GitHub are retired from the queue automatically.
2. **Select** — the scheduler (or you, manually) picks the top‑scored open
   candidate. A standing repo [objective](/docs/objectives) takes priority over
   issue solving.
3. **Solve** — an agent team implements the fix with the issue context in focus,
   commits, and the [gate](/docs/verification-gate) must pass.
4. **PR** — a pull request opens with **`Fixes #N`** in the body, so merging it
   auto‑closes the issue. The cap (`solutions_target`) stops AM after the
   configured number of attempts — no runaway.

## Manual control

- `POST /api/repos/{id}/issues/sync` — refresh the candidate queue.
- `GET /api/repos/{id}/issues` — list candidates.
- `POST /api/issues/{id}/run` — solve one now.
- `POST /api/issues/{id}/reject` — skip a candidate.

(Or drive it from the CLI / an agent — see the [Agent cheatsheet](/docs/agent-cheatsheet).)

## Issue filter

By default every open issue is a candidate, except those carrying a skip label
(`am-skip`, `am-hold`, `do-not-treat`, `wontfix`, `blocked`, `on-hold`). Open
**Repo settings → Automation → Issue candidates → Issue filter** to narrow the
queue further (mirrors the [PR watcher](/docs/pr-watcher) policy):

- **Include labels** — keep only issues carrying at least one (e.g. `bug`, `good first issue`).
- **Exclude labels** — drop issues carrying any (on top of the skip labels).
- **Authors** — keep only issues opened by these logins.
- **Min comments** — require at least N comments (a rough "has discussion" signal).
- **Max age (days)** — keep only issues created within the last N days.

Filters are applied at sync time, work the same for GitHub and GitLab, and can
only *tighten* the queue. An issue that no longer passes is marked `skipped`; it
returns automatically once it matches again (or the filter is relaxed). The
filter is stored on the repo as the `issue_solve_policy` JSON field — settable
via `PATCH /api/repos/{id}` for automation.

## Gotchas

- **Needs a GitHub token** on your account (for sync + opening PRs).
- **Solutions cap is per issue.** Once `solutions_target` attempts are spawned the
  candidate is marked done — it won't be re‑solved unless you re‑open/re‑sync.
- A red gate yields a **draft** PR (it never merges unverified work).
- Auto‑merge of the resulting PR follows the [trust ladder](/docs/trust-and-plans)
  (Max + repo auto‑merge on).

## Related

- [The Verification Gate](/docs/verification-gate) · [PR watcher](/docs/pr-watcher)
- [Trust ladder & plans](/docs/trust-and-plans)