Automatic issue-to-PR flow

ClawSweeper can open a narrow implementation pull request for some issues. It does not do that merely because an issue was reviewed. A review is an evidence step; a separate intake path must decide that the issue is safe and specific enough to attempt.

Use this guide to answer two maintainer questions:

Why did this issue receive a ClawSweeper implementation status comment or a

generated PR?

Why did another apparently similar issue remain review-only?

For the complete repair architecture, see the repair overview and internal feature map.

#The short version

An issue can enter implementation in either of two ways:

A maintainer explicitly asks on the open issue with @clawsweeper implement,

@clawsweeper fix, @clawsweeper build, @clawsweeper create pr, or @clawsweeper fix issue.

Scheduled candidate selection finds an already-reviewed issue that meets the

configured automatic-admission rules.

Both routes create or reuse one durable issue-implementation job. The repair worker then rechecks the issue and current main, plans and validates a narrow change, and only then may push a branch and open or update a PR. A blocked worker leaves a status/result record instead of publishing a speculative PR.

Normal @clawsweeper review and @clawsweeper re-review requests are review-only. They can supply the report that automatic selection later reads, but they do not directly request implementation.

#What happens after an issue is selected

open issue
  -> review report or maintainer implementation command
  -> separate intake checks
  -> durable job + queued status comment
  -> autonomous repair worker
  -> latest-main, safety, validation, and review checks
  -> branch + generated PR, or a blocked result

The durable job uses a branch shaped like:

clawsweeper/issue-<owner>-<repo>-<issue-number>

The branch and job make retries idempotent: ClawSweeper should resume or update the same implementation effort rather than start a second PR for the issue.

Generated issue PRs are labeled clawsweeper:autogenerated and enter the bounded clawsweeper:autofix review/fix loop. They remain open for a human to merge; issue-generated PRs do not automerge.

#Automatic selection routes

Scheduled selection is intentionally narrower than a general "fix every bug" rule. The receiver workflow is sweep.yml and the admission implementation is src/repair/issue-implementation-intake.ts.

Candidate route	Where it can run	Required enablement	Extra evidence required
Strict reproducible bug	`openclaw/openclaw`	`CLAWSWEEPER_AUTO_IMPLEMENT_ISSUES=1` and `CLAWSWEEPER_AUTO_IMPLEMENT_REPRO_BUGS=1`	High-confidence reproduced bug; no feature/config expansion; a high-confidence `queue_fix_pr` recommendation, repair prompt, and validation plan
Vision-fit issue	`openclaw/openclaw`	`CLAWSWEEPER_AUTO_IMPLEMENT_ISSUES=1` and `CLAWSWEEPER_AUTO_IMPLEMENT_VISION_FIT=1`	Clear VISION alignment, small implementation complexity, evidence, repair prompt, and validation plan
Viable reviewed issue	Supported targets other than `openclaw/openclaw` and `openclaw/clawhub`	`CLAWSWEEPER_AUTO_IMPLEMENT_ISSUES=1` plus target App write access	A completed `keep_open` issue review with no product-decision, protection, pause, security, or duplicate-PR blocker

The scheduled route is capacity-bounded. It selects only a small configured number of candidates per sweep and waits for the issue-implementation worker lane to have capacity. See Scheduler and Automation limits.

#Why an issue is rejected

Scheduled intake refuses a candidate when the completed review does not say keep_open, requires a product decision, lacks the route's required evidence, or has protected, pause, security-sensitive, duplicate, or linked-PR signals. It also refuses an existing implementation job, generated branch PR, or related work-cluster PR. Candidate discovery skips a prior intake audit only when it matches the current review snapshot, so a materially re-reviewed issue can be considered again.

An explicit maintainer command does not require that completed review report. Instead, the router first requires an authorized requester and an open issue, then refuses a pause label or existing linked PR before it creates or reuses the durable job. The later repair worker can still block the attempt if the issue is no longer open, has clawsweeper:human-review or clawsweeper:manual-only, the work is unsafe or already fixed, or it cannot validate a small, reviewable change on current main.

Automatic-intake pause labels are admission checks. Adding one after a job is queued does not by itself guarantee that an already-running worker will stop; use the human-review or manual-only pause for the execution-time stop guard.

The worker rechecks that the source issue remains open and unpaused immediately before it pushes. If current-main verification shows that the request is already fixed, unsafe, or cannot be validated, the correct outcome is a blocked result—not a PR.

#Maintainer commands versus automatic selection

An implementation command is an explicit maintainer request, not proof that a PR will be opened. The comment router verifies the commenter’s association or repository permission, requires an open issue, refuses linked PRs and pause labels, then creates or reuses the same durable job used by automatic intake.

@clawsweeper review and @clawsweeper re-review are different commands: they dispatch a fresh issue/PR assessment and publish review state. They do not create an implementation job. A later scheduled candidate pass may decide that the resulting report is eligible, which can make review activity appear to have started PR work even though the decision was a separate transition.

The full command behavior is documented in Repair operations.

#Execution gates and credentials

Even an eligible, queued job cannot open a PR without all of these controls:

CLAWSWEEPER_ALLOW_EXECUTE=1 enables deterministic write execution;
CLAWSWEEPER_ALLOW_FIX_PR=1 permits branch and PR publication;
the job itself must allow fix and raise_pr and set allow_fix_pr: true;
the GitHub App must be installed with target-repository contents and pull

request write permission;

deterministic validation and internal review must accept the prepared fix.

The Codex planning step does not receive a GitHub write token. Dedicated queueing and planning-status steps use narrowly scoped issue-write tokens; the deterministic executor owns the short-lived App token for branch push, PR creation, and labels. The worker workflow and executor are repair-cluster-worker.yml and src/repair/execute-fix-artifact.ts.

CLAWSWEEPER_ALLOW_MERGE and CLAWSWEEPER_ALLOW_AUTOMERGE do not turn an issue-generated PR into an automatic merge: that lane intentionally leaves its PR open for maintainer review.

#How to investigate one issue

For automatically selected issues, start with the durable review report in the state repository:

records/<owner>-<repo>/items/<issue-number>.md

Then look for the corresponding intake audit and job:

results/issue-implementation-intake/<owner>-<repo>/<issue-number>.md
jobs/<owner>/inbox/issue-<owner>-<repo>-<issue-number>.md

The intake audit records the candidate route and the first blocker. If a job exists, the repair issue implementation intake Actions run records the queueing decision, and the repair cluster worker run records whether the worker stopped, updated an existing branch, or opened a PR.

For a maintainer-command request, start with the command comment and its ClawSweeper status reply, then inspect results/comment-router.json and the same durable job path. This route creates the job directly, so it does not require a review report or write an issue-implementation intake audit.

For target setup and App-installation prerequisites, see Target repositories. For existing contributor PR adoption, replacement, and automerge behavior, see Automerge flow rather than treating it as issue-generated PR behavior.