# Issue scout

Point AM at a repo and it audits the code and **files GitHub issues** — no pull
request, no code change. It's the inverse of [issue solving](/docs/issue-solving):
instead of fixing existing issues, it discovers gaps worth tracking and opens
issues for them.

## Enable it

In **Repo settings → Features** (Pro plan or higher), toggle **Issue scout** on.
The repo's owner must have a [GitHub token](/docs/connect-github) with issue
write access — that's how AM files the issues.

It runs on the repo's normal schedule and respects the spawn interval, so it
takes a scheduled slot like any other run. It only runs when the repo has **no
standing [objective](/docs/objectives)** set.

## How it works

1. A scheduled cycle picks the repo and dispatches an `issue_scout` run.
2. The worker prepares a **read-only worktree** and spawns a single agent with
   the repo's first team role (harness + model).
3. The agent audits the code (docs gaps, untracked TODO/FIXMEs, obvious bugs,
   missing tests, hardening gaps), lists existing issues to avoid duplicates,
   and files up to **5** new issues via `gh issue create`.
4. The run completes with **no branch and no PR** — the issues are the output.
   The dashboard shows the run with an issue count (e.g. *3 issue(s) created*)
   instead of a PR link.

## What it does not do

- **No code changes.** The agent never edits files, commits, pushes, or opens a
  PR. The worktree is read-only and discarded.
- **No runaway.** A single run files at most 5 issues, and the agent is told to
  skip anything that duplicates an existing open issue.

## Gotchas

- **Needs a GitHub token** with issue write on the repo.
- Issues are filed on the **canonical repo** immediately — there's no review
  step before they appear. Start on a repo where that's welcome.
- It shares the schedule/cooldown with normal runs, so a cycle spent scouting is
  a cycle not spent on a code run.

## Related

- [Issue solving](/docs/issue-solving) · [Explore mode](/docs/explore-mode)
- [Trust ladder & plans](/docs/trust-and-plans) · [Connect GitHub](/docs/connect-github)