## No Eligible Issues

Symptoms:

- `roark auto --dry-run` prints no selected issues.
- Scheduled autorun exits without claiming work.

Check:

```bash
gh issue view 123 --repo owner/repo --json labels,state,assignees
```

Common causes:

- issue is closed
- missing ready label, default `afk`
- issue has a skip label
- custom `--label`, `--skip-label`, or `--skip-labels` does not match the repository label policy

Read [Label semantics](label-semantics.md).

## Missing Required Labels

Symptoms:

- dry run reports missing labels
- autorun stops before claiming work

Normal autorun can create required lifecycle labels. Dry run reports missing labels without creating them.

Use a non-dry autorun when you are ready for Roark to create missing required labels, or create labels manually with `gh label create`.

## GitHub Authentication Fails

Symptoms:

- `gh auth status` fails
- scheduled jobs work manually but fail under cron or launchd
- GitHub API calls return permission errors

Check as the same user that runs Roark:

```bash
gh auth status
gh repo view owner/repo
```

For launchd, run under the user's login session so keychain credentials are available. For GitHub Actions, set `GH_TOKEN` and repository permissions.

## Verification Command Missing

Symptoms:

- `auto` or `continue` refuses to publish because no verification command is configured

Fix:

```json
{
  "verify": "bun run check"
}
```

Or pass:

```bash
roark auto --repo owner/repo --verify "bun run check"
```

See [Verification](verification.md).

## Verification Fails Because Ignored Files Are Missing

Symptoms:

- `verification.md` shows missing `.env`, `.secrets`, credentials, generated config, or other ignored files

Fix by copying path names, not secret values:

```json
{
  "workspace": {
    "copyToWorktree": [".secrets/env"]
  }
}
```

The destination must be ignored by Git. See [Managed workspaces](managed-workspaces.md) and [Security and secrets](security-and-secrets.md).

## Dirty Managed Workspace

Symptoms:

- a fresh `auto` run refuses an existing issue workspace
- command output says to use `continue` or clean/remove the workspace

Use:

```bash
roark continue 123 --repo owner/repo
```

If the work is no longer needed:

```bash
roark workspace remove --issue 123 --force
```

Do not remove a workspace if it may contain recoverable uncommitted work.

## Branch Already Exists

Symptoms:

- branch creation or checkout fails
- issue branch already exists locally or remotely

Roark issue branches use:

```text
roark/issue-<number>
```

Inspect:

```bash
git branch --list 'roark/issue-*'
git ls-remote --heads origin 'roark/issue-*'
```

If the branch belongs to a previous attempt, prefer `roark continue`. If it is unrelated, rename or remove it deliberately.

## Readiness Fails

Symptoms:

- `readiness.md` does not contain `ready-for-pr`
- no PR is opened

Open:

```text
.roark/runs/issue/<n>/attempts/<k>/readiness.md
```

Then inspect the latest review and fix logs. Use `continue` after addressing local setup issues.

## PR Not Opened

Common causes:

- readiness failed
- verification failed
- push failed
- GitHub token lacks `contents:write` or pull request permissions
- branch head is not publishable

Inspect `summary.json`, `verification.md`, command output, and GitHub auth state.

## PR Revision Makes No Commit

`revise-pr` does not commit when:

- all feedback is already addressed
- all actionable feedback is classified `needs-human`, `non-blocking`, or `invalid/stale`
- verification fails
- the working tree is dirty and preflight refuses to continue

See [PR revisions](pr-revisions.md).

## Scheduler Runs Overlap

Symptoms:

- issue claiming races
- dirty workspace surprises

Use scheduler-level serialization:

- `flock` for cron
- `concurrency` for GitHub Actions
- one launchd job per control checkout

See [Scheduling](scheduling.md) and [Operations runbook](operations-runbook.md).

## Useful First Files

For issue attempts:

```text
.roark/runs/issue/<n>/attempts/<k>/summary.json
.roark/runs/issue/<n>/attempts/<k>/verification.md
.roark/runs/issue/<n>/attempts/<k>/readiness.md
.roark/runs/issue/<n>/attempts/<k>/events.jsonl
```

For PR revisions:

```text
.roark/runs/pr/<pr-number>/revision-<n>/
```

See [Artifacts](artifacts.md).